Тепловая карта стакана
Объём лимитных заявок в каждой ячейке цены в каждой колонке времени — таблицей или компактным бинарём HMP1/HMP2; полосы книги — сколько долларов стоит в стакане до ±0,1…±10 % от середины.
/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, если источник обрезал ответ по объёму |
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"Таблица содержит только ненулевые ячейки — строку на каждую пару «колонка времени × уровень цены», где объём был:
{
"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без тела и не расходует суточный объём.
Полосы книги
/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 из минут не собрать.
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"{
"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; голова и хвост строки — как без параметра.
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шестая в обычном ответе и седьмая в глубоком. - Вес и группа тарифа — те же, что без параметра.