개인 이벤트 스트림

wss://api-ws.btxpro.co.kr/v1/user/stream

read 권한으로 서명된 업그레이드를 수행합니다. 구독 명령 없이 초기 상태와 후속 이벤트를 받습니다. 같은 연결에서 trade 권한으로 주문 명령을 보낼 수 있습니다.

초기 snapshot

첫 JSON 프레임은 항상 sequence 0인 snapshot입니다.

{
  "event": "snapshot",
  "sequence": 0,
  "data": { "orders": [], "ordersHasMore": false, "balances": [] },
  "serverTime": 1783420800123
}

현재 볼 수 있는 지갑 잔고와 최대 1000개의 현물 미체결 주문을 포함합니다. ordersHasMore: true면 주문 목록이 잘린 것이므로 스냅샷만으로 전체 미체결 주문 상태를 확정하지 마세요. REST 조회를 병행하고 필요하면 지갑·마켓별로 상태 범위를 나눕니다. 전체 상태를 확보하지 못한 자동매매는 운영 확인이 필요합니다.

스냅샷을 만드는 동안 대기한 이벤트는 이후에 순서대로 전달됩니다. 이미 snapshot의 누적 체결 수량에 포함된 체결은 같은 연결에서 중복 발행하지 않습니다.

이벤트 종류

order, fill, balance가 하나의 sequence를 공유합니다. 모든 이벤트를 순서대로 수신한 뒤 필요한 유형을 분배해야 합니다.

주문 이벤트

updateType은 open, partiallyFilled, filled, canceled, unknown 중 하나입니다. 아래는 핵심 필드만 보인 예시이며 전체 주문 필드는 UserStreamOrderEvent에 있습니다.

{
  "event": "order",
  "updateType": "partiallyFilled",
  "sequence": 7,
  "data": {
    "orderId": "987654",
    "status": "partiallyFilled",
    "filledQuantity": "0.040000000",
    "remainingQuantity": "0.060000000"
  },
  "serverTime": 1783420800123
}

수량·체결 금액·수수료는 누적값입니다. 이벤트의 절대 주문 상태로 기존 값을 교체합니다.

체결 이벤트

{
  "event": "fill",
  "sequence": 8,
  "data": {
    "executionId": "987654:0.040000000",
    "orderId": "987654",
    "symbol": "BTC-USDT",
    "walletId": 21,
    "side": "buy",
    "type": "limit",
    "liquidity": "maker",
    "price": "65000.000000000",
    "quantity": "0.010000000",
    "quoteQuantity": "650.000000000",
    "cumulativeQuantity": "0.040000000",
    "cumulativeQuoteQuantity": "2600.000000000",
    "cumulativeFee": "0.001000000",
    "aggregated": false,
    "baseCurrencyId": 1002,
    "quoteCurrencyId": 1001,
    "time": 1783420800123,
    "microtime": 1783420800123456
  },
  "serverTime": 1783420800123
}

• executionId는 실시간 중복 확인용 불투명 ID입니다. REST /v1/fills의 fillId와 다릅니다.
• quantity와 quoteQuantity는 이번 이벤트의 체결 증가분입니다.
• cumulativeQuantity, cumulativeQuoteQuantity, cumulativeFee는 주문 전체의 누적값입니다.
• maker는 보통 한 번의 체결이며 aggregated: false입니다. taker가 여러 주문을 체결한 결과나 복구된 누적 차이는 aggregated: true일 수 있습니다. 이때 price는 해당 결과의 가중평균입니다.
• snapshot은 체결을 재생하지 않습니다. 연결이 끊긴 구간의 정확한 체결은 REST로 대조합니다.

잔고 이벤트와 순서

주문 엔진의 체결 업데이트는 order → fill → 관련 기준·결제 통화의 balance 순서로 전달됩니다. 이체에 따른 잔고 변경도 balance 이벤트로 전달됩니다.

잔고 필드는 Balance를 확인하세요. 잔고 이벤트를 기존 값에 더하지 말고, 지갑과 통화별 상태를 대체합니다. 연결 종료·sequence 누락·권한 변경 시에는 복구 절차를 따릅니다.