LootX

Потоки WebSocket

Actualizado 21 de noviembre de 2026 Esta página en PDF

Одно соединение /v1/ws на несколько каналов — плотности, скринер, сделки, открытый интерес и секундные свечи; подписка по инструментам или на весь рынок с фильтрами, команды, кадры, пределы и коды закрытия.

Esta página aún no está traducida a tu idioma — mostramos el original.

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. В адрес ключ не кладётся.

JavaScript
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);
Python
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 КиБ:

JSON
{"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_volume REST; объёма в монетах в канале нет.

Канал, группа которого закрыта тарифом, отвечает на подписку 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. У screener hyperliquid:perp:BTCUSDC читается по его списку инструментов: монета без акции с таким именем идёт как hyperliquid:perp:BTC, остальное — как акция.
  • На screener дека нет: AAPLUSDC.XYZ и AAPLUSDC идут как hyperliquid:perp:AAPLUSDC, кадр один на все деки монеты.
  • Имя, которое не собирается обратно из имени источника (опечатка, котировка вне списка шлюза), идёт как написал клиент. На oi у bingx BT-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.

JSON
{"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 — те же, что в таблице каналов.

JSON
{"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 значит, что подписку остановил сбой шлюза: место уже свободно, подпишитесь заново.

Пример

JavaScript
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);
    }
  }
};
Python
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 ещё не опубликованы: код лежит в репозитории шлюза.