WebSocket-стрим

СоединениеСкопировать ссылку на раздел

• Адрес: ws://127.0.0.1:48180/v1/stream.
• Токен передаётся в заголовке Authorization: Bearer <token> рукопожатия. Рукопожатию нужно право market:read. Оно отклоняется по тем же правилам, что HTTP-запрос, с 401 или 403.
• Сервер шлёт WebSocket-ping каждые 20 с. Если pong не приходит 50 с, сервер закрывает соединение.
• Когда клиент закрывает соединение, сервер отвечает кадром закрытия с кодом клиента.
• Закрытие сокета снимает все подписки соединения. Явный unsubscribe снимает подписку сразу.
• Пара без подписчиков отпускается на бирже через 30 с.

Коды закрытияСкопировать ссылку на раздел

ЛимитыСкопировать ссылку на раздел

Лимиты возвращает GET /v1/meta. Отказ — это кадр error с rate_limited в ответ на запрос или закрытие с кодом 4029.

Медленные клиентыСкопировать ссылку на раздел

Клиент, который не читает, не замедляет ни терминал, ни других клиентов. Кадры, которые он не забрал вовремя, отбрасываются. Для trades кадр gap называет потерянные номера. Для остальных топиков следующий кадр просто новее.

Порядковые номераСкопировать ссылку на раздел

seq нумерует события подписки. У trades он растёт на единицу. У топиков, где отправляется только последнее значение, пропуски в номерах — это норма.

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Скопировать ссылку на раздел

Снять подписку.

Принимает только sub, возвращённый в subscribed.

{
  "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Скопировать ссылку на раздел

Суточный тикер пары.

data — тикер, как ticker в GET /v1/market/snapshot. Отправляется только последнее значение.

Данные: 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Скопировать ссылку на раздел

Цена маркировки (mark) пары.

Отправляется только последнее значение.

Данные: 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 — один бакет, как элемент data в GET /v1/market/clusters. Кадр приходит по каждому изменившемуся бакету, не чаще раза в 16 мс, с его последним состоянием. Смена интервала в терминале видна в interval.

Данные: ClusterBucket

account.ordersСкопировать ссылку на раздел

Заявки и триггерные заявки одного инструмента после изменения.

Отправляется только последнее состояние инструмента. Подписка не обращается к бирже, и события идут с того момента, как их присылает подключение. Кадра-снимка при подписке нет. Текущее состояние читайте через GET /v1/account/orders.

Данные: InstrumentOrders

account.positionsСкопировать ссылку на раздел

Позиция одного инструмента после изменения.

Отправляется только последнее состояние. Закрытая позиция приходит как "position": null. Кадра-снимка при подписке нет.

Данные: InstrumentPosition

account.balancesСкопировать ссылку на раздел

Баланс одной валюты.

data — один баланс, как элемент data в GET /v1/account/balances. Отправляется только последнее значение. Кадра-снимка при подписке нет.

Данные: Balance

account.fillsСкопировать ссылку на раздел

Одно исполнение.

Один кадр на исполнение. Если клиент отстаёт, кадр теряется, и seq показывает пропуск. Прочитайте исполнения ещё раз через GET /v1/account/fills с since_ts.

Данные: Fill

workspaceСкопировать ссылку на раздел

Раскладка окон целиком.

data — раскладка, как data в GET /v1/workspace. Первый кадр — текущая раскладка, он отправляется сразу при подписке. Дальше кадр приходит на каждое изменение. Отправляется только последнее состояние.

Данные: 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Скопировать ссылку на раздел

Суточный тикер.

MarkPriceСкопировать ссылку на раздел

BookTopСкопировать ссылку на раздел

Верхушка стакана: биды от лучшей цены вниз, аски от лучшей цены вверх.

ClusterBucketСкопировать ссылку на раздел

InstrumentOrdersСкопировать ссылку на раздел

InstrumentPositionСкопировать ссылку на раздел

BalanceСкопировать ссылку на раздел

FillСкопировать ссылку на раздел

WorkspaceSnapshotСкопировать ссылку на раздел

SettingWrittenСкопировать ссылку на раздел

Строка настроек, как она записана, без writable.

PriceLevelСкопировать ссылку на раздел

string[]

[price, size], оба значения — десятичные строки.

ClusterLevelСкопировать ссылку на раздел

OrderСкопировать ссылку на раздел

TriggerСкопировать ссылку на раздел

PositionСкопировать ссылку на раздел

WindowСкопировать ссылку на раздел

TriggerKindСкопировать ссылку на раздел

stop_losstake_profitstop

TriggerRuleСкопировать ссылку на раздел

price_above_or_equalprice_below_or_equal

TabСкопировать ссылку на раздел

StackСкопировать ссылку на раздел

Стакан с лентой сделок и кластерами.

ChartСкопировать ссылку на раздел

CellСкопировать ссылку на раздел

Ячейка сетки вкладки: колонка слева, строка сверху, ячейка внутри строки.