Ir al contenido principal

L4 Book Updates Dataset

Actualizado el
18 de julio de 2026

Resumen​

El StreamL4BookUpdates stream delivers typed order-level book changes as NEW, UPDATE, y REMOVE diffs for one or more coins. It gives clients per-order L4 movement without consuming full L4 book snapshots every block, and without parsing JSON-encoded payloads: every diff is a strongly typed protobuf message.

gRPC : OrderBookStreaming
gRPC : StreamL4BookUpdates
Modelo de actualización: Full reset snapshot on subscribe and for mid-stream replacement resets, then typed per-order diffs per block

Cómo funciona​

  1. Al suscribirse: The first message has snapshot: true and contains every resting order as a L4_ORDER_DIFF_TYPE_NEW diff, a full reset snapshot of the book
  2. A partir de ahí, por bloque: Each L4BookUpdatesUpdate contains typed diffs for orders that changed: NEW (order entered the book), UPDATE (order size changed), REMOVE (order left the book, sz is omitted)
  3. Apply diffs to a local order map keyed by oide to maintain the current book
  4. Replacement resets: Any later message can also have snapshot: true, for example when an ALO priority fee insertion changes queue order or when stream state is rebuilt. Whenever a message has snapshot: true, clear the keyed local order state before applying its diffs, not only on the first message

Unlike StreamL4Book, which sends diffs as a JSON-encoded datos string, every field here is a typed protobuf field, so no secondary JSON parsing is required. A single stream can cover multiple coins (or all coins with an empty coins list).

Estructura de datos​

Each L4BookUpdatesUpdate message contains the typed diffs for one block:

{
  "time": 1781109115476,
  "height": 586405189,
  "diffs": [
    { "diff_type": "L4_ORDER_DIFF_TYPE_NEW", "coin": "ETH", "oid": 54764586686,
      "user": "0x768484F7e2EBB675C57838366C02Ae99ba2A9B08", "side": "B", "px": "1649.1", "sz": "1.022" }
  ]
}

Parámetros de la solicitud​

CampoTipoObligatorioDescripción
coinsrepeated stringNoList of symbols to subscribe to (e.g., "BTC", "ETH"). Empty means all coins

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​

L4BookUpdatesUpdate​

CampoTipoDescripción
tiempouint64Marca de tiempo del bloque en milisegundos
alturauint64Altura del bloque
instantáneaboolTrue when the diffs carry a full reset snapshot of all resting orders (sent on subscribe and for mid-stream replacement resets)
diffsL4OrderDiff[]Typed per-order diffs for this block

L4OrderDiff​

CampoTipoDescripción
diff_typeL4OrderDiffTypeL4_ORDER_DIFF_TYPE_NEW (order entered the book), L4_ORDER_DIFF_TYPE_UPDATE (order size changed), or L4_ORDER_DIFF_TYPE_REMOVE (order left the book)
monedacadenaSímbolo (p. ej., «BTC», «ETH»)
oideuint64N.º de pedido único
usuariocadenaEthereum de Ethereum del titular del pedido
ladocadena«A» (precio de venta/oferta) o «B» (precio de compra/demanda)
pxcadenaOrder price as a decimal string
szcadenaNew/current order size for NEW and UPDATE diffs. Omitted on REMOVE

Definición de «Proto»​

StreamL4BookUpdates se define en orderbook.proto:

service OrderBookStreaming {
  rpc StreamL4BookUpdates (L4BookUpdatesRequest) returns (stream L4BookUpdatesUpdate);
}

message L4BookUpdatesRequest {
  repeated string coins = 1;
}

enum L4OrderDiffType {
  L4_ORDER_DIFF_TYPE_UNSPECIFIED = 0;
  L4_ORDER_DIFF_TYPE_NEW = 1;
  L4_ORDER_DIFF_TYPE_UPDATE = 2;
  L4_ORDER_DIFF_TYPE_REMOVE = 3;
}

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

message L4OrderDiff {
  L4OrderDiffType diff_type = 1;
  string coin = 2;
  uint64 oid = 3;
  string user = 4;
  string side = 5;
  string px = 6;
  string sz = 7;
}

Ejemplos de actualizaciones​

Initial Snapshot (first message, truncated)

The first message has snapshot: true and contains every resting order as a NEW diff. Later messages can also carry snapshot: true as a replacement reset; handle each one the same way:

{
  "time": 1781109063794,
  "height": 586404872,
  "snapshot": true,
  "diffs": [
    { "diff_type": "L4_ORDER_DIFF_TYPE_NEW", "coin": "BTC", "oid": 54764492622,
      "user": "0x039442e06b482Bf01A1a65742cf061bD73A80f31", "side": "B", "px": "62963", "sz": "0.00009" },
    { "diff_type": "L4_ORDER_DIFF_TYPE_NEW", "coin": "BTC", "oid": 54764537698,
      "user": "0x3643290CD5DE72b37d2f10A351Ce57c30d103969", "side": "B", "px": "62963", "sz": "0.00024" },
    { "diff_type": "L4_ORDER_DIFF_TYPE_NEW", "coin": "BTC", "oid": 54764482173,
      "user": "0x4547B9E33F07965711f67d0bE2423939A4E33aF5", "side": "B", "px": "62955", "sz": "0.00015" }
  ]
}
Per-Block Update with Removals

sz is omitted on REMOVE diffs:

{
  "time": 1781109083796,
  "height": 586404997,
  "diffs": [
    { "diff_type": "L4_ORDER_DIFF_TYPE_REMOVE", "coin": "BTC", "oid": 54764554671,
      "user": "0xc64cc00B46101bd40aA1C3121195E85c0B0918d8", "side": "B", "px": "62389.0" },
    { "diff_type": "L4_ORDER_DIFF_TYPE_REMOVE", "coin": "BTC", "oid": 54764557274,
      "user": "0xc64cc00B46101bd40aA1C3121195E85c0B0918d8", "side": "B", "px": "62421.0" }
  ]
}
New Order and Size Update

A new order entering the book:

{
  "time": 1781109115476,
  "height": 586405189,
  "diffs": [
    { "diff_type": "L4_ORDER_DIFF_TYPE_NEW", "coin": "ETH", "oid": 54764586686,
      "user": "0x768484F7e2EBB675C57838366C02Ae99ba2A9B08", "side": "B", "px": "1649.1", "sz": "1.022" }
  ]
}

A size change on a resting order (sz is the new current size):

{ "diff_type": "L4_ORDER_DIFF_TYPE_UPDATE", "coin": "ETH", "oid": 54764551695,
  "user": "0x4547B9E33F07965711f67d0bE2423939A4E33aF5", "side": "B", "px": "1702.9", "sz": "0.0032" }

Uso de la API​

gRPC
// Single coin
const request = {
  coins: ['BTC']
};

// Multiple coins in one stream
const multiRequest = {
  coins: ['BTC', 'ETH']
};

// All coins
const allCoinsRequest = {
  coins: []
};

gRPC

StreamL4BookUpdates 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: L4 Book Updates vs L4 Book vs Book Updates Dataset​

CaracterísticaStreamL4BookUpdatesStreamL4BookNOVEDADES_LIBROS
GranularidadIndividual orders, typed diffsPedidos individualesDiferencias a nivel de pedido individual
Diff encodingTyped protobuf (NEW/UPDATE/REMOVE)JSON-encoded data stringJSON objects
Incluye el estado actualYes (reset snapshot as NEW diffs)Yes (initial snapshot)No (forward-only)
Requiere el arranque de RESTNoNoSí
Coins per streamMultiple (or all coins)One coin per streamFilterable
Detalles por pedidoUser, oid, side, px, szUsuario, oid, disparadores, marcas de tiempo, tifUsuario, oid, tamaño
Ideal paraPer-order book tracking without JSON parsingFull order detail (triggers, tif, cloid)Clientes que solo necesitan actualizaciones de libros

Notas importantes​


  • Reset on every snapshot: true mensaje: The first message is a full reset with all resting orders as NEW diffs, and replacement resets can arrive mid-stream (for example after an ALO priority fee queue insertion). Clear any local state and rebuild whenever instantánea is true, not only on subscribe and reconnect
  • REMOVE omits sz: Remove diffs identify the order by oide (with moneda, usuario, lado, px) but carry no size. Delete the order from your local map
  • Typed alternative to StreamL4Book: If you need trigger info, timestamps, tif, or cloide per order, use StreamL4Book; if you need lean typed per-order movement, use this stream
  • zstd compression recommended: Enable zstd compression on your gRPC channel to reduce bandwidth, especially when streaming multiple coins

  • StreamL4Book - Full order book at order granularity with snapshot + JSON-encoded diffs
  • StreamL2BookDiff - Incremental L2 price-level changes with sequence numbers
  • Órdenes - Eventos del ciclo de vida de los pedidos (pendientes, completados, cancelados, etc.)
Última actualización en