Формат 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), а не за своїм запитом.
Ціна й об’єм комірки:
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 кадрів підряд:
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 живуть у межах однієї відповіді. Стан словників після кадру — одна колонка теплової карти.
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⁶⁵ монет.
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 і лічильників кадру:
- Час:
frame_countразівvarint ts_delta,zigzag best_bid_d,zigzag best_ask_d— як у кадру. - Ряди: для бідів, потім асків —
varint R, потім R разівzigzag idx_delta(перший — від 0, далі — від idx минулого ряду цієї сторони, строго за зростанням) іvarint run_count. - Довжини: всі ряди бідів, потім асків, по кожній серії
varint (len − 1). Сума довжин по ряду =frame_count. - Коди: у тому самому порядку по кожній серії
zigzag(code − prev),prev = 0на початку кожного ряду.code = 0— рівня немає в цих колонках.
Ряд без жодного ненульового коду не пишеться. Колонку рядів не можна прочитати окремо від усього тіла — для потокового відмалювання беріть layout=0.