L2 Book Diff Dataset

Resumen

El StreamL2BookDiff stream delivers incremental L2 price-level changes for one or more coins instead of full snapshots. Each message contains only the levels that changed since the previous block, allowing clients to maintain a local L2 order book efficiently with far less bandwidth than full snapshots.

gRPC : OrderBookStreaming
gRPC : StreamL2BookDiff
Modelo de actualización: Initial per-coin snapshot (optional), then incremental diffs per block with sequence numbers

Cómo funciona

Al suscribirse: Unless skip_initial_snapshot is set, the first update for each coin contains the current price levels as a snapshot (snapshot: true on the message and the per-coin diff)
A partir de ahí, por bloque: Each L2BookDiffUpdate contains only the price levels that changed. A level with sz: "0" means the level was removed
Apply diffs to your local copy of the book, using seq/prev_seq to verify continuity: each coin's diff carries a sequence number, and prev_seq should match the seq of the previous diff you applied for that coin

A single stream can cover multiple coins (or all coins with an empty coins list). The maximum tracked depth per side defaults to 20 levels, matching StreamL2Book, and the same price-bucketing parameters (n_sig_figs, mantissa) are supported.

Estructura de datos

Initial snapshot (first message per coin)

{
  "time": 1781109048255,
  "height": 586404776,
  "snapshot": true,
  "diffs": [
    {
      "coin": "BTC",
      "seq": 1,
      "snapshot": true,
      "bids": [
        { "px": "62963", "sz": "0.00072", "n": 2 },
        { "px": "62959", "sz": "0.001", "n": 1 }
      ],
      "asks": [
        { "px": "63054", "sz": "0.00008", "n": 1 },
        { "px": "63082", "sz": "0.00035", "n": 1 }
      ]
    }
  ]
}

Diferencia (mensajes posteriores)

{
  "time": 1781109048660,
  "height": 586404778,
  "diffs": [
    {
      "coin": "BTC",
      "seq": 2,
      "prev_seq": 1,
      "asks": [
        { "px": "63168", "sz": "0.00001", "n": 1 },
        { "px": "63210", "sz": "0" }
      ]
    }
  ]
}

A level with sz: "0" has been removed from the book; any other level value replaces the previous state at that price.

Parámetros de la solicitud

Campo	Tipo	Obligatorio	Descripción
coins	repeated string	No	List of symbols to subscribe to (e.g., "BTC", "ETH"). Empty means all coins
n_niveles	uint32	Sí	Maximum number of price levels tracked per side (default 20, max 100)
n_sig_figs	uint32	No	Significant figures for price bucketing (2–5). Omit for exact price-level aggregation.
mantissa	uint64	No	Mantissa for price bucketing (1, 2, or 5). Used with n_sig_figs to control bucket width.
skip_initial_snapshot	bool	No	If false (default), the first update per coin contains the current levels as a snapshot

Denominación de las monedas

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

Perpetuos: Human-readable names, such as «BTC», «ETH», «HYPE», «SOL»
Fichas al contado: @{índice} format, such as "@1", «@107», «@142», «@166»
Mercados de resultados (HIP-4): #N formato. Cada resultado tiene dos #N coins, one per side (Yes and No). Multi-price question markets consist of multiple grouped outcomes (price buckets plus a fallback), each with its own Yes/No coin pair. Use the 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.

Campos de respuesta

L2BookDiffUpdate

Campo	Tipo	Descripción
tiempo	uint64	Marca de tiempo del bloque en milisegundos
altura	uint64	Altura del bloque
instantánea	bool	True when this update carries the initial levels as a snapshot for any coin
diffs	L2CoinDiff[]	Per-coin diffs of changed price levels

L2CoinDiff

Campo	Tipo	Descripción
moneda	cadena	Símbolo (p. ej., «BTC», «ETH»)
seq	uint64	Per-coin sequence number of this diff
prev_seq	uint64	Sequence number of the previous diff for this coin. Compare against the last applied seq to detect gaps
ofertas	L2Level[]	Changed bid levels. A level with sz "0" was removed
pregunta	L2Level[]	Changed ask levels. A level with sz "0" was removed
instantánea	bool	True when this diff carries the initial levels for the coin as a snapshot

L2Level

Campo	Tipo	Descripción
px	cadena	Price as a decimal string
sz	cadena	Total size across all orders at this price level, as a decimal string. "0" means the level was removed
n	uint32	Number of individual orders at this price level (0/omitted on removed levels)

Definición de «Proto»

StreamL2BookDiff se define en orderbook.proto:

service OrderBookStreaming {
  rpc StreamL2BookDiff (L2BookDiffRequest) returns (stream L2BookDiffUpdate);
}

message L2BookDiffRequest {
  repeated string coins = 1;
  uint32 n_levels = 2;
  optional uint32 n_sig_figs = 3;
  optional uint64 mantissa = 4;
  bool skip_initial_snapshot = 5;
}

message L2BookDiffUpdate {
  uint64 time = 1;
  uint64 height = 2;
  bool snapshot = 3;
  repeated L2CoinDiff diffs = 4;
}

message L2CoinDiff {
  string coin = 1;
  uint64 seq = 2;
  uint64 prev_seq = 3;
  repeated L2Level bids = 4;
  repeated L2Level asks = 5;
  bool snapshot = 6;
}

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

Ejemplos de actualizaciones

Initial Snapshot (first message)

{
  "time": 1781109048255,
  "height": 586404776,
  "snapshot": true,
  "diffs": [
    {
      "coin": "BTC",
      "seq": 1,
      "snapshot": true,
      "bids": [
        { "px": "62963", "sz": "0.00072", "n": 2 },
        { "px": "62959", "sz": "0.001", "n": 1 },
        { "px": "62955", "sz": "0.00015", "n": 1 },
        { "px": "62922", "sz": "0.00074", "n": 1 },
        { "px": "62892", "sz": "0.00035", "n": 1 }
      ],
      "asks": [
        { "px": "63054", "sz": "0.00008", "n": 1 },
        { "px": "63082", "sz": "0.00035", "n": 1 },
        { "px": "63146", "sz": "0.00035", "n": 1 },
        { "px": "63187", "sz": "0.00074", "n": 1 },
        { "px": "63210", "sz": "0.00035", "n": 1 }
      ]
    }
  ]
}

Incremental Diff (level added and level removed)

A level with sz: "0" means the level was removed:

{
  "time": 1781109048660,
  "height": 586404778,
  "diffs": [
    {
      "coin": "BTC",
      "seq": 2,
      "prev_seq": 1,
      "asks": [
        { "px": "63168", "sz": "0.00001", "n": 1 },
        { "px": "63210", "sz": "0" }
      ]
    }
  ]
}

Level Size Change Only

{
  "time": 1781109050268,
  "height": 586404788,
  "diffs": [
    { "coin": "BTC", "seq": 3, "prev_seq": 2,
      "bids": [ { "px": "62963", "sz": "0.00052", "n": 2 } ] }
  ]
}

When skip_initial_snapshot is verdadero, the first message is a plain diff (no instantánea flags) with seq starting at 1.

Uso de la API

gRPC

// Single coin
const request = {
  coins: ['BTC'],
  n_levels: 20
};

// Multiple coins with price bucketing
const bucketedRequest = {
  coins: ['BTC', 'ETH'],
  n_levels: 20,
  n_sig_figs: 3,
  mantissa: 1
};

// Diffs only, no initial snapshot
const diffOnlyRequest = {
  coins: ['BTC'],
  n_levels: 20,
  skip_initial_snapshot: true
};

gRPC

StreamL2BookDiff 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 StreamL2Book

Característica	StreamL2BookDiff	StreamL2Book
Data per message	Only changed price levels	Full snapshot every block
Includes current book state	Yes (initial per-coin snapshot)	Yes (every message)
Client-side state management	Apply diffs to local book, track seq	Ninguno
Gap detection	seq / prev_seq per coin	Not needed
Coins per stream	Multiple (or all coins)	One coin per stream
Ancho de banda	Bajo (solo diferencias)	Medio (limitado por n_levels)
Price bucketing	Supported (n_sig_figs, mantissa)	Supported (n_sig_figs, mantissa)
Ideal para	Efficient local book maintenance at scale	Simplest depth consumption

Notas importantes

sz: "0" means removed: A changed level with size "0" (and n 0/omitted) has been removed from the book. Delete it from your local state
Track sequence numbers: Verify prev_seq matches the last seq you applied per coin; on a gap, resubscribe to receive a fresh snapshot
Default depth matches StreamL2Book: n_niveles defaults to 20 tracked levels per side (max 100)
Multi-coin in one stream: A single subscription can cover multiple coins (or all coins). Demultiplex by the moneda field on each diff
zstd compression recommended: Enable zstd compression on your gRPC channel to reduce bandwidth, especially when streaming multiple coins

StreamL2Book - Aggregated price-level depth, full snapshot every block
StreamBboBook - Top-of-book best bid/ask, emitted only when the BBO changes
Book Updates - Forward-only incremental diffs via StreamData

Resumen​

Cómo funciona​

Estructura de datos​

Initial snapshot (first message per coin)​

Diferencia (mensajes posteriores)​

Parámetros de la solicitud​

Denominación de las monedas​

Campos de respuesta​

L2BookDiffUpdate​

L2CoinDiff​

L2Level​

Definición de «Proto»​

Ejemplos de actualizaciones​

Uso de la API​

Comparison with StreamL2Book​

Notas importantes​

Streams relacionados​