Потоки WebSocket
1Потоки WebSocket
Одно соединение /v1/ws на несколько каналов — плотности, скринер, сделки, открытый интерес и секундные свечи; подписка по инструментам или на весь рынок с фильтрами, команды, кадры, пределы и коды закрытия.
wss://market-api.lootx.trade/v1/ws — одно соединение на несколько каналов и инструментов — в пределах тарифа и пределов соединения. Кадры — JSON с именами venue:market:SYMBOL и временем в Unix-мс, как у REST; написание имени в кадре может отличаться от вашего.
Поток опционов — отдельный адрес wss://market-api.lootx.trade/v1/options/stream со своим протоколом: текст hello и кадры OPC1, без команд и каналов, группа тарифа — options, а не ws (живой поток). Ключ передаётся так же, как здесь.
Подключение
Ключ — как у REST: Authorization: Bearer <ключ> или X-API-Key. Из браузера заголовок не задать, поэтому ключ передаётся подпротоколом: ["lx.v1", "key.<ключ>"] — сервер выберет lx.v1. В адрес ключ не кладётся.
const ws = new WebSocket("wss://market-api.lootx.trade/v1/ws", ["lx.v1", `key.${apiKey}`]);
ws.onopen = () => {
ws.send(JSON.stringify({
op: "subscribe", id: 1, channel: "trades",
instruments: ["binance:perp:BTCUSDT"],
}));
};
ws.onmessage = (e) => {
const m = JSON.parse(e.data);
if (m.type === "update" && m.channel === "trades") {
for (const t of m.data.trades) console.log(m.instrument, t.side, t.price, t.qty);
} else if (m.type === "error") {
console.warn(m.code, m.message);
}
};
ws.onclose = (e) => console.log("закрыто", e.code, e.reason);import asyncio, json, os
import websockets # pip install "websockets>=14"
async def main():
headers = {"Authorization": f"Bearer {os.environ['LOOTX_API_KEY']}"}
async with websockets.connect("wss://market-api.lootx.trade/v1/ws",
additional_headers=headers) as ws:
await ws.send(json.dumps({"op": "subscribe", "id": 1, "channel": "densities",
"instruments": ["binance:perp:BTCUSDT"]}))
async for raw in ws:
m = json.loads(raw)
if m["type"] == "snapshot":
print("стен:", len(m["data"]["walls"]))
elif m["type"] == "update":
print("+", len(m["data"]["upsert"]), "-", len(m["data"]["remove"]))
asyncio.run(main())Сервер шлёт WS-ping каждые 5 секунд (одновременно с проверкой доступа) — библиотеки отвечают на него сами.
Команды
Текстовые JSON-кадры, не больше 64 КиБ:
{"op":"subscribe","id":1,"channel":"densities","instruments":["binance:perp:BTCUSDT","hyperliquid:perp:BTC"]}
{"op":"unsubscribe","id":2,"channel":"densities","instruments":["binance:perp:BTCUSDT"]}
{"op":"unsubscribe","id":3,"channel":"densities"}
{"op":"subscribe","id":5,"channel":"densities","scope":"market","params":{"venues":["binance"],"markets":["perp"],"min_usd":250000}}
{"op":"unsubscribe","id":6,"channel":"densities","scope":"market"}
{"op":"ping","id":4}id— любое число или строка; сервер вернёт его в ответе на команду. На каждую команду сidприходит ответ с этимid, пока соединение открыто:subscribed,unsubscribed,pongилиerror.unsubscribeбез непустого массиваinstrumentsснимает все инструменты канала; рыночную подписку — нет, она снимается соscope: "market".paramsу подписки по инструментам, кромеnullи пустого объекта, даютbad_params. Фильтры есть у подписки на весь рынок.
Кадры сервера
type |
Когда | Поля |
|---|---|---|
subscribed |
подписка принята | id, channel, instruments — имена, под которыми пойдут кадры, с одним исключением |
unsubscribed |
снята | id, channel, instruments |
snapshot |
состояние инструмента целиком | channel, instrument, t, data |
update |
изменение | channel, instrument, t, data |
removed |
инструменты вышли из рыночной подписки | channel, scope, t, instruments |
status |
связь с источником | channel, state, instruments, message |
error |
отказ | id, code, message, instrument |
pong |
ответ на ping |
id |
У рыночной подписки кадры другой формы — см. ниже. По каждому инструменту сначала приходит ровно один snapshot, потом update (у trades снимка нет). snapshot может прийти снова — после обрыва источника: это «замените состояние целиком», а не дубль. После unsubscribed ещё могут дойти кадры, уже стоявшие в очереди.
Обрыв источника соединение не рвёт. Приходит status с state: "reconnecting" и списком задетых инструментов; шлюз сам переподключается к источнику и повторяет подписки, затем state: "live" и свежие снимки. state: "gap" — источник потерял кадры без восстановления (бывает у ленты сделок): дочитайте пропуск через REST.
Каналы
| Канал | snapshot.data |
update.data |
Группа тарифа |
|---|---|---|---|
densities |
{"walls": [стена…]} |
{"upsert": [стена…], "remove": [{"wall_id", "reason", "duration_ms"}]} |
densities |
screener |
метрики {"last_price": …, …} |
изменившиеся метрики; null — значение сброшено |
screener |
trades |
— | {"trades": [{"ts", "price", "qty", "quote_qty", "side", "fills", "aggregated"}]} |
trades |
oi |
бар текущей минуты или null |
бар минуты; незакрытый — с растущим samples |
oi |
candles |
{"candles": [до 600 секундных свечей]} |
{"candles": […]} |
candles_1s |
- Стена — те же поля, что у
/v1/densities:wall_idстрокой,side,price,qty(в монетах),usd(в долларах),dist_bp,first_ts(мс),age_ms,peak_usd,touched,aggи, где есть,size,score.reasonпри удалении —pulled(снята) илиeaten(съедена);null— служебное удаление. - Метрики скринера — длинные имена, как у
/v1/screener. - Сделка:
price(в валюте котировки),qty(в монетах),quote_qty(в валюте котировки, без округления к шагу цены),side— сторона агрессора. - Бар OI:
bucket_ts(мс, начало минуты),samples,native_unit(coins,usdилиcontracts),native_open…native_close,oi_coins_open…oi_coins_close,oi_usd_open…oi_usd_close,price_used_close. Живой поток OI есть у binance, bybit, okx, bingx, kucoin, mexc, bitget, hyperliquid, aster и gate. У kraken и coinbase потока нет: подписка даётunsupported_instrument, история — через REST/v1/oi. У остальных бирж OI в шлюзе нет: и подписка, и REST даютunsupported_instrument. - Свеча:
ts(мс),open,high,low,close,volume(в валюте котировки, у USDT-пар это доллары),trades;trades: 0— пустая секунда, OHLC равны прошлому закрытию. Это неvolumeиз REST: в/v1/candlesколонкаvolume— монеты, а сумма в котировке лежит вquote_volume. Значениеvolumeканала соответствуетquote_volumeREST; объёма в монетах в канале нет.
Канал, группа которого закрыта тарифом, отвечает на подписку error route_not_in_plan; соединение при этом живёт.
Имена в кадрах
Кадры подписки называются не так, как написал клиент, а по имени инструмента на этом канале. Разные написания одного инструмента — одна подписка и одно имя в кадрах. Обычные символы (binance:perp:BTCUSDT, hyperliquid:perp:BTC) это не меняет. Особые случаи:
hyperliquid:perp:kPEPEиhyperliquid:perp:KPEPEидут какhyperliquid:perp:KPEPEна всех каналах, кромеoi. Наoiимя монеты остаётся как у биржи:kPEPEиKPEPE, как иbtcиBTC, — разные подписки под этими же именами.binance:perp:btcusdtна каналахcandlesиdensitiesидёт какbinance:perp:BTCUSDT. Наtradesиoiрегистр не приводится, наscreenerтакое имя получаетunsupported_instrument.- Варианты монеты Hyperliquid
BTCUSDCиBTCUSDTв любом регистре хвоста идут какhyperliquid:perp:BTC. Уscreenerhyperliquid:perp:BTCUSDCчитается по его списку инструментов: монета без акции с таким именем идёт какhyperliquid:perp:BTC, остальное — как акция. - На
screenerдека нет:AAPLUSDC.XYZиAAPLUSDCидут какhyperliquid:perp:AAPLUSDC, кадр один на все деки монеты. - Имя, которое не собирается обратно из имени источника (опечатка, котировка вне списка шлюза), идёт как написал клиент. На
oiу bingxBT-CUSDTиBTCUSDT— разные имена источника, поэтому разные подписки и разные имена кадров.
Имя кадров называет subscribed, с одним исключением: несколько написаний такого имени, которые у источника совпадают, например hyperliquid:perp:AAPLUSDC.XYZUSDC и hyperliquid:perp:aaplusdc.xyzusdc на densities. subscribed отвечает каждому его написанием, а кадры идут под написанием первого подписчика, пока у инструмента есть подписчики. На одном соединении отписка одного написания останавливает кадры обоих, а второе считается подпиской, пока его не снимут или соединение не закроется. Настоящих символов это не касается.
unsubscribe принимает то имя, которым подписывались, а unsubscribed называет имя, под которым шла подписка.
Подписка не сверяет символ
unsupported_instrument в потоке значит, что у источника канала нет такого рынка или биржи, а на oi и screener ещё и что не разобралась котировка символа. Кадр несёт instrument, поля param в нём нет: случаи он не различает.
- Котировка на
oiпроверяется только у okx, bingx, mexc и kucoin:okx:perp:BTC-USDT-SWAP,kucoin:perp:XBTUSDTM. - Канал
screenerбиржу не сверяет: неизвестная биржа подписку проходит. Он отказывает, если котировку не разобрать, и перпу с котировкой не изUSDT,USDCиUSD; перпов Hyperliquid это не касается.
Опечатка, имя которой шлюз смог перевести, подписку проходит: binance:perp:BTCUSDTT на candles, densities, trades и oi получит subscribed, а дальше в лучшем случае пустой snapshot. Данных не будет, ошибки тоже. Символ проверяют только REST /v1/candles и /v1/series, и не всегда. Молчание подписки не значит, что инструмент существует: имя берите из /v1/instruments.
Весь рынок
Подписка scope: "market" даёт весь рынок канала densities или screener без списка инструментов. Фильтры задаются в params, применяет их источник — тем же кодом, что и для терминала. У других каналов такой подписки нет: bad_params.
{"op":"subscribe","id":5,"channel":"densities","scope":"market","params":{"venues":["binance"],"markets":["perp"],"min_usd":250000,"max_dist_pct":2}}
{"op":"subscribe","id":6,"channel":"screener","scope":"market","params":{"markets":["perp"],"fields":["last_price","volume_24h_usd"],"filters":[{"metric":"volume_24h_usd","op":"gt","value":1000000}]}}
{"op":"unsubscribe","id":7,"channel":"densities","scope":"market"}- Ответ — кадр
subscribedс нормализованнымиparams: что применено на самом деле. Он приходит раньше кадров подписки и не теряется, даже если следующая команда снимает её сразу. subscribedиunsubscribedэтой подписки идут через очередь к клиенту: в порядке команд и вслед за кадрами прежней подписки. Отказыerrorприходят сразу и могут их обогнать: сопоставляйте ответы поid.- В соединении одна рыночная подписка на канал. Повторный
subscribeзаменяет её: прежняя обрывается, после новогоsubscribedкадров старых фильтров нет. Неверная команда прежнюю подписку не трогает. Открывать подписку канала на соединении можно раз в секунду: чаще —rate_limited, прежняя подписка, если она есть, остаётся. unsubscribeсоscope: "market"снимает подписку и отвечаетunsubscribedсоscope, в том числе когда подписки не было.instrumentsв этой команде не читаются. Безscopeрыночная подписка не снимается.- Непустой массив
instrumentsвместе соscope: "market"в командеsubscribe—bad_params. - Рыночная подписка и подписка канала по инструментам друг другу не мешают. Рыночная не считается ни в 200 подписок на соединение, ни в долю
too_many_instruments. - Группа тарифа — та же, что у канала: закрытая группа даёт
route_not_in_plan.
Фильтры densities
| Параметр | Значение |
|---|---|
venues |
биржи массивом, тот же набор, что у /v1/densities. Нет параметра — все |
markets |
массив из spot и perp. Нет параметра — все |
min_usd |
номинал стены от этого значения, в долларах, не меньше 0 |
max_dist_pct |
дальше от середины стакана не идти, в процентах: 2 — это ±2 %. От 0.01 до 100, шаг 0.01: значение округляется до шага, в subscribed.params приходит округлённое. Округлилось в ноль — bad_params |
side |
bid или ask |
min_size |
класс стены не ниже указанного: weak, optimal или strong |
agg |
tick (по умолчанию) или natr |
hide_stables, hide_commodities, hide_stocks, hide_indices |
true — скрыть класс актива: стейблкоины и фиат, сырьё, акции, индексы |
tier1_only |
true — только Tier-1 |
Удержание 10 %. Вход в подписку строгий, выход мягче. Стена, которую источник уже показал этому соединению, остаётся, пока usd не меньше 90 % от min_usd, а расстояние не больше max_dist_pct, делённого на 0,9, в целых базисных пунктах с округлением вверх. При min_usd: 250000 стена снимается ниже 225 000 $, при max_dist_pct: 2 — дальше 223 б.п., то есть 2,23 %. До этого приходят обычные upsert со значениями вне фильтра: не считайте их ошибкой. Остальные фильтры, min_size тоже, удержания не имеют.
Фильтры screener
| Параметр | Значение |
|---|---|
venues |
биржи массивом, тот же набор, что у /v1/screener: Upbit у скринера нет. Нет параметра — все |
markets |
массив из spot и perp. Нет параметра — все |
fields |
какие метрики слать: длинные имена из GET /v1/screener/metrics массивом. Нет параметра — все |
filters |
до 32 условий, выполняться должны все: {"metric":"volume_24h_usd","op":"gt","value":1000000}. op — gt, gte, lt, lte, eq, ne или between (вторая граница — в value2) |
hide_stables, hide_commodities, hide_stocks, hide_indices |
true — скрыть класс актива: стейблкоины и фиат, сырьё, акции, индексы |
tier1_only |
true — только Tier-1 |
Остальные параметры — bad_params с именем параметра в тексте ошибки, в том числе имена из REST (venue, market, coins). Окна и сортировки нет: top_n, sort_by, limit, offset тоже дают bad_params. Окно заморозило бы набор инструментов до следующей подписки, а подписка отдаёт весь отфильтрованный набор живьём: сузьте его через filters и сортируйте у себя.
Кадры рыночной подписки
У всех кадров этой подписки есть scope: "market", а данные лежат в items: [{"instrument", "data"}]. data — те же, что в таблице каналов.
{"type":"subscribed","id":5,"channel":"densities","scope":"market","params":{"venues":["binance"],"markets":["perp"],"min_usd":250000.0,"max_dist_pct":2.0,"agg":"tick"}}
{"type":"snapshot","channel":"densities","scope":"market","t":1793750400000,"part":1,"parts":1,"complete":true,"items":[{"instrument":"binance:perp:BTCUSDT","data":{"walls":[…]}}]}
{"type":"update","channel":"densities","scope":"market","t":1793750401000,"items":[{"instrument":"binance:perp:ETHUSDT","data":{"upsert":[…],"remove":[…]}}]}
{"type":"removed","channel":"screener","scope":"market","t":1793750402000,"instruments":["binance:perp:BTCUSDT"]}
{"type":"unsubscribed","id":7,"channel":"densities","scope":"market"}snapshot— всё состояние. Он идёт частями не длиннее 1 МиБ:partизparts. Первая часть заменяет всё, что было. Стены одного инструмента могут лежать в нескольких элементахitems— сливайте их.complete: false— снимокdensitiesнеполон. Причин четыре: шлюз выбрал предел запросов к источнику; снимок вышел за предел по байтам; срез одной биржи, рынка и стороны упёрся в предел стен, и делить его дальше нечем; источник не ответил. Числа — в пределах. Только в последнем случае за снимком приходит ещёstatusсstate: "gap"иmessage. Дальше идут только изменения, новый снимок — повторной подпиской, а при упоре в предел — с более узкими фильтрами.update— изменения, как в таблице каналов.removed— инструменты вышли из фильтров скринера или символ снят.- Стена вышла из фильтров
densitiesс учётом удержания —removeсreason: nullвupdate.
Обрыв источника подписку не снимает. Приходит status с state: "reconnecting", шлюз сам переподключается, затем state: "live" и новый snapshot — у densities шлюз снимает его заново. status рыночной подписки — со scope: "market" и без instruments.
Пределы рыночной подписки
| Что | Предел | Сверх предела |
|---|---|---|
| Рыночных подписок на аккаунт | ws_market_subs тарифа — все ключи, соединения и каналы вместе. Ноль или нет поля — значение шлюза, одна подписка |
market_subs_limit с limit, remaining: 0, scope: "account", window: "concurrent" |
| Рыночных соединений шлюза | потолок на канал, общий для всех клиентов, по умолчанию 8: на каждую подписку шлюз держит своё соединение с источником | channel_unavailable с channel, scope: "market" и retry_after |
| Открытие подписки канала | на соединении раз в секунду. Считается открытие: и замена, и снятие с повторной подпиской | rate_limited с limit: 1, remaining: 0, scope: "connection", window: "second" и retry_after, прежняя подписка, если она есть, остаётся |
Снимок densities |
100 запросов к источнику, 5000 стен на срез одной биржи, рынка и стороны, потолок шлюза по объёму снимка | complete: false |
Снимков densities одновременно |
на шлюз 4, остальные подписки ждут очереди | снимок приходит позже, изменения за это время копятся |
| Накопленные изменения | шлюз копит их, пока подписка ждёт снимок или клиент забирает очередь; объём ограничен потолком шлюза | за время снимка шлюз заново подключается к источнику, за время записи клиенту — slow_consumer и закрытие 1008 |
| Очередь к клиенту | подписка занимает не больше половины очереди и ждёт, пока клиент заберёт кадры; ответу на команду хватает любого свободного места | slow_consumer и закрытие 1008 |
| Суточный объём | кадры идут в объём тарифа вместе с REST | на исчерпанном объёме новая подписка получает daily_quota_exceeded |
Снимок может быть длиннее очереди: клиент, который читает, получит его весь. slow_consumer приходит, если клиент за 10 секунд не освободил место под кадр подписки, если очередь забита целиком дольше 10 секунд и ответу на команду некуда встать либо если изменения, пришедшие за это время, вышли за потолок шлюза.
Место возвращается отпиской или закрытием соединения. Клиент, вернувшийся раньше, чем шлюз заметил обрыв старого сокета, может получить market_subs_limit: старое место ещё занято. Повторите подписку. channel_unavailable со scope: "market" без retry_after значит, что подписку остановил сбой шлюза: место уже свободно, подпишитесь заново.
Пример
const ws = new WebSocket("wss://market-api.lootx.trade/v1/ws", ["lx.v1", `key.${apiKey}`]);
const walls = new Map(); // инструмент → wall_id → стена
const table = (name) => walls.get(name) ?? walls.set(name, new Map()).get(name);
ws.onopen = () => {
ws.send(JSON.stringify({
op: "subscribe", id: 1, channel: "densities", scope: "market",
params: { venues: ["binance"], markets: ["perp"], min_usd: 250000, max_dist_pct: 2 },
}));
};
ws.onmessage = (e) => {
const m = JSON.parse(e.data);
if (m.type === "error") return console.warn(m.code, m.message);
if (m.scope !== "market") return;
if (m.type === "snapshot") {
if (m.part === 1) walls.clear();
for (const { instrument, data } of m.items) {
for (const w of data.walls) table(instrument).set(w.wall_id, w);
}
if (m.part === m.parts && !m.complete) console.warn("снимок неполон");
} else if (m.type === "update") {
for (const { instrument, data } of m.items) {
for (const w of data.upsert) table(instrument).set(w.wall_id, w);
for (const r of data.remove) table(instrument).delete(r.wall_id);
}
}
};import asyncio, json, os
import websockets # pip install "websockets>=14"
SUBSCRIBE = {
"op": "subscribe", "id": 1, "channel": "screener", "scope": "market",
"params": {
"markets": ["perp"],
"fields": ["last_price", "volume_24h_usd"],
"filters": [{"metric": "volume_24h_usd", "op": "gt", "value": 1000000}],
},
}
async def main():
headers = {"Authorization": f"Bearer {os.environ['LOOTX_API_KEY']}"}
rows = {} # инструмент → метрики
async with websockets.connect("wss://market-api.lootx.trade/v1/ws",
additional_headers=headers) as ws:
await ws.send(json.dumps(SUBSCRIBE))
async for raw in ws:
m = json.loads(raw)
if m["type"] == "error":
print(m["code"], m["message"])
elif m.get("scope") != "market":
continue
elif m["type"] == "snapshot":
if m["part"] == 1:
rows.clear()
for item in m["items"]:
rows[item["instrument"]] = item["data"]
elif m["type"] == "update":
for item in m["items"]:
rows.setdefault(item["instrument"], {}).update(item["data"])
elif m["type"] == "removed":
for name in m["instruments"]:
rows.pop(name, None)
asyncio.run(main())Пределы
| Что | Предел | Сверх предела |
|---|---|---|
| Одновременных соединений | ws_conns тарифа, на аккаунт — все ключи вместе |
429 ws_limit при подключении |
| Подписок на соединение | 200; подписка — пара «канал + инструмент»: binance:perp:BTCUSDT в двух каналах занимает два места |
too_many_subscriptions, команда отвергается целиком |
| Команд от клиента | 10 в секунду, запас 20 | rate_limited, команда пропущена |
| Размер кадра клиента | 64 КиБ | соединение закрывается |
| Очередь кадров к клиенту | 1024 кадра или 32 МиБ | slow_consumer и закрытие 1008 |
| Рыночные подписки | свои пределы | market_subs_limit, channel_unavailable, rate_limited |
Ещё два ответа связаны с общей ёмкостью каналов: соединения шлюза с источниками делятся между всеми клиентами.
channel_unavailableсinstrument— канал сейчас выбрал свой потолок соединений с источником. Повторите подписку позже. Соscope: "market"иretry_afterэто потолок рыночных соединений шлюза.too_many_instrumentsсinstrument— ваш аккаунт уже держит свою долю канала (по умолчанию — половину его ёмкости). Подписка на инструмент, который уже кто-то смотрит, места не занимает; отписка возвращает место.
Коды закрытия
| Код | Причина в reason |
Что делать |
|---|---|---|
1008 |
slow_consumer |
клиент не успевает читать: разбирайте кадры быстрее или подпишитесь на меньшее |
1008 |
daily_quota_exceeded |
кончился суточный объём: перед закрытием приходит кадр error с limit, remaining: 0, window: "bytes_day" и scope. Сброс в 00:00 UTC (подробно) |
1008 |
revoked_key, plan_inactive, invalid_key, insufficient_scope, route_not_in_plan |
доступ кончился посреди соединения: ключ отозван, тариф закончился или в нём больше нет группы ws. Переподключение не поможет, пока не исправлен доступ |
1013 |
ws_limit |
слот соединения потерян: у аккаунта открыто больше соединений, чем разрешает тариф. Закройте лишнее и переподключитесь через 5 с |
Причина закрытия — код ошибки, не длиннее 123 байт. Кадр error перед закрытием несёт те же поля, что тело ошибки REST, — docs_url и детали лимита (подробно).
Доступ перепроверяется каждые 5 секунд; отзыв ключа закрывает поток почти сразу, конец тарифа — не позже чем через два такта. Перед закрытием приходит кадр error с тем же кодом.
Если закрылась только группа одного канала, приходит error route_not_in_plan с channel, подписки этого канала снимаются — и рыночная тоже, — а соединение живёт.
Переподключение
Свой обрыв сети клиент восстанавливает сам: переподключитесь с паузой (0,5 с, затем удваивая до 30 с) и повторите подписки. После subscribed придут свежие snapshot — состояние до обрыва выбрасывайте. Рыночную подписку повторите так же; если придёт market_subs_limit, шлюз мог ещё не заметить обрыв старого сокета: повторите ещё раз с паузой.
В SDK feed() повторяет сам только подписки, ушедшие при подключении и переподключении: на market_subs_limit и rate_limited до 3 раз, с паузой retry_after или 1, 4 и 16 с, затем отдаёт кадр error. Команды живого соединения он не повторяет, а новая рыночная команда канала, новое подключение и закрытие feed() отменяют ожидающий повтор. Пакеты SDK ещё не опубликованы: код лежит в репозитории шлюза.
https://docs.lootx.trade/hy/market-api/websocket