LootX

Формат HMP1 і HMP2

Оновлено 6 листопада 2026 р. Ця сторінка у PDF

Бінарник теплової карти байт за байтом — заголовок, кадри, коди об'єму 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.