포트폴리오 및 계정 상태
SDK와 CLI 전반에서 통합 계정 상태, 출금 가능 잔액, 수수료 일정, 확장된 포지션 정보, 포트폴리오 시계열을 다룹니다.
포트폴리오 엔드포인트는 계정에 대한 네 가지 질문에 답합니다. 지금 가치가 얼마인지, 무엇을 출금할 수 있는지, 수수료가 얼마인지, 시간에 따라 성과가 어땠는지입니다. 이들은 소수의 인증된 REST 엔드포인트와 포지션별로 확장된 리스크 필드로 구성됩니다. 모든 인터페이스(Rust, TypeScript, Python SDK와 CLI)는 API 및 요청 한도에 문서화된 게이트웨이의 동일한 경로에 접근합니다.
포트폴리오 화면을 구축한다면, 무엇이든 렌더링하기 전에 값을 안전하게 읽는 방법을 읽으십시오. 여러 필드가 의도적으로 null이 될 수 있고, 부호 규칙 하나는 뒤집기 쉬우며, 두 번 호출하는 단순한 구현은 프로덕션에서 경합 조건(race condition)에 부딪힙니다.
설치
npm install @nexus-xyz/exchange-ts # TypeScript
cargo add nexus-exchange # Rust
pip install nexus-exchange # PythonCLI는 nexus-exchange-cli 릴리스로 배포됩니다. 모든 클라이언트는 SDK 및 도구를 참조하십시오.
인증
이 페이지의 모든 경로는 계정 범위이며 HMAC API 키가 필요합니다. 공개 또는 인증 없는 버전은 없습니다. 요청에는 X-API-Key, X-Timestamp, X-Signature가 포함되며, 타임스탬프는 서버 시간과 30초 이내로 차이가 나야 합니다. SDK와 CLI가 서명을 대신 처리합니다. 실행 가능한 cURL을 포함한 전체 흐름은 빠른 시작에 있습니다.
API 시크릿은 소스 코드와 셸 기록에 남기지 마십시오. 시크릿은 생성 시 한 번만 표시되며 나중에 다시 조회할 수 없습니다. 아래 예시는 시크릿을 환경 변수에서 읽습니다.
네트워크 선택
거래소는 현재 Nexus Testnet에서 운영되며, 메인넷이 뒤따를 예정입니다. 클라이언트를 생성할 때 네트워크를 선택하십시오. 각 인터페이스의 선택 방법과 API 키가 네트워크에 바인딩되는 방식은 네트워크를, 현재 기본 URL은 API 및 요청 한도를 참조하십시오. 이 경로들이 요구하는 HMAC 키는 키가 생성된 네트워크로 범위가 한정됩니다.
레퍼런스
GET
/account/state
HMAC
하나의 일관된 읽기에서 가져온 포트폴리오 요약 및 모든 미결제 포지션
GET
/account/summary
HMAC
포트폴리오 요약만 제공하며, /account/state에 포함된 것과 같은 객체
GET
/account/fees
HMAC
계정에 적용되는 실효 수수료 일정
GET
/account/portfolio-history?window=&limit=
HMAC
총자산, 누적 손익, 누적 거래량 시계열
SDK별 진입점:
Rust
fetch_account_state()
fetch_account_fees()
fetch_portfolio_history(window, limit)
Python
fetch_account_state()
fetch_account_fees()
fetch_portfolio_history(window, limit)
TypeScript
getAccountState()
getAccountFees()
getPortfolioHistory({ window, limit })
CLI
nexus account state
nexus account fees
nexus account portfolio-history --window --limit
통합 계정 상태
GET /account/state는 서버 측 한 번의 읽기로 구성한 포트폴리오 집계와 모든 미결제 포지션을 반환합니다. 두 부분이 같은 스냅숏에서 나오므로 summary.open_positions_count는 항상 positions의 길이와 같습니다.
요약에는 collateral, total_equity, total_unrealized_pnl, total_realized_pnl_24h, total_volume_24h, open_positions_count, open_orders_count, margin_used, available_margin, withdrawable이 포함됩니다.
withdrawable은 계정에서 빠져나갈 수 있는 잔액으로, 엔진이 권위 있게 산출한 여유 증거금을 0 이상으로 제한한 값인 max(0, available_margin)입니다. 여유 증거금은 이미 각 포지션의 개시 증거금과 모든 거래 전 주문 예약분을 총자산에서 차감한 값이므로, 이것이 출금이 끌어 쓸 수 있는 금액입니다. total_equity도 아니고 collateral도 아닙니다. 손실 상태의 계정은 "0"으로 제한되며 절대 음수로 보고되지 않습니다. 이 값은 권위 있는 증거금 뷰에서 나오므로, 그 뷰를 사용할 수 없을 때 엔드포인트는 로컬에서 추정한 숫자를 반환하지 않고 502를 반환하는 실패 시 차단(fail closed) 방식으로 동작합니다.
수수료 일정
GET /account/fees는 거래소가 현재 계정에 부과하는 수수료를 보고합니다. 이는 향후 적용될 일정 요율이며, 과거 체결의 실현 평균이 아닙니다.
maker_fee_bps
대표 베이시스 포인트. 음수일 수 있으며, schedule=unknown일 때 0은 센티널 값입니다
taker_fee_bps
대표 베이시스 포인트. schedule=unknown일 때 0은 센티널 값입니다
tier
현재 항상 base이며, 아직 계정별 등급은 없습니다
schedule
per_market, reference, unknown 중 하나이며, 새 값이 추가될 수 있는 문자열로 취급하십시오
markets
보존된 체결 버퍼에 있는 시장의 요율이며, market_id 순으로 정렬됩니다
volume_30d
최근 30일 롤링 거래 명목 가치, 10진수 문자열. 최선 노력(best-effort) 방식의 값이며, 아래 플래그를 참조하십시오
volume_30d_estimated
volume_30d가 과소 집계되었을 수 있을 때 true(원천 체결 버퍼가 용량 한도에 도달함)
discounts
적용 중인 할인. 현재 항상 비어 있습니다
schedule이 per_market이면 반환된 markets 행을 권위 있는 요율로 사용하십시오. 최상위 쌍은 그 행들의 결정론적 최빈값 요약일 뿐입니다. 용량이 제한된 메모리 내 체결 버퍼는 초기화되거나 오래된 시장을 제거할 수 있으므로, 행이 없다고 해서 계정이 해당 시장에서 거래한 적이 없다는 증거는 아닙니다. reference는 보존된 버퍼에 일정이 미러링된 시장이 없으며, 최상위 쌍이 미러링된 모든 거래소 시장에 걸친 결정론적 최빈 요율이라는 뜻입니다. 두 최빈값 계산 모두 출현 횟수가 가장 많은 쌍이 선택되며, 동률이면 사전순으로 가장 작은 (maker_fee_bps, taker_fee_bps) 쌍으로 결정됩니다. unknown은 시장 파라미터를 사용할 수 없다는 뜻입니다. markets는 비어 있고 두 대표 bps 값은 무료 수수료 일정이 아니라 0 센티널 값입니다. 현재 계정별 등급이나 할인 프로그램은 존재하지 않습니다. schedule을 확장 가능한 값으로 취급하고, 존재하지 않는 할인 구조에 따라 분기하지 마십시오.
포트폴리오 시계열
GET /account/portfolio-history는 한 기간 동안의 총자산, 누적 거래 손익, 누적 거래 명목 가치를 서버 측에서 다운샘플링하여 반환합니다. 데이터 포인트는 오래된 순서입니다.
window
간격
최대 포인트 수
기간
day
5분
288
24시간
week
1시간
168
7일
month
6시간
120
30일
all
1일
366
약 1년
window를 생략하면 day가 적용됩니다. 이 집합 밖의 값은 400(invalid_window)으로 거부됩니다. 파라미터가 반복되면 첫 번째 값이 사용됩니다. limit은 1에서 366 사이여야 합니다. 이 범위 안에서는 결과를 좁히며, 거부되지 않고 해당 기간의 용량에 맞게 상한 처리(clamp)됩니다. 따라서 day에 366개 포인트를 요청하면 오류가 아니라 288개가 반환됩니다. 이 범위를 벗어나면 요청은 400으로 거부됩니다.
응답은 실제로 제공된 window와 cadence_ms를 되돌려 줍니다. 보낸 값을 가정하지 말고 이 값을 다시 읽어 차트 축에 제공된 값이 반영되도록 하십시오.
각 포인트에는 timestamp_ms, equity, pnl, volume이 포함됩니다. pnl과 volume은 구간별 값이 아니라 해당 샘플까지의 누적값입니다. 구간별 활동을 차트로 그리려면 인접한 포인트 간의 차이를 직접 계산하십시오.
확장된 포지션 필드
/account/state(및 /positions)가 반환하는 포지션에는 symbol, side, size, entryPrice, unrealizedPnl, realizedPnl과 함께 포지션별 리스크 세부 정보가 포함됩니다.
notional
abs(size) × mark price
initialMargin
교차 마진 모델에서 해당 포지션에 대해 보유하는 개시 증거금
roe
개시 증거금 대비 수익: unrealizedPnl / initialMargin
max_leverage
시장의 리스크 파라미터에 따른, 해당 시장이 허용하는 최대 레버리지
leverage
이 포지션에 대한 계정의 레버리지 배수
funding_paid
포지션의 누적 펀딩. 아래의 부호 규칙을 참조하십시오
필드 이름은 CCXT의 통합 어휘이므로 ccxt.nexus() 클라이언트가 이 구조를 그대로 읽습니다. CCXT에 대응 항목이 없는 필드는 거래소 고유의 표기를 유지합니다: size, roe, max_leverage, funding_paid. GET /account는 이 구조가 아닙니다. 이 엔드포인트는 매칭 엔진에서 중계되며, 엔진 고유의 이름으로 더 좁은 객체를 응답합니다.
서버는 매칭 엔진까지 왕복하지 않고 저지연 읽기 경로에서 이 값들을 계산하므로 엔드포인트가 빠르게 유지됩니다. 그 대가로, 입력값 중 하나를 그 경로에서 사용할 수 없으면 필드는 null이 되고, 짝이 되는 <field>_error가 지어낸 숫자 대신 기계가 읽을 수 있는 사유를 담습니다.
leverage는 현재 항상 null이며, leverage_error는 margin_state_not_mirrored로 설정됩니다. 이 값을 도출하려면 계정의 레버리지 설정 또는 할당된 증거금이 필요한데, 둘 다 읽기 경로에서 사용할 수 없습니다. initialMargin으로부터 재구성하지 마십시오. 그 식은 1 / initial_margin_rate로 축약되는데, 이는 포지션의 실제 레버리지가 아니라 시장별 상수이므로 해당 시장의 모든 포지션에 대해 틀린 값이 됩니다.
funding_paid는 지불 시 양수입니다. 양수 값은 포지션이 펀딩을 지불했다는 뜻이고, 음수 값은 펀딩을 받았다는 뜻입니다. 이 필드는 항상 존재하며, 펀딩이 발생하기 전에는 "0"이고, 거래소가 보존하는 펀딩 이력의 범위 내로 제한됩니다. 이 부호를 뒤집으면 손익 화면에서 비용이 수입으로 바뀌므로, 이에 대한 테스트를 작성하십시오.
값을 안전하게 읽는 방법
금액 값은 숫자가 아니라 10진수 문자열입니다. equity, pnl, volume, withdrawable, notional 등은 손실 없이 표현되도록 문자열로 직렬화된 임의 정밀도 10진수입니다. 10진수 타입으로 파싱하십시오. 부동소수점(parseFloat, float(), as f64)을 거치면 문자열 인코딩이 막으려는 반올림 오차가 다시 생깁니다. 레버리지 필드(leverage, max_leverage)는 실제 JSON 숫자입니다.
파생 필드에는 두 가지가 아니라 세 가지 상태가 있습니다. 계산되는 다섯 개의 포지션 필드(notional, initialMargin, roe, leverage, max_leverage)는 각각 다음 중 하나일 수 있습니다.
값: 계산되었으며 권위 있는 값;
null: 보고되었지만 계산할 수 없으며, 짝이 되는<field>_error가 사유를 알려 줌;없음: 서버가 해당 필드보다 이전 버전임.
이 중 어느 것이든 0으로 뭉뚱그리면 데이터를 지어내는 것입니다. "보고되지 않음", "계산할 수 없음", "0"은 자신의 포지션 가치가 얼마인지 묻는 사용자에게 주는 서로 다른 세 가지 답이며, 그중 숫자는 하나뿐입니다. 누락된 경우는 명시적인 공백으로 렌더링하고(CLI는 -를 출력합니다), <field>_error가 있으면 함께 표시하십시오. withdrawable에도 같은 원칙이 적용됩니다. 이 필드는 스키마에서 선택 사항이므로 이전 배포에서는 생략될 수 있으며, 이를 "0"으로 기본 처리하면 서버가 값을 보고한 적이 없는데도 사용 가능한 금액이 없다고 알리게 됩니다.
이 다섯 개가 바로 짝이 되는 <field>_error를 가진 필드입니다. funding_paid는 여기에 포함되지 않습니다. 항상 존재하므로 분기할 funding_paid_error가 없습니다.
두 번 호출하기보다 /account/state를 사용하십시오. /account/summary와 /positions를 따로 가져오는 것은 거래가 진행 중인 계정에 대한 두 개의 독립된 요청입니다. 그 사이에 체결이 발생하면 포지션 목록과 맞지 않는 집계가 반환되며(open_positions_count는 3인데 배열에는 4개가 있음), 이는 실제 부하 상황에서는 언제든 일어납니다. 통합 엔드포인트는 두 부분을 하나의 일관된 읽기로 뒷받침합니다.
실패 코드를 구분해서 처리하십시오. 401은 자격 증명 또는 시계 문제입니다. 키가 잘못되었다고 가정하기 전에 X-Timestamp가 서버 시간과 30초 이내인지 확인하십시오. 429는 요청 한도 예산을 초과했다는 뜻입니다. 요청 한도를 참조하고, 즉시 재시도하지 말고 백오프하십시오. 이 페이지의 세 경로(/account/summary, /fills, /account/portfolio-history)는 각각 해당 예산에서 1단위가 아닌 5단위를 소모하므로, 짧은 주기로 폴링하면 요청 횟수로 짐작하는 것보다 5배 빠르게 Pro 호출자의 초당 20회 허용량을 소진합니다. /account/state는 1단위를 소모하면서 요약과 포지션을 함께 반환하므로 둘 다 읽는 더 저렴한 방법입니다. /account/state와 /account/summary의 502는 권위 있는 증거금 뷰에 연결할 수 없어 서버가 추측을 거부했다는 뜻입니다. 재시도하되, 로컬에서 계산한 withdrawable로 대체하지 마십시오.
예시
위 숫자들은 서로 일관됩니다. 마크 가격이 86000일 때 notional은 0.25 × 86000, unrealizedPnl은 0.25 × (86000 − 84000), initialMargin은 notional × 1/max_leverage, roe는 unrealizedPnl / initialMargin이며, 증거금을 예약하는 미체결 주문이 없으므로 withdrawable은 요약의 total_equity − margin_used와 같습니다. 마지막 구절의 두 가지 표기에 유의하십시오. SUMMARY 객체의 margin_used는 계정 집계값이며 그 이름을 유지합니다. 포지션의 initialMargin은 포지션별 요구 증거금입니다.
실행 가능한 엔드투엔드 예시는 SDK 저장소에 있습니다: examples/portfolio.ts, examples/portfolio.rs.
관련 문서
상태: 테스트넷의 개발 프리뷰입니다. 이 경로들은 OpenAPI 사양 v0.7.2에 포함되었으며 v0.9.90에서도 최신 상태입니다. 프로덕션에서는 사양 버전을 고정하고, 업그레이드 전에 각 SDK의 릴리스 노트를 확인하십시오.
/account/fees에는 현재 계정별 등급이나 할인 프로그램이 없으며,leverage는 필요한 증거금 상태가 미러링될 때까지null을 보고합니다. 테스트넷 자격 증명과 잔액에는 실제 가치가 없습니다.
마지막 업데이트