← Volver a la documentación
LootX

Formato HMP1 y HMP2

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

1Formato 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:

TEXT
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_scale

Tramas — HMP1 y HMP2 con layout=0

Después del encabezado, frame_count tramas consecutivas:

TEXT
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 mismo

varint — 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.

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} 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 out

La 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, code es el volumen de la celda en monedas en formato con m = qty_bits bits 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.

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]

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:

  1. Tiempo: frame_count veces varint ts_delta, zigzag best_bid_d, zigzag best_ask_d — como en una trama.
  2. Series: para bids y luego asks — varint R, después R veces zigzag idx_delta (la primera desde 0, las siguientes desde idx de la serie anterior de ese lado, estrictamente creciente) y varint run_count.
  3. Longitudes: todas las series de bids y luego asks, por cada serie varint (len − 1). La suma de longitudes por serie = frame_count.
  4. Códigos: en el mismo orden, por cada serie zigzag(code − prev), prev = 0 al 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.

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