LootX

Тепловая карта стакана

Обновлено 21 ноября 2026 г. Эта страница в PDF

Объём лимитных заявок в каждой ячейке цены в каждой колонке времени — таблицей или компактным бинарём HMP1/HMP2; полосы книги — сколько долларов стоит в стакане до ±0,1…±10 % от середины.

GET/v1/heatmap

Тепловая карта стакана: объём бидов и асков в ячейках цены по колонкам времени. Группа тарифа — heatmap; тариф часто задаёт ей свои, более строгие лимиты.

Параметр Что
instrument обязательный
from начало, мс. По умолчанию — час назад от to
to конец, мс, не включительно. По умолчанию — сейчас
tf шаг колонки, кратный секунде: 1s, 5s, 1m, … По умолчанию — самый мелкий, при котором окно влезает в 4096 колонок. Если окно начинается раньше, чем сутки назад, отдаётся минутная свёртка: шаг округлится вверх до минуты
price_step высота ячейки в единицах цены: 10 — ячейки по $10 у BTCUSDT. Округляется вверх до сетки хранения; итоговый шаг — в price_step ответа. Без данных книги в минуте перед to возможен 400 bad_request: условие
agg avg (по умолчанию) — средний объём за колонку, max — максимум
price_from, price_to ценовое окно, только парой. Без него — ±20 % от середины книги
format json, protobuf, csv — таблица; hmp1, hmp2 — бинарь
qbits, layout только для format=hmp2
cursor курсор из next_cursor, если источник обрезал ответ по объёму
Shell
curl -s "https://market-api.lootx.trade/v1/heatmap?instrument=binance:perp:BTCUSDT&tf=1m&price_step=10&from=1793750400000&to=1793754000000" \
  -H "Authorization: Bearer $LOOTX_API_KEY"

Таблица содержит только ненулевые ячейки — строку на каждую пару «колонка времени × уровень цены», где объём был:

JSON
{
  "instrument": "binance:perp:BTCUSDT",
  "from": 1793750400000,
  "to": 1793754000000,
  "time_step_ms": 60000,
  "price_step": 10,
  "agg": "avg",
  "price_from": null,
  "price_to": null,
  "frames": 60,
  "columns": ["t", "side", "price", "qty"],
  "rows": [
    [1793750400000, "bid", 104240, 18.402],
    [1793750400000, "ask", 104260, 9.117]
  ],
  "next_cursor": null
}
  • price — нижняя граница ячейки: ячейка — это [price, price + price_step);
  • qty — объём в монетах, средний (agg=avg) или максимальный за колонку;
  • frames — сколько колонок времени в ответе; from выровнен наружу по шагу.

Пределы

  • До 4096 колонок и 500 000 ячеек в таблице. Больше — 413 too_large: сузьте окно, укрупните tf или price_step либо возьмите бинарь.
  • История книг у Binance длиннее; у остальных бирж стакан пишется с 30.10.2026 — раньше этой даты по ним ответ пустой, а с price_step может прийти 400, условие ниже.
  • price_step переводится в сетку хранения по данным самой книги: шлюз запрашивает минуту перед to, границы выравниваются наружу по минутной сетке. Данных в этой минуте нет — 400 bad_request, запрашивайте без price_step. Решает окно, а не статус инструмента: торгуемый инструмент с to раньше начала истории книг получит 400, снятый с торгов с данными в этой минуте — 200. Удачный перевод шлюз помнит до часа, независимо от ключа, и теряет его при перезапуске: пока он помнит, минута перед to не проверяется, и запрос без данных получит 200 с пустым ответом.
  • Бинарь hmp1/hmp2 во много раз короче таблицы, идёт потоком и кэшируется — для отрисовки берите его. Разбор — Формат HMP1 и HMP2.
  • Закрытые диапазоны бинаря отдаются с ETag и долгим Cache-Control: повторный запрос с If-None-Match получает 304 без тела и не расходует суточный объём.

Полосы книги

GET/v1/book/bands

Сколько долларов стоит в стакане в пределах ±0,1 … ±10 % от середины книги, а с bands=deep — ещё ±3, ±8, ±15 % и вся сторона — по окнам времени. Группа тарифа та же, что у тепловой карты, — heatmap.

Параметр Что
instrument обязательный
tf окно: 1s, 5s, 10s, 15s, 30s, 1m, 5m, 15m, 30m, 1h, 4h, 1d. По умолчанию 1m. Другие — 400 bad_request с param: "tf"
from начало, мс; выравнивается вниз по окну. По умолчанию — 60 окон назад от to
to конец, мс, не включительно; выравнивается вверх по окну
bands набор полос: без параметра — семь полос до ±10 %, deep — одиннадцать, до всей стороны (глубокие полосы). Другие значения — 400 bad_request с param: "bands"

Полоса — уровень книги, а не поток: значение окна — последний срез в окне, а не сумма за окно. Поэтому окна только из списка: 45s из минут не собрать.

Shell
curl -s "https://market-api.lootx.trade/v1/book/bands?instrument=binance:perp:BTCUSDT&tf=1m&from=1794500160000&to=1794500220000" \
  -H "Authorization: Bearer $LOOTX_API_KEY"
JSON
{
  "instrument": "binance:perp:BTCUSDT",
  "tf": "1m",
  "columns": ["ts", "sample_ms", "best_bid", "best_ask", "mid",
              "bid_bp10_e8", "bid_bp25_e8", "bid_bp50_e8", "bid_bp100_e8", "bid_bp200_e8", "bid_bp500_e8", "bid_bp1000_e8",
              "ask_bp10_e8", "ask_bp25_e8", "ask_bp50_e8", "ask_bp100_e8", "ask_bp200_e8", "ask_bp500_e8", "ask_bp1000_e8",
              "reach_bid_bp", "reach_ask_bp", "complete_bid", "complete_ask", "closed"],
  "rows": [
    [1794500160000, 1794500219950, 68961.0, 68961.1, 68961.05,
     "51234500000000", "98765400000000", "150000000000000", "310000000000000", "640000000000000", "1500000000000000", "2900000000000000",
     "48765400000000", "91234500000000", "140000000000000", "300000000000000", "620000000000000", "1450000000000000", "2800000000000000",
     1000, 213, 7, 5, true]
  ],
  "next_cursor": null,
  "bands_bp": [10, 25, 50, 100, 200, 500, 1000],
  "units_revision": 1,
  "source": "book_bands_1m",
  "asof_ms": 1794500325000
}
Колонка Что
ts начало окна, мс
sample_ms момент среза книги, которым представлено окно, мс
best_bid, best_ask, mid лучшие цены и середина книги в этом срезе
bid_bp…_e8 биды от середины книги вниз до −0,1 %, −0,25 %, −0,5 %, −1 %, −2 %, −5 % и −10 %: число в имени — граница в базисных пунктах
ask_bp…_e8 аски от середины вверх до тех же границ
reach_bid_bp, reach_ask_bp самая широкая граница, в базисных пунктах, все цены до которой книга знала
complete_bid, complete_ask сколько первых полос полны: полоса номер k по порядку bands_bp, с нуля, полна, если k < complete
closed окно закрыто и больше не изменится

Деньги полос — в e8 USD строкой: "51234500000000" — это 512 345 $, делите целое на 10⁸. Строкой — потому что у книг крупных монет число больше 2⁵³ и в double потеряло бы знаки: читайте его как целое 64 бита или десятичное. Шаг цены инструмента к этим суммам не относится. Полосы нарастающие: bp25 включает bp10. В примере у асков полны первые пять полос, до ±2 %, а ask_bp500_e8 и ask_bp1000_e8 неполны: книга знала аски только до 2,13 % от середины.

  • Окно без среза книги не приходит строкой: пропуск — это дыра в данных, а не нули.
  • Секундные окна (1s … 30s) есть не у всех инструментов и только за последние 7 суток, у остальных ответ пустой. Минутные и крупнее — у книг с долларовой котировкой, без срока. Таблица источника — в поле source: book_bands_1s или book_bands_1m.
  • asof_ms — до какого момента склад источника полон: окна раньше него не изменятся. units_revision — ревизия единиц источника, сейчас 1 (e8 USD).
  • Окон в запросе — до 20 000, больше — 413 too_large: сузьте окно или возьмите tf крупнее. Курсора нет, next_cursor всегда null.
  • Суммы площадок нет: полоса каждой биржи отсчитана от её середины книги и снята в свой момент. instruments= с двумя и больше инструментами — 400 bad_request: запрашивайте каждую биржу своим instrument и складывайте e8-строки сами.
  • Символ с реестром шлюз не сверяет.

Глубокие полосы

bands=deep — одиннадцать полос вместо семи: bands_bp — [10, 25, 50, 100, 200, 300, 500, 800, 1000, 1500, 10000], в ответе 32 колонки. К прежним границам добавлены ±3 %, ±8 %, ±15 % и 10000 — вся сторона: биды до нуля, аски до двух mid. Колонки идут в том же порядке, что bands_bp: bid_bp10_e8 … bid_bp10000_e8, затем ask_bp10_e8 … ask_bp10000_e8; голова и хвост строки — как без параметра.

Shell
curl -s "https://market-api.lootx.trade/v1/book/bands?instrument=binance:perp:BTCUSDT&tf=1m&bands=deep&from=1794500160000&to=1794500220000" \
  -H "Authorization: Bearer $LOOTX_API_KEY"
  • null в полосе — «неизвестно», а не 0. Так приходят глубокие полосы у строк, записанных до того, как их начали считать, и вся сторона, если книга её не знала целиком.
  • complete_* — до 11 и считается до первой неизвестной полосы: у старых строк — не больше 5.
  • Полосу берите по bands_bp, а не по номеру колонки: номера в двух наборах разные — bid_bp500_e8 шестая в обычном ответе и седьмая в глубоком.
  • Вес и группа тарифа — те же, что без параметра.