Ir al contenido principal

Conjunto de datos del libro de órdenes L4

Actualizado el
18 de julio de 2026

Resumen​

El StreamL4Book El flujo proporciona el libro de órdenes completo con un nivel de detalle por orden individual: cada orden pendiente incluye la dirección del usuario, el ID de la orden, el volumen, la información de activación y las marcas de tiempo. Al suscribirse, el flujo envía una instantánea completa de todas las órdenes pendientes y, a continuación, diferencias incrementales por bloque.

gRPC : OrderBookStreaming
gRPC : StreamL4Book
Disponibilidad de la API: Solo API gRPC Modelo de actualización: Instantánea completa al suscribirse y, a continuación, diferencias incrementales por bloque, con la posibilidad de realizar instantáneas de sustitución definitivas en cualquier momento.

Cómo funciona​

  1. Al suscribirse: El flujo envía un L4BookSnapshot que contiene todas las ofertas de compra y venta en espera, con todos los detalles de las órdenes
  2. A partir de ahí, por bloque: El arroyo lleva L4BookDiff mensajes codificados en JSON datos cadena que contiene estados_de_pedido (todos los objetos de estado de pedido que coincidan con el flujo «Orders») y diferencias_entre_libros (cambios incrementales mediante raw_book_diff (formato compatible con el flujo «Book Updates»)
  3. Aplica los cambios a tu copia local de la instantánea para mantener el estado actual
  4. Instantáneas de sustitución: El flujo puede enviar otro L4BookSnapshot tras la inicial, por ejemplo, cuando la inserción de una tarifa prioritaria ALO modifica el orden de la cola o cuando se reconstruye el estado del flujo. Considera cada instantánea como definitiva: descarta ambos lados del libro local y reconstruye a partir de ofertas y pregunta en el orden en que se han generado, y seguir aplicando las diferencias posteriores a partir de esa instantánea altura

Esta es una forma mucho más sencilla de crear y mantener una vista local del libro de órdenes de L4, ya que la instantánea inicial está integrada de serie: no se necesita ninguna configuración inicial REST ni la resolución de condiciones de carrera. Al volver a conectarse, se envía automáticamente una nueva instantánea.

Estructura de datos​

Instantánea (primer mensaje y sustituciones)​

La inicial L4BookSnapshot contiene el libro de órdenes completo. Las instantáneas posteriores utilizan la misma estructura y sustituyen por completo al libro de órdenes local:

{
  "snapshot": {
    "coin": "ETH",
    "time": 1764867600518,
    "height": 817863403,
    "bids": [
      {
        "user": "0x1c1c270b573d55b68b3d14722b5d5d401511bed0",
        "coin": "ETH",
        "side": "B",
        "limit_px": "3167.4",
        "sz": "1.5785",
        "oid": 258166296856,
        "timestamp": 1764867590000,
        "trigger_condition": "N/A",
        "is_trigger": false,
        "trigger_px": "0",
        "is_position_tpsl": false,
        "reduce_only": false,
        "order_type": "Limit",
        "tif": "Gtc"
      }
    ],
    "asks": [
      {
        "user": "0xe9acfdc9322f6f924f007016c082e6891a3c653c",
        "coin": "ETH",
        "side": "A",
        "limit_px": "3168.0",
        "sz": "2.0000",
        "oid": 258166160909,
        "timestamp": 1764867580000,
        "trigger_condition": "N/A",
        "is_trigger": false,
        "trigger_px": "0",
        "is_position_tpsl": false,
        "reduce_only": false,
        "order_type": "Limit",
        "tif": "Gtc"
      }
    ]
  }
}

Diferencia (mensajes posteriores)​

Tras la instantánea, cada bloque genera un L4BookDiff con cambios incrementales codificados en JSON:

{
  "diff": {
    "time": 1764867601000,
    "height": 817863404,
    "data": "{\"order_statuses\": [...], \"book_diffs\": [...]}"
  }
}

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»)

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.

Campos de respuesta​

L4BookUpdate​

Cada mensaje es un L4BookUpdate que contenga una instantánea o un archivo de diferencias:

CampoTipoDescripción
instantáneaL4BookSnapshotResumen completo de la cartera de pedidos (enviado al suscribirse, al volver a conectarse y como restablecimiento de sustitución a mitad de proceso)
diffL4BookDiffDiferencias incrementales (enviadas por bloque entre instantáneas)

L4BookSnapshot​

CampoTipoDescripción
monedacadenaSímbolo (p. ej., «BTC», «ETH»)
tiempouint64Marca de tiempo del bloque en milisegundos
alturauint64Altura del bloque
ofertasL4Order[]Todas las órdenes de compra en espera
preguntaL4Order[]Todas las órdenes pendientes

L4BookDiff​

CampoTipoDescripción
tiempouint64Marca de tiempo del bloque en milisegundos
alturauint64Altura del bloque
datoscadenaObjeto codificado en JSON que contiene «order_statuses» y «book_diffs», y que se ajusta al formato de datos de los nodos existentes

L4Order​

CampoTipoDescripción
usuariocadenaEthereum de Ethereum del titular del pedido
monedacadenaIdentificador del par de negociación (p. ej., «ETH», «BTC»)
ladocadena«A» (precio de venta/oferta) o «B» (precio de compra/demanda)
limit_pxcadenaPrecio límite como cadena decimal
szcadenaTamaño del pedido como cadena decimal
oideuint64N.º de pedido único
marca de tiempouint64Momento en que se registró la orden (en milisegundos)
condición_de_activacióncadenaEstado de la condición de activación: «N/A», «Activada», etc.
is_triggerboolSi la orden es una orden de activación o de stop
trigger_pxcadenaPrecio de activación como cadena decimal
is_position_tpslboolTanto si la orden es una orden de toma de beneficios o de corte de pérdidas
reduce_onlyboolSi el orden es «solo reducir»
tipo_de_pedidocadenaTipo de orden: «Límite», «Mercado», etc.
tifcadena (opcional)Vigencia: «Gtc» (Válida hasta su cancelación), «Ioc» (Inmediata o cancelada), «Alo» (Solo añadir liquidez)
cloidecadena (opcional)ID del pedido del cliente (identificador personalizado establecido por el usuario)

Definición de «Proto»​

StreamL4Book se define en orderbook.proto:

service OrderBookStreaming {
  rpc StreamL4Book (L4BookRequest) returns (stream L4BookUpdate);
}

message L4BookRequest {
  string coin = 1;
}

message L4BookUpdate {
  oneof update {
    L4BookSnapshot snapshot = 1;
    L4BookDiff diff = 2;
  }
}

message L4BookSnapshot {
  string coin = 1;
  uint64 time = 2;
  uint64 height = 3;
  repeated L4Order bids = 4;
  repeated L4Order asks = 5;
}

message L4BookDiff {
  uint64 time = 1;
  uint64 height = 2;
  string data = 3;
}

message L4Order {
  string user = 1;
  string coin = 2;
  string side = 3;
  string limit_px = 4;
  string sz = 5;
  uint64 oid = 6;
  uint64 timestamp = 7;
  string trigger_condition = 8;
  bool is_trigger = 9;
  string trigger_px = 10;
  bool is_position_tpsl = 11;
  bool reduce_only = 12;
  string order_type = 13;
  optional string tif = 14;
  optional string cloid = 15;
}

Ejemplos de actualizaciones​

Instantánea L4 (estado completo inicial)
{
  "snapshot": {
    "coin": "ETH",
    "time": 1764867600518,
    "height": 817863403,
    "bids": [
      {
        "user": "0x1c1c270b573d55b68b3d14722b5d5d401511bed0",
        "coin": "ETH",
        "side": "B",
        "limit_px": "3167.4",
        "sz": "1.5785",
        "oid": 258166296856,
        "timestamp": 1764867590000,
        "trigger_condition": "N/A",
        "is_trigger": false,
        "trigger_px": "0",
        "is_position_tpsl": false,
        "reduce_only": false,
        "order_type": "Limit",
        "tif": "Gtc"
      },
      {
        "user": "0x999a4b5f268a8fbf33736feff360d462ad248dbf",
        "coin": "ETH",
        "side": "B",
        "limit_px": "3167.0",
        "sz": "5.0000",
        "oid": 258166123456,
        "timestamp": 1764867585000,
        "trigger_condition": "N/A",
        "is_trigger": false,
        "trigger_px": "0",
        "is_position_tpsl": false,
        "reduce_only": false,
        "order_type": "Limit",
        "tif": "Gtc",
        "cloid": "0x20251204000000000000000000381433"
      }
    ],
    "asks": [
      {
        "user": "0xe9acfdc9322f6f924f007016c082e6891a3c653c",
        "coin": "ETH",
        "side": "A",
        "limit_px": "3168.0",
        "sz": "2.0000",
        "oid": 258166160909,
        "timestamp": 1764867580000,
        "trigger_condition": "N/A",
        "is_trigger": false,
        "trigger_px": "0",
        "is_position_tpsl": false,
        "reduce_only": false,
        "order_type": "Limit",
        "tif": "Alo"
      }
    ]
  }
}
L4 Diff (actualización incremental por bloques)
{
  "diff": {
    "time": 1764867601000,
    "height": 817863404,
    "data": "{\"order_statuses\":[...],\"book_diffs\":[...]}"
  }
}

El datos El campo es una cadena codificada en JSON. Una vez analizada, contiene:

estados_de_pedido — Eventos completos sobre el estado de los pedidos, uno por cada pedido modificado en este bloque. Cada elemento se corresponde con el Flujo de pedidos forma del evento:

{
  "order": {
    "coin": "ETH",
    "side": "B",
    "limitPx": "3167.4",
    "sz": "1.5785",
    "oid": 258166296856,
    "timestamp": 1764867590000,
    "triggerCondition": "N/A",
    "isTrigger": false,
    "triggerPx": "0.0",
    "isPositionTpsl": false,
    "reduceOnly": false,
    "orderType": "Limit",
    "tif": "Gtc",
    "cloid": "0x...",
    "user": null
  },
  "status": "filled",
  "time": "2025-12-04T17:00:00.518000000",
  "user": "0x1c1c270b573d55b68b3d14722b5d5d401511bed0"
}

diferencias_entre_libros — Cambios incrementales en la cartera de pedidos. Cada partida utiliza el mismo raw_book_diff formato como el Novedades sobre el libro transmisión:

// New order or size update
{
  "coin": "ETH",
  "oid": 258166296857,
  "px": "3168.0",
  "raw_book_diff": { "new": { "sz": "2.0000" } },
  "side": "A",
  "user": "0xe9acfdc9322f6f924f007016c082e6891a3c653c"
}

// Order removed (cancelled or filled)
{
  "coin": "ETH",
  "oid": 258166296856,
  "px": "3167.4",
  "raw_book_diff": "remove",
  "side": "B",
  "user": "0x1c1c270b573d55b68b3d14722b5d5d401511bed0"
}
Orden de activación/stop-loss
{
  "user": "0x7a475736bf02d67bf51b00414ab766ef4da9214d",
  "coin": "BTC",
  "side": "A",
  "limit_px": "90000.0",
  "sz": "0.5000",
  "oid": 258166400000,
  "timestamp": 1764867595000,
  "trigger_condition": "Triggered",
  "is_trigger": true,
  "trigger_px": "91000.0",
  "is_position_tpsl": true,
  "reduce_only": true,
  "order_type": "Limit",
  "tif": "Gtc"
}

Uso de la API​

gRPC
// Perp order book
const request = {
  coin: 'ETH'
};

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

gRPC

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

Comparación: libro L4 frente a libro L2 frente al conjunto de datos de actualizaciones de libros​

CaracterísticaStreamL4BookStreamL2BookNOVEDADES_LIBROS
GranularidadPedidos individualesAgrupados por nivel de preciosDiferencias a nivel de pedido individual
Incluye el estado actualSí — instantánea inicialSí, todos los mensajesNo — solo hacia adelante
Requiere el arranque de RESTNoNoSí
Gestión del estado del clienteAplicar diferencias a la instantáneaNingunoCrear desde cero
Detalles por pedidoUsuario, oid, disparadores, marcas de tiempo, tifSolo el tamaño total y el número totalUsuario, oid, tamaño
Ancho de bandaMás arriba (detalles completos del pedido)Medio (limitado por n_levels)Bajo (solo diferencias)
Ideal paraHFT, equipos cuantitativos, MEVLa mayoría de los clientesClientes que solo necesitan actualizaciones de libros

Notas importantes​


  • Considera cada instantánea como definitiva: las instantáneas se reciben al suscribirse y al volver a conectarse, y también puede recibirse una instantánea de sustitución tras las actualizaciones incrementales normales (por ejemplo, cuando la inserción de una tarifa prioritaria ALO modifica el orden de la cola). En mercados activos, las instantáneas de sustitución pueden recibirse varias veces por minuto. Cada vez que se reciba una instantánea, descarta el libro de órdenes local y reconstrúyelo a partir de la instantánea.
  • La prioridad de la cola se establece mediante instantáneas, no insertBefore: El crudo Novedades sobre el libro El flujo expone un insertBefore campo en las inserciones prioritarias; las diferencias L4 no lo incluyen. streams , los streams L4 transmiten los cambios en el orden de la cola mediante instantáneas de sustitución cuyas ofertas y pregunta se emiten siguiendo el orden canónico de la cola.
  • Permitir mensajes de gran tamaño: las instantáneas de sustitución contienen toda la profundidad L4 y pueden ser mucho más grandes que una diferencia incremental, especialmente en el caso de BTC. Asigna al menos 100 MB para gRPC entrantes y aplica cada instantánea de forma atómica antes de procesar las actualizaciones posteriores.
  • PÉRDIDA DE DATOS reconexión: El flujo puede emitir gRPC PÉRDIDA DE DATOS errores de estado durante problemas transitorios. Implementar la lógica de reconexión automática en PÉRDIDA DE DATOS — En cada nueva conexión se envía una instantánea actualizada, por lo que no es necesario recuperar el estado manualmente.
  • Aplicar diferencias al estado local: Entre una instantánea y otra, aplica cada una L4BookDiff para mantener el libro actual. Cada diferencias_entre_libros usos del artículo raw_book_diff: {"new": {"sz": "..."}} para añadir o modificar un pedido, o raw_book_diff: «eliminar» para eliminar uno, con el mismo formato que el Novedades sobre el libro transmisión.
  • Hay una versión mecanografiada disponible: Si solo necesitas realizar operaciones de añadir, actualizar o eliminar por pedido sin analizar el formato JSON, datos cadena, StreamL4BookUpdates ofrece los mismos cambios a nivel de orden que las diferencias de Protobuf escritas.
  • Se recomienda encarecidamente la compresión zstd: los mensajes L4 pueden ser de gran tamaño debido a los detalles completos del pedido. Activa la compresión zstd en tu gRPC para reducir significativamente el ancho de banda.

  • StreamL2Book - Niveles de precios agregados: más sencillos, menor ancho de banda y sin gestión del estado por parte del cliente
  • StreamL4BookUpdates - Diferencias de adición, actualización y eliminación por pedido, sin necesidad de analizar JSON
  • Actualizaciones del libro - Comparaciones incrementales solo hacia adelante a través de StreamData (método tradicional)
  • Ó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