WebSocket stream

ConnectionCopy Anchor Link

• Address: ws://127.0.0.1:48180/v1/stream.
• The token goes in the Authorization: Bearer <token> header of the handshake. The handshake requires the market:read scope. It is rejected by the same rules as an HTTP request, with 401 or 403.
• The server sends a WebSocket ping every 20 s. If no pong comes for 50 s, the server closes the connection.
• When the client closes the connection, the server answers with a close frame that carries the code of the client.
• Closing the socket removes every subscription of the connection. An explicit unsubscribe removes a subscription at once.
• A pair with no subscribers is released on the exchange after 30 s.

Close codesCopy Anchor Link

LimitsCopy Anchor Link

GET /v1/meta returns the limits. A refusal is an error frame with rate_limited in answer to the request, or a close with 4029.

Slow clientsCopy Anchor Link

A client that does not read slows down neither the terminal nor other clients. Frames it does not take in time are dropped. For trades a gap frame names the lost numbers. For the other topics the next frame is simply newer.

Sequence numbersCopy Anchor Link

seq numbers the events of a subscription. For trades it grows by one. For topics where only the latest value is sent, gaps in the numbers are normal.

subscribeCopy Anchor Link

Ask for a topic.

What a topic needs depends on its family:

• Market topics are trades, ticker, mark_price, book.top and clusters. instrument is required. connection_id is chosen by the common rule. The scope is market:read.
• Account topics are account.*. connection_id is required. instrument is not used. The scope is account:read.
• workspace and settings take neither. The scopes are workspace:read and settings:read.

Only book.top uses params. Other topics ignore them.

{
  "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"
}

unsubscribeCopy Anchor Link

Drop a subscription.

Takes only the sub returned by subscribed.

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

subscribedCopy Anchor Link

The subscription is set up.

sub identifies the subscription in every later frame. It is "{stream}:{topic}" for market topics, "{connection}:account.<topic>" for account topics, and "workspace" or "settings" for the other two. Every client subscribed to the same pair and topic gets the same sub. connection_id is present for market and account topics. It is absent for workspace and settings.

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

unsubscribedCopy Anchor Link

The subscription is removed.

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

errorCopy Anchor Link

A request is refused, or a subscription is removed by the server.

With request_id it answers a request of the client. With sub and without request_id the server has removed the subscription. The codes are the codes of the HTTP operations.

{
  "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"
}

gapCopy Anchor Link

Trades the client lost.

Sent only for trades, before the first frame after the loss. The client was not reading, and the events from from_seq to to_seq are lost. Read them again with GET /v1/market/trades and since_ts.

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

tradesCopy Anchor Link

Trades of a pair, in order.

data is an array of trades, as in GET /v1/market/trades. Trades come in order. If the client falls behind, a gap frame names what was lost.

Data: 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
    }
  ]
}

tickerCopy Anchor Link

The 24-hour ticker of a pair.

data is the ticker, as ticker in GET /v1/market/snapshot. Only the latest value is sent.

Data: 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_priceCopy Anchor Link

The mark price of a pair.

Only the latest value is sent.

Data: MarkPrice

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

book.topCopy Anchor Link

The top of the order book of a pair.

Each subscriber sets its own depth and interval_ms. Values outside the bounds are refused with invalid_request. The first frame comes as soon as the book is ready. After that at most one frame comes per interval_ms, with the latest book. seq is the version of the book.

Data: 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"
      ]
    ]
  }
}

clustersCopy Anchor Link

Volume clusters of an instrument.

data is one bucket, as an element of data in GET /v1/market/clusters. A frame comes for every bucket that changed, at most once in 16 ms, with its latest state. A change of the interval in the terminal shows in interval.

Data: ClusterBucket

account.ordersCopy Anchor Link

Orders and trigger orders of one instrument after a change.

Only the latest state of the instrument is sent. Subscribing does not touch the exchange, and events come from the moment the connection sends them. There is no snapshot frame on subscribing. Read the current state with GET /v1/account/orders.

Data: InstrumentOrders

account.positionsCopy Anchor Link

The position of one instrument after a change.

Only the latest state is sent. A closed position arrives as "position": null. There is no snapshot frame on subscribing.

Data: InstrumentPosition

account.balancesCopy Anchor Link

The balance of one currency.

data is one balance, as an element of data in GET /v1/account/balances. Only the latest value is sent. There is no snapshot frame on subscribing.

Data: Balance

account.fillsCopy Anchor Link

One fill.

One frame per fill. If the client falls behind, a frame is lost and seq shows the gap. Read the fills again with GET /v1/account/fills and since_ts.

Data: Fill

workspaceCopy Anchor Link

The whole layout of the windows.

data is the layout, as data in GET /v1/workspace. The first frame is the current layout, sent at once on subscribing. Then a frame comes for every change. Only the latest state is sent.

Data: WorkspaceSnapshot

settingsCopy Anchor Link

One written settings row.

One frame for every write to the settings table: from the API, from Settings App and from the window itself. There is no snapshot on subscribing. Read the current values with GET /v1/settings. If the client falls behind, a frame is lost and seq shows the gap.

Data: 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
  }
}

TopicCopy Anchor Link

tradestickermark_pricebook.topclustersaccount.ordersaccount.positionsaccount.balancesaccount.fillsworkspacesettings

ErrorCodeCopy Anchor Link

unauthorizedforbiddenforbidden_scopenot_foundinvalid_requestunsupportednot_activenot_tradablerate_limitedunavailable

A stable code, part of the contract. New codes may be added.

TradeCopy Anchor Link

TickerCopy Anchor Link

The 24-hour ticker.

MarkPriceCopy Anchor Link

BookTopCopy Anchor Link

The top of the book: bids from the best price down, asks from the best price up.

ClusterBucketCopy Anchor Link

InstrumentOrdersCopy Anchor Link

InstrumentPositionCopy Anchor Link

BalanceCopy Anchor Link

FillCopy Anchor Link

WorkspaceSnapshotCopy Anchor Link

SettingWrittenCopy Anchor Link

A settings row as it was written, without writable.

PriceLevelCopy Anchor Link

string[]

[price, size], both decimal strings.

ClusterLevelCopy Anchor Link

OrderCopy Anchor Link

TriggerCopy Anchor Link

PositionCopy Anchor Link

WindowCopy Anchor Link

TriggerKindCopy Anchor Link

stop_losstake_profitstop

TriggerRuleCopy Anchor Link

price_above_or_equalprice_below_or_equal

TabCopy Anchor Link

StackCopy Anchor Link

An order book with the tape and clusters.

ChartCopy Anchor Link

CellCopy Anchor Link

A cell of the grid of the tab: column from the left, row from the top, cell inside the row.