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Скопіювати посилання на розділ

24-годинний тікер пари.

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Скопіювати посилання на розділ

24-годинний тікер.

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Скопіювати посилання на розділ

Комірка сітки вкладки: колонка зліва, рядок згори, комірка в рядку.