L2 Order Book Dataset

Présentation générale

Le 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
Modèle de mise à jour : Full snapshot every block — no client-side state management required

Comment ça marche ?

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.

Structure de données

Each Mise à jour de L2Book 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 }
  ]
}

Paramètres de requête

Champ	Type	Obligatoire	Description
pièce de monnaie	chaîne de caractères	Oui	Symbole à souscrire — pour les contrats à terme, on utilise des noms (par exemple, « BTC », « ETH ») ; pour le marché au comptant, on utilise le format @index (par exemple, « @142 »)
n_niveaux	uint32	Oui	Maximum number of price levels to return per side (default 20, max 100)
n_sig_figs	uint32	Non	Significant figures for price bucketing (2–5). Omit for exact price-level aggregation.
mantissa	uint64	Non	Mantissa for price bucketing (1, 2, or 5). Used with n_sig_figs to control bucket width.

Dénomination des pièces

Le pièce de monnaie Ce paramètre respecte la convention de nommage Hyperliquid, qui distingue sans ambiguïté les contrats à durée indéterminée des contrats au comptant :

Titre perpétuel: Noms lisibles par l'utilisateur — « BTC », « ETH », « HYPE », « SOL »
Jetons au comptant: @{index} format — « @1 », « @107 », « @142 », « @166 »
Marchés des résultats (HIP-4): #N format. Chaque résultat comporte deux #N pièces — une par côté (Oui et Non). Les marchés de questions à prix multiples se composent de plusieurs résultats regroupés (tranches de prix plus une option de repli), chacun disposant de sa propre paire de pièces Oui/Non. Utilisez le outcomeMeta endpoint mettre en correspondance les indices des cryptomonnaies avec les noms et les côtés du marché.
Exception: « PURR/USDC » C'est la seule pièce de monnaie dont le nom est lisible.

Il n'y a pas de chevauchement entre les formats. « BTC » fait toujours référence au contrat à terme perpétuel sur BTC ; le BTC au comptant est « @142 ». Pour découvrir @index mappages pour les jetons ponctuels, interroger le méta ou spotMeta points de terminaison d'information.

Price Bucketing

The optional n_sig_figs et 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

Champs de réponse

Mise à jour de L2Book

Champ	Type	Description
pièce de monnaie	chaîne de caractères	Symbole (par exemple, « BTC », « ETH »)
temps	uint64	Horodatage du bloc en millisecondes
block_number	uint64	Numéro de bloc
offres	L2Level[]	Aggregated bid levels, ordered best (highest) price first
demande	L2Level[]	Aggregated ask levels, ordered best (lowest) price first

L2Level

Champ	Type	Description
px	chaîne de caractères	Price as a decimal string
sz	chaîne de caractères	Total size across all orders at this price level, as a decimal string
n	uint32	Number of individual orders at this price level

Définition de « proto »

StreamL2Book est défini dans 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;
}

Exemples de mises à jour

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 et 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 }
  ]
}

Utilisation de l'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 n'est disponible que via l'API gRPC (OrderBookStreaming service). Il n'est pas disponible via JSON-RPC ou WebSocket.

Comparison with Book Updates Dataset

Fonctionnalité	StreamL2Book	BOOK_UPDATES (StreamData)
Includes current book state	Yes — every message is a full snapshot	No — forward-only diffs from subscribe time
Nécessite le démarrage REST	Non	Yes (Info endpoint l2Book)
Client-side state management	Aucun	Build and maintain local book from diffs
Data granularity	Agrégés par niveau de prix	Différences au niveau des commandes individuelles
Reconnect handling	Automatic — full snapshot resumes	Must re-bootstrap from REST
Price bucketing	Supported (n_sig_figs, mantissa)	Not available

Remarques importantes

Full snapshot every block: Each Mise à jour de L2Book 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
Commandes - Événements liés au cycle de vie des commandes (en cours, exécutées, annulées, etc.)
Transactions - Données relatives aux transactions exécutées, avec informations sur les « makers » et les « takers »

Présentation générale​

Comment ça marche ?​

Structure de données​

Paramètres de requête​

Dénomination des pièces​

Price Bucketing​

Champs de réponse​

Mise à jour de L2Book​

L2Level​

Définition de « proto »​

Exemples de mises à jour​

Utilisation de l'API​

Comparison with Book Updates Dataset​

Remarques importantes​

Streams associés​