WebSocket 스트림

연결섹션 링크 복사

• 주소: ws://127.0.0.1:48180/v1/stream.
• 토큰은 핸드셰이크의 Authorization: Bearer <token> 헤더로 보냅니다. 핸드셰이크에는 market:read 권한이 필요합니다. HTTP 요청과 같은 규칙에 따라 401 또는 403으로 거부됩니다.
• 서버는 20초마다 WebSocket ping을 보냅니다. 50초 동안 pong이 오지 않으면 서버가 연결을 닫습니다.
• 클라이언트가 연결을 닫으면 서버는 클라이언트의 코드를 담은 close 프레임으로 응답합니다.
• 소켓을 닫으면 연결의 모든 구독이 제거됩니다. 명시적인 unsubscribe는 구독 하나를 즉시 제거합니다.
• 구독자가 없는 페어는 30초 뒤 거래소에서 해제됩니다.

종료 코드섹션 링크 복사

제한섹션 링크 복사

GET /v1/meta가 제한을 반환합니다. 거부는 요청에 대한 응답인 error 프레임에 rate_limited가 담겨 오거나, 4029 종료로 나타납니다.

느린 클라이언트섹션 링크 복사

읽지 않는 클라이언트는 터미널도 다른 클라이언트도 느리게 만들지 않습니다. 제때 가져가지 않은 프레임은 버려집니다. trades의 경우 gap 프레임이 잃어버린 번호를 알려 줍니다. 다른 토픽에서는 다음 프레임이 그저 더 최신일 뿐입니다.

시퀀스 번호섹션 링크 복사

seq는 구독의 이벤트에 번호를 매깁니다. trades에서는 1씩 증가합니다. 최신 값만 전송되는 토픽에서는 번호에 누락이 있는 것이 정상입니다.

subscribe섹션 링크 복사

토픽을 요청합니다.

토픽에 필요한 것은 토픽의 종류에 따라 다릅니다:

• 시장 토픽은 trades, ticker, mark_price, book.top, clusters입니다. instrument는 필수입니다. connection_id는 공통 규칙에 따라 선택됩니다. 권한은 market:read입니다.
• 계정 토픽은 account.*입니다. connection_id는 필수입니다. instrument는 사용하지 않습니다. 권한은 account:read입니다.
• workspace 및 settings 토픽은 둘 다 받지 않습니다. 권한은 workspace:read와 settings:read입니다.

book.top만 params를 사용합니다. 다른 토픽은 이를 무시합니다.

{
  "type": "subscribe",
  "request_id": "r1",
  "topic": "trades",
  "instrument": "binance:futures:BTCUSDT",
  "connection_id": 12
}

{
  "type": "subscribe",
  "request_id": "r2",
  "topic": "book.top",
  "instrument": "binance:futures:BTCUSDT",
  "params": {
    "depth": 10,
    "interval_ms": 250
  }
}

{
  "type": "subscribe",
  "request_id": "r3",
  "topic": "account.fills",
  "connection_id": 12
}

{
  "type": "subscribe",
  "request_id": "r4",
  "topic": "workspace"
}

unsubscribe섹션 링크 복사

구독을 해제합니다.

subscribed가 반환한 sub만 받습니다.

{
  "type": "unsubscribe",
  "request_id": "r5",
  "sub": "7:trades"
}

subscribed섹션 링크 복사

구독이 설정되었습니다.

sub는 이후의 모든 프레임에서 구독을 식별합니다. 시장 토픽은 "{stream}:{topic}", 계정 토픽은 "{connection}:account.<topic>", 나머지 둘은 "workspace" 또는 "settings"입니다. 같은 페어와 토픽을 구독한 모든 클라이언트는 같은 sub를 받습니다. connection_id는 시장 토픽과 계정 토픽에 있습니다. workspace와 settings에는 없습니다.

{
  "type": "subscribed",
  "request_id": "r1",
  "sub": "7:trades",
  "connection_id": 12
}

unsubscribed섹션 링크 복사

구독이 제거되었습니다.

{
  "type": "unsubscribed",
  "request_id": "r5",
  "sub": "7:trades"
}

error섹션 링크 복사

요청이 거부되었거나 서버가 구독을 제거했습니다.

request_id가 있으면 클라이언트의 요청에 대한 응답입니다. sub는 있고 request_id가 없으면 서버가 구독을 제거한 것입니다. 코드는 HTTP 작업의 코드와 같습니다.

{
  "type": "error",
  "request_id": "r1",
  "code": "not_found",
  "message": "no connection for the instrument"
}

{
  "type": "error",
  "sub": "7:trades",
  "code": "unavailable",
  "message": "the exchange refused the subscription"
}

gap섹션 링크 복사

클라이언트가 놓친 체결입니다.

trades에만 전송되며, 손실 뒤 첫 프레임 앞에 옵니다. 클라이언트가 읽지 않고 있었고, from_seq부터 to_seq까지의 이벤트가 손실되었습니다. GET /v1/market/trades와 since_ts로 다시 읽습니다.

{
  "type": "gap",
  "sub": "7:trades",
  "from_seq": 42,
  "to_seq": 57,
  "reason": "slow_consumer"
}

trades섹션 링크 복사

페어의 체결이며, 순서대로 전달됩니다.

data는 체결 배열이며, GET /v1/market/trades에서와 같습니다. 체결은 순서대로 옵니다. 클라이언트가 뒤처지면 gap 프레임이 무엇을 놓쳤는지 알려 줍니다.

데이터: Trade[]

{
  "type": "event",
  "sub": "7:trades",
  "seq": 41,
  "ts": 1730294400130,
  "data": [
    {
      "id": null,
      "price": "67000.1",
      "qty": "0.012",
      "side": "buy",
      "ts": 1730294400125,
      "exchange_ts": 1730294400119
    }
  ]
}

ticker섹션 링크 복사

페어의 24시간 티커입니다.

data는 티커이며, GET /v1/market/snapshot의 ticker와 같습니다. 최신 값만 전송됩니다.

데이터: Ticker

{
  "type": "event",
  "sub": "7:ticker",
  "seq": 12,
  "ts": 1730294400130,
  "data": {
    "price": "67000.1",
    "change_24h_pct": "1.25",
    "volume_24h": "81234.5",
    "high_24h": null,
    "low_24h": null,
    "best_bid": null,
    "best_ask": null,
    "ts": 1730294400120
  }
}

mark_price섹션 링크 복사

페어의 마크 가격입니다.

최신 값만 전송됩니다.

데이터: MarkPrice

{
  "type": "event",
  "sub": "7:mark_price",
  "seq": 5,
  "ts": 1730294400130,
  "data": {
    "mark_price": "67001.0",
    "ts": 1730294400120
  }
}

book.top섹션 링크 복사

페어의 호가창 상단입니다.

구독자마다 자신의 depth와 interval_ms를 설정합니다. 범위를 벗어난 값은 invalid_request로 거부됩니다. 첫 프레임은 호가창이 준비되는 즉시 옵니다. 그 뒤로는 interval_ms마다 최대 한 프레임이 최신 호가창과 함께 옵니다. seq는 호가창의 버전입니다.

데이터: BookTop

{
  "type": "event",
  "sub": "7:book.top",
  "seq": 9031,
  "ts": 1730294400130,
  "data": {
    "ts": 1730294400123,
    "depth": 10,
    "bids": [
      [
        "67000.1",
        "1.25"
      ]
    ],
    "asks": [
      [
        "67000.2",
        "0.40"
      ]
    ]
  }
}

clusters섹션 링크 복사

종목의 거래량 클러스터입니다.

data는 버킷 하나이며, GET /v1/market/clusters의 data 요소와 같습니다. 변경된 버킷마다 최대 16ms에 한 번, 최신 상태를 담은 프레임이 옵니다. 터미널에서 인터벌을 바꾸면 interval에 나타납니다.

데이터: ClusterBucket

account.orders섹션 링크 복사

변경 후 한 종목의 주문과 트리거 주문입니다.

종목의 최신 상태만 전송됩니다. 구독은 거래소를 건드리지 않으며, 이벤트는 연결이 보내는 시점부터 옵니다. 구독 시 스냅샷 프레임은 없습니다. 현재 상태는 GET /v1/account/orders로 읽습니다.

데이터: InstrumentOrders

account.positions섹션 링크 복사

변경 후 한 종목의 포지션입니다.

최신 상태만 전송됩니다. 청산된 포지션은 "position": null로 도착합니다. 구독 시 스냅샷 프레임은 없습니다.

데이터: InstrumentPosition

account.balances섹션 링크 복사

한 통화의 잔고입니다.

data는 잔고 하나이며, GET /v1/account/balances의 data 요소와 같습니다. 최신 값만 전송됩니다. 구독 시 스냅샷 프레임은 없습니다.

데이터: Balance

account.fills섹션 링크 복사

체결 내역 하나입니다.

체결 내역마다 프레임 하나가 옵니다. 클라이언트가 뒤처지면 프레임이 손실되고 seq에 누락이 나타납니다. GET /v1/account/fills와 since_ts로 체결 내역을 다시 읽습니다.

데이터: Fill

workspace섹션 링크 복사

창의 전체 레이아웃입니다.

data는 레이아웃이며, GET /v1/workspace의 data와 같습니다. 첫 프레임은 현재 레이아웃이며 구독 즉시 전송됩니다. 그 뒤로는 변경이 있을 때마다 프레임이 옵니다. 최신 상태만 전송됩니다.

데이터: WorkspaceSnapshot

settings섹션 링크 복사

기록된 설정 행 하나입니다.

설정 테이블에 쓸 때마다 프레임 하나가 옵니다: API, Settings App, 창 자체에서 쓴 경우 모두 해당합니다. 구독 시 스냅샷은 없습니다. 현재 값은 GET /v1/settings로 읽습니다. 클라이언트가 뒤처지면 프레임이 손실되고 seq에 누락이 나타납니다.

데이터: SettingWritten

{
  "type": "event",
  "sub": "settings",
  "seq": 3,
  "ts": 1730294400130,
  "data": {
    "scope": "global",
    "scope_id": "default",
    "connection_id": null,
    "category": "multiview",
    "key": "stack_width_px",
    "value": 300
  }
}

Topic섹션 링크 복사

tradestickermark_pricebook.topclustersaccount.ordersaccount.positionsaccount.balancesaccount.fillsworkspacesettings

ErrorCode섹션 링크 복사

unauthorizedforbiddenforbidden_scopenot_foundinvalid_requestunsupportednot_activenot_tradablerate_limitedunavailable

안정적인 코드이며 계약의 일부입니다. 새 코드가 추가될 수 있습니다.

Trade섹션 링크 복사

Ticker섹션 링크 복사

24시간 티커입니다.

MarkPrice섹션 링크 복사

BookTop섹션 링크 복사

호가창 상단입니다: 매수 호가는 최우선 가격부터 아래로, 매도 호가는 최우선 가격부터 위로.

ClusterBucket섹션 링크 복사

InstrumentOrders섹션 링크 복사

InstrumentPosition섹션 링크 복사

Balance섹션 링크 복사

Fill섹션 링크 복사

WorkspaceSnapshot섹션 링크 복사

SettingWritten섹션 링크 복사

기록된 그대로의 설정 행이며, writable은 없습니다.

PriceLevel섹션 링크 복사

string[]

[price, size], 둘 다 10진수 문자열입니다.

ClusterLevel섹션 링크 복사

Order섹션 링크 복사

Trigger섹션 링크 복사

Position섹션 링크 복사

Window섹션 링크 복사

TriggerKind섹션 링크 복사

stop_losstake_profitstop

TriggerRule섹션 링크 복사

price_above_or_equalprice_below_or_equal

Tab섹션 링크 복사

Stack섹션 링크 복사

체결 테이프와 클러스터가 있는 호가창입니다.

Chart섹션 링크 복사

Cell섹션 링크 복사

탭 그리드의 셀입니다: 왼쪽부터의 열, 위부터의 행, 행 안의 셀.