← К документации
LootX

Формат HMP1 и HMP2

Собрано: 2026-11-21 docs.lootx.trade
Форматы и потоки

1Формат HMP1 и HMP2

Бинарь тепловой карты байт за байтом — заголовок, кадры, коды объёма HMP2 и ряды цены, с декодером на Python.

GET /v1/heatmap?format=hmp1 или format=hmp2 отдаёт тепловую карту не таблицей, а бинарём: он во много раз короче таблицы, идёт потоком и кэшируется. Его удобно рисовать — разбирать можно кадр за кадром, не дожидаясь конца тела. Параметры запроса — те же, что у таблицы.

format Что внутри Content-Type
hmp1 объёмы точными целыми application/octet-stream
hmp2 объём кодом в 6–9 бит, короче HMP1; qbits — бит мантиссы (6–9, по умолчанию 6), layout — 0 кадры или 1 ряды application/x-hmp2

format=hmp1|hmp2 у других маршрутов — 400 bad_format; qbits или layout без format=hmp2 — 400 bad_request. Ошибки приходят JSON, как всегда.

Кэш и объём

Заголовок ставит источник тепловой карты, шлюз передаёт его как есть:

Cache-Control Когда
no-store окно кончается в последней минуте — живой край
public, max-age=600 конец окна не старше 50 часов: ремонт из архива ещё может залить дыры
public, max-age=86400, immutable старше

У закрытых диапазонов есть ETag. Повторный запрос с If-None-Match: <ETag> получает 304 Not Modified без тела — суточный объём он не расходует. Оборванная загрузка расходует столько байт, сколько успела получить.

Заголовок

Little-endian, 48 байт:

Смещение Размер Поле
0 4 magic: HMP1 или HMP2
4 2 version: 1 у HMP1, 2 у HMP2
6 2 flags
8 8 bucket_size (i64) — высота ячейки в единицах price_scale
16 1 price_scale (u8)
17 1 qty_scale (u8)
18 1 HMP1: 0; HMP2: qty_bits (6–9)
19 1 HMP1: 0; HMP2: layout (0 — кадры, 1 — ряды)
20 4 time_step_ms (u32)
24 8 from_ms (i64)
32 8 to_ms (i64)
40 4 frame_count (u32) — число колонок времени
44 4 stream_id (u32), у REST 0

flags: бит 0 — значения агрегированы максимумом (иначе средним); бит 1 — ответ упёрся в потолок тела источника (16 МБ) и обрезан справа по времени. Продолжение — тот же запрос с from = время последнего кадра + time_step_ms.

Разбирайте ответ по заголовку (magic, version, layout), а не по своему запросу.

Цена и объём ячейки:

TEXT
price = idx * bucket_size / 10^price_scale     нижняя граница ячейки [price, price + шаг)
qty   = q / 10^qty_scale                       в монетах
шаг   = bucket_size / 10^price_scale

Кадры — HMP1 и HMP2 с layout=0

После заголовка — frame_count кадров подряд:

TEXT
varint  ts_delta_ms    от ts предыдущего кадра; у первого — от from_ms
u8      kind           1 = KEY (полное состояние), 0 = DELTA (изменения)
zigzag  best_bid_d     разность к best_bid предыдущего кадра; у первого — к 0
zigzag  best_ask_d     то же для best_ask
varint  bid_count
  bid_count раз:
    zigzag  idx_delta  к idx предыдущей ячейки; у первой — к 0
    varint  qty        АБСОЛЮТНЫЙ объём ячейки (в HMP2 — код); 0 = уровень исчез
varint  ask_count
  ask_count раз:       то же самое

varint — LEB128 без знака. zigzag — LEB128 поверх (n << 1) ^ (n >> 63), раскодируется как (u >> 1) ^ -(u & 1).

Держите два словаря idx → qty, для бидов и асков:

  • KEY — словари замещаются содержимым кадра;
  • DELTA — накладывается поверх: qty > 0 — присвоить, qty == 0 — удалить ключ.

Первый кадр всегда KEY, дальше KEY повторяется каждые 512 кадров. Счётчики ts, best_bid, best_ask живут в пределах одного ответа. Состояние словарей после кадра — одна колонка тепловой карты.

Python
import struct

def uvarint(b, p):
    out = shift = 0
    while True:
        x = b[p]; p += 1
        out |= (x & 0x7F) << shift
        if x < 0x80:
            return out, p
        shift += 7

def svarint(b, p):
    u, p = uvarint(b, p)
    return (u >> 1) ^ -(u & 1), p

def columns(b):
    """HMP1 -> [(ts, {price: qty} биды, {price: qty} аски)]."""
    assert b[:4] == b"HMP1"
    bucket, ps, qs = struct.unpack_from("<qBB", b, 8)
    step_ms, from_ms, _to, frames = struct.unpack_from("<IqqI", b, 20)
    if frames == 0:
        return []
    bid, ask, out, p, ts = {}, {}, [], 48, from_ms
    for _ in range(frames):
        d, p = uvarint(b, p); ts += d
        kind = b[p]; p += 1
        _, p = svarint(b, p); _, p = svarint(b, p)        # best_bid_d, best_ask_d
        for book in (bid, ask):
            n, p = uvarint(b, p)
            cells, idx = [], 0
            for _ in range(n):
                di, p = svarint(b, p); idx += di
                q, p = uvarint(b, p)
                cells.append((idx, q))
            if kind == 1:
                book.clear()
                book.update((i, q) for i, q in cells if q > 0)
            else:
                for i, q in cells:
                    if q: book[i] = q
                    else: book.pop(i, None)
        price = lambda i: i * bucket / 10**ps
        out.append((ts,
                    {price(i): q / 10**qs for i, q in sorted(bid.items())},
                    {price(i): q / 10**qs for i, q in sorted(ask.items())}))
    assert p == len(b), "после кадров остались байты"
    return out

Таблица format=json — ровно этот разбор: строка на каждую ненулевую ячейку каждой колонки.

HMP2: объём кодом

Кадры с layout=0 — байт в байт как у HMP1, но вместо varint qty стоит varint code:

  • code = 0 — уровня нет (в DELTA — «уровень исчез»);
  • иначе code — объём ячейки в монетах в формате с m = qty_bits битами мантиссы.

DELTA сравнивает коды: ячейка, у которой код не сменился, в DELTA не попадает, даже если сырой объём чуть сдвинулся.

Раскодирование (d = 23 − m): code = 0 → 0, иначе v = from_bits(((code + (64 << m)) << d) as u32) как float32 — объём в монетах, qty_scale к нему уже не применяется. При m = 9 ошибка не больше 2⁻¹⁰, диапазон — от 2⁻⁶³ до 2⁶⁵ монет.

Python
import struct

def hmp2_qty(code, m):
    if code == 0:
        return 0.0
    bits = (code + (64 << m)) << (23 - m)
    return struct.unpack("<f", struct.pack("<I", bits))[0]

Векторы для проверки своей реализации:

Объём Код m=9 Обратно Код m=6 Обратно
1e-8 18607 9.997166e-9 2326 1.0011718e-8
0.001 27148 0.0009994507 3394 0.0010070801
0.5 31744 0.5 3968 0.5
1 32256 1 4032 1
1023 37375 1023 4672 1024
12345.678 39172 12352 4896 12288

HMP2, layout=1: ряды цены

Тот же заголовок с байтом 19 = 1. Тело — четыре потока подряд, без kind и счётчиков кадра:

  1. Время: frame_count раз varint ts_delta, zigzag best_bid_d, zigzag best_ask_d — как у кадра.
  2. Ряды: для бидов, затем асков — varint R, потом R раз zigzag idx_delta (первый — от 0, дальше — от idx прошлого ряда этой стороны, строго по возрастанию) и varint run_count.
  3. Длины: все ряды бидов, затем асков, по каждой серии varint (len − 1). Сумма длин по ряду = frame_count.
  4. Коды: в том же порядке по каждой серии zigzag(code − prev), prev = 0 в начале каждого ряда. code = 0 — уровня нет в этих колонках.

Ряд без единого ненулевого кода не пишется. Колонку рядов нельзя прочитать отдельно от всего тела — для потоковой отрисовки берите layout=0.

https://docs.lootx.trade/ru/market-api/heatmap-binary