Formato HMP1 y HMP2
El binario del mapa de calor byte a byte: encabezado, tramas, códigos de volumen HMP2 y series de precio, con decodificador en Python.
GET /v1/heatmap?format=hmp1 o format=hmp2 devuelve el mapa de calor no como tabla, sino como binario: es mucho más corto que la tabla, se transmite como flujo y se almacena en caché. Es cómodo de dibujar: se puede analizar trama por trama, sin esperar el fin del cuerpo. Los parámetros de la solicitud son los mismos que los de la tabla.
format |
Qué contiene | Content-Type |
|---|---|---|
hmp1 |
volúmenes como enteros exactos | application/octet-stream |
hmp2 |
volumen codificado en 6–9 bits, más corto que HMP1; qbits — bits de mantisa (6–9, por defecto 6), layout — 0 tramas o 1 series |
application/x-hmp2 |
format=hmp1|hmp2 en otras rutas — 400 bad_format; qbits o layout sin format=hmp2 — 400 bad_request. Los errores llegan en JSON, como siempre.
Caché y volumen
El encabezado establece la fuente del mapa de calor; el gateway lo transmite tal cual:
Cache-Control |
Cuándo |
|---|---|
no-store |
la ventana termina en el último minuto: borde vivo |
public, max-age=600 |
el fin de la ventana no tiene más de 50 horas: la reparación desde el archivo aún puede llenar huecos |
public, max-age=86400, immutable |
más antigua |
Los rangos cerrados tienen ETag. Una solicitud repetida con If-None-Match: <ETag> recibe 304 Not Modified sin cuerpo: no consume volumen diario. Una descarga interrumpida consume tantos bytes como logró recibir.
Encabezado
Little-endian, 48 bytes:
| Desplazamiento | Tamaño | Campo |
|---|---|---|
| 0 | 4 | magic: HMP1 o HMP2 |
| 4 | 2 | version: 1 en HMP1, 2 en HMP2 |
| 6 | 2 | flags |
| 8 | 8 | bucket_size (i64): altura de la celda en unidades de 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 — tramas, 1 — series) |
| 20 | 4 | time_step_ms (u32) |
| 24 | 8 | from_ms (i64) |
| 32 | 8 | to_ms (i64) |
| 40 | 4 | frame_count (u32): número de columnas de tiempo |
| 44 | 4 | stream_id (u32), en REST 0 |
flags: bit 0 — los valores se agregaron por máximo (de lo contrario, por promedio); bit 1 — la respuesta alcanzó el techo del cuerpo de origen (16 MB) y se truncó por la derecha en el tiempo. Continuación: la misma solicitud con from = tiempo del último fotograma + time_step_ms.
Analice la respuesta según el encabezado (magic, version, layout), no según su solicitud.
Precio y volumen de la celda:
price = idx * bucket_size / 10^price_scale límite inferior de la celda [price, price + paso)
qty = q / 10^qty_scale en monedas
paso = bucket_size / 10^price_scaleTramas — HMP1 y HMP2 con layout=0
Después del encabezado, frame_count tramas consecutivas:
varint ts_delta_ms desde ts de la trama anterior; en la primera, desde from_ms
u8 kind 1 = KEY (estado completo), 0 = DELTA (cambios)
zigzag best_bid_d diferencia con best_bid de la trama anterior; en la primera, con 0
zigzag best_ask_d lo mismo para best_ask
varint bid_count
bid_count veces:
zigzag idx_delta con idx de la celda anterior; en la primera, con 0
varint qty volumen ABSOLUTO de la celda (en HMP2, código); 0 = el nivel desapareció
varint ask_count
ask_count veces: lo mismovarint — LEB128 sin signo. zigzag — LEB128 sobre (n << 1) ^ (n >> 63), se decodifica como (u >> 1) ^ -(u & 1).
Mantenga dos diccionarios idx → qty, para bids y asks:
- KEY — los diccionarios se reemplazan por el contenido de la trama;
- DELTA — se superpone:
qty > 0— asignar,qty == 0— eliminar la clave.
La primera trama siempre es KEY, después KEY se repite cada 512 tramas. Los contadores ts, best_bid, best_ask viven dentro de una respuesta. El estado de los diccionarios tras la trama es una columna del mapa de calor.
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} bids, {price: qty} asks)]."""
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), "quedan bytes después de las tramas"
return outLa tabla format=json es exactamente este análisis: una fila por cada celda no nula de cada columna.
HMP2: volumen codificado
Las tramas con layout=0 son byte a byte como en HMP1, pero en lugar de varint qty va varint code:
code = 0— no hay nivel (en DELTA, «el nivel desapareció»);- de lo contrario,
codees el volumen de la celda en monedas en formato conm = qty_bitsbits de mantisa.
DELTA compara códigos: una celda cuyo código no cambió no entra en DELTA, incluso si el volumen bruto se desplazó ligeramente.
Decodificación (d = 23 − m): code = 0 → 0, de lo contrario v = from_bits(((code + (64 << m)) << d) as u32) como float32 — volumen en monedas; qty_scale ya no se le aplica. Con m = 9, el error no supera 2⁻¹⁰, el rango es de 2⁻⁶³ a 2⁶⁵ monedas.
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]Vectores para verificar su implementación:
| Volumen | Código m=9 | Inverso | Código m=6 | Inverso |
|---|---|---|---|---|
| 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: series de precio
El mismo encabezado con byte 19 = 1. El cuerpo son cuatro flujos consecutivos, sin kind ni contadores de trama:
- Tiempo:
frame_countvecesvarint ts_delta,zigzag best_bid_d,zigzag best_ask_d— como en una trama. - Series: para bids y luego asks —
varint R, después R veceszigzag idx_delta(la primera desde 0, las siguientes desde idx de la serie anterior de ese lado, estrictamente creciente) yvarint run_count. - Longitudes: todas las series de bids y luego asks, por cada serie
varint (len − 1). La suma de longitudes por serie =frame_count. - Códigos: en el mismo orden, por cada serie
zigzag(code − prev),prev = 0al inicio de cada serie.code = 0— no hay nivel en esas columnas.
Una serie sin un solo código no nulo no se escribe. Una columna de series no se puede leer separada del cuerpo completo: para renderizado en flujo use layout=0.