Ir al contenido principal

L2 Order Book Dataset

Actualizado el
10 de junio de 2026

Resumen​

El StreamL2Book stream delivers aggregated price-level depth for a given coin. Each message contains the full L2 snapshot — total size and order count at each price level — refreshed every block.

gRPC : OrderBookStreaming
gRPC : StreamL2Book
Modelo de actualización: Full snapshot every block — no client-side state management required

Cómo funciona​

Instant, ongoing access to the full L2 order book: StreamL2Book delivers a complete L2 snapshot every block. There is no need to:

  • Fetch an initial snapshot from the REST Info endpoint
  • Stitch incremental diffs onto a snapshot
  • Handle race conditions during the snapshot-to-diff transition
  • Re-bootstrap on reconnect

Each message is the full current state of the order book at that block, aggregated by price level.

Estructura de datos​

Each L2BookUpdate message contains the full aggregated book at the time of a block:

{
  "coin": "BTC",
  "time": 1764867600518,
  "block_number": 817863403,
  "bids": [
    { "px": "95000.0", "sz": "12.5432", "n": 47 },
    { "px": "94999.5", "sz": "8.2100", "n": 23 },
    { "px": "94999.0", "sz": "5.0000", "n": 12 }
  ],
  "asks": [
    { "px": "95000.5", "sz": "10.8900", "n": 38 },
    { "px": "95001.0", "sz": "6.3210", "n": 15 },
    { "px": "95001.5", "sz": "3.7500", "n": 9 }
  ]
}

Parámetros de la solicitud​

CampoTipoObligatorioDescripción
monedacadenaSíSímbolo para suscribirse: en los contratos perpetuos se utilizan nombres (p. ej., «BTC», «ETH»), mientras que en el mercado al contado se utiliza el formato @índice (p. ej., «@142»)
n_nivelesuint32SíMaximum number of price levels to return per side (default 20, max 100)
n_sig_figsuint32NoSignificant figures for price bucketing (2–5). Omit for exact price-level aggregation.
mantissauint64NoMantissa for price bucketing (1, 2, or 5). Used with n_sig_figs to control bucket width.

Denominación de las monedas​

El moneda El parámetro sigue la convención de nomenclatura Hyperliquid, que distingue sin ambigüedades entre los contratos perpetuos y los al contado:

  • Perpetuos: Nombres legibles para las personas — «BTC», «ETH», «HYPE», «SOL»
  • Fichas al contado: @{índice} formato — "@1", «@107», «@142», «@166»
  • Mercados de resultados (HIP-4): #N formato. Cada resultado tiene dos #N monedas: una por cada opción (Sí y No). Los mercados de preguntas con precios múltiples se componen de varios resultados agrupados (rangos de precios más una opción de reserva), cada uno con su propio par de monedas «Sí/No». Utiliza el outcomeMeta endpoint asignar los índices de las monedas a los nombres y lados del mercado.
  • Excepción: «PURR/USDC» es la única moneda de la serie «Spot» cuyo nombre se puede leer

No hay solapamiento entre los formatos. «BTC» siempre se refiere al contrato perpetuo de BTC; el BTC al contado es «@142». Para descubrir @índice asignaciones para tokens puntuales, consultar el meta o spotMeta puntos de información.

Price Bucketing​

The optional n_sig_figs y mantissa parameters control how prices are aggregated into buckets. When omitted, each distinct price level is reported individually. When set, orders are grouped into price buckets — for example, bucketing BTC orders into $100 increments instead of exact prices.

  • n_sig_figs (2–5): Number of significant figures in the bucket price
  • mantissa (1, 2, or 5): Mantissa multiplier for the bucket width

Campos de respuesta​

L2BookUpdate​

CampoTipoDescripción
monedacadenaSímbolo (p. ej., «BTC», «ETH»)
tiempouint64Marca de tiempo del bloque en milisegundos
número_de_bloqueuint64Block number
ofertasL2Level[]Aggregated bid levels, ordered best (highest) price first
preguntaL2Level[]Aggregated ask levels, ordered best (lowest) price first

L2Level​

CampoTipoDescripción
pxcadenaPrice as a decimal string
szcadenaTotal size across all orders at this price level, as a decimal string
nuint32Number of individual orders at this price level

Definición de «Proto»​

StreamL2Book se define en orderbook.proto:

service OrderBookStreaming {
  rpc StreamL2Book (L2BookRequest) returns (stream L2BookUpdate);
}

message L2BookRequest {
  string coin = 1;
  uint32 n_levels = 2;
  optional uint32 n_sig_figs = 3;
  optional uint64 mantissa = 4;
}

message L2BookUpdate {
  string coin = 1;
  uint64 time = 2;
  uint64 block_number = 3;
  repeated L2Level bids = 4;
  repeated L2Level asks = 5;
}

message L2Level {
  string px = 1;
  string sz = 2;
  uint32 n = 3;
}

Ejemplos de actualizaciones​

Full L2 Snapshot (top 5 levels)
{
  "coin": "BTC",
  "time": 1764867600518,
  "block_number": 817863403,
  "bids": [
    { "px": "95000.0", "sz": "12.5432", "n": 47 },
    { "px": "94999.5", "sz": "8.2100", "n": 23 },
    { "px": "94999.0", "sz": "5.0000", "n": 12 },
    { "px": "94998.0", "sz": "3.1250", "n": 8 },
    { "px": "94997.5", "sz": "1.7500", "n": 5 }
  ],
  "asks": [
    { "px": "95000.5", "sz": "10.8900", "n": 38 },
    { "px": "95001.0", "sz": "6.3210", "n": 15 },
    { "px": "95001.5", "sz": "3.7500", "n": 9 },
    { "px": "95002.0", "sz": "2.5000", "n": 6 },
    { "px": "95003.0", "sz": "1.2000", "n": 3 }
  ]
}
L2 Snapshot with Price Bucketing

When using n_sig_figs=3 y mantissa=1, prices are aggregated into broader buckets:

{
  "coin": "BTC",
  "time": 1764867600518,
  "block_number": 817863403,
  "bids": [
    { "px": "95000.0", "sz": "25.8782", "n": 82 },
    { "px": "94900.0", "sz": "18.4300", "n": 61 },
    { "px": "94800.0", "sz": "12.1000", "n": 34 }
  ],
  "asks": [
    { "px": "95100.0", "sz": "21.0110", "n": 62 },
    { "px": "95200.0", "sz": "14.7210", "n": 40 },
    { "px": "95300.0", "sz": "8.9500", "n": 18 }
  ]
}

Uso de la API​

gRPC
// Perp order book
const request = {
  coin: 'BTC',
  n_levels: 20
};

// Spot order book (@ index format)
const spotRequest = {
  coin: '@142',
  n_levels: 20
};

// With price bucketing
const bucketedRequest = {
  coin: 'BTC',
  n_levels: 20,
  n_sig_figs: 3,
  mantissa: 1
};

gRPC

StreamL2Book solo está disponible a través de la API gRPC (OrderBookStreaming servicio). No está disponible a través de JSON-RPC ni de WebSocket.

Comparison with Book Updates Dataset​

CaracterísticaStreamL2BookBOOK_UPDATES (StreamData)
Includes current book stateYes — every message is a full snapshotNo — forward-only diffs from subscribe time
Requiere el arranque de RESTNoYes (Info endpoint l2Book)
Client-side state managementNingunoBuild and maintain local book from diffs
Data granularityAgrupados por nivel de preciosDiferencias a nivel de pedido individual
Reconnect handlingAutomatic — full snapshot resumesMust re-bootstrap from REST
Price bucketingSupported (n_sig_figs, mantissa)Not available

Notas importantes​


  • Full snapshot every block: Each L2BookUpdate is a complete snapshot — no need to track state across messages
  • zstd compression recommended: Enable zstd compression on your gRPC channel to reduce bandwidth, especially when streaming multiple coins

  • StreamL4Book - Individual order granularity with user, oid, size, triggers, and timestamps
  • StreamBboBook - Top-of-book best bid/ask, emitted only when the BBO changes
  • StreamL2BookDiff - Incremental L2 price-level changes with sequence numbers
  • Book Updates - Forward-only incremental diffs via StreamData
  • Órdenes - Eventos del ciclo de vida de los pedidos (pendientes, completados, cancelados, etc.)
  • Operaciones - Datos de operaciones ejecutadas con información sobre «maker» y «taker»
Última actualización en