Übersicht

Die 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
Modell aktualisieren: Initial per-coin snapshot (optional), then incremental diffs per block with sequence numbers

So funktioniert es

1. Beim Abonnieren: 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)
2. Danach pro Block: Each L2BookDiffUpdate contains only the price levels that changed. A level with sz: "0" means the level was removed
3. 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.

Datenstruktur

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

Unterschied (folgende Nachrichten)

{
  "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.

Anfrageparameter

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

Benennung von Münzen

Die coins Der Parameter folgt der Namenskonvention Hyperliquid, die Perpetuals eindeutig vom Spot unterscheidet:

• Unbefristete Verträge: Human-readable names, such as „BTC“, „ETH“, „HYPE“, „SOL“
• Spot-Token: @{index} format, such as "@1", „@107“, "@142", "@166"
• Ergebnismärkte (HIP-4): #N Format. Jedes Ergebnis hat zwei #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 Zuordnung von Münzindizes zu Marktbezeichnungen und Seiten.
• Ausnahme: „PURR/USDC“ ist die einzige Spot-Münze, auf der ein Name zu lesen ist

Es gibt keine Überschneidungen zwischen den Formaten. „BTC“ bezieht sich immer auf den BTC-Perpetual-Kontrakt; der Spot-BTC ist "@142". Um zu entdecken @index Zuordnungen für Spot-Token, Abfrage der Meta oder spotMeta Info-Endpunkte.

Antwortfelder

L2BookDiffUpdate

Feld	Typ	Beschreibung
Zeit	uint64	Block-Zeitstempel in Millisekunden
Höhe	uint64	Blockhöhe
Momentaufnahme	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

Feld	Typ	Beschreibung
Münze	Zeichenkette	Symbol (z. B. „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
Gebote	L2Level[]	Changed bid levels. A level with sz "0" was removed
fragt	L2Level[]	Changed ask levels. A level with sz "0" was removed
Momentaufnahme	bool	True when this diff carries the initial levels for the coin as a snapshot

L2Level

Feld	Typ	Beschreibung
px	Zeichenkette	Price as a decimal string
sz	Zeichenkette	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)

Proto-Definition

StreamL2BookDiff ist definiert in 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;
}

Beispiele für Aktualisierungen

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 wahr, the first message is a plain diff (no Momentaufnahme flags) with seq starting at 1.

API-Nutzung

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 ist nur über die gRPC -API verfügbar (OrderBookStreaming Dienst). Er ist nicht über JSON-RPC oder WebSocket verfügbar.

Comparison with StreamL2Book

Funktion	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	Keine
Gap detection	seq / prev_seq per coin	Not needed
Coins per stream	Multiple (or all coins)	One coin per stream
Bandbreite	Niedrig (nur Differenzwerte)	Mittel (begrenzt durch n_levels)
Price bucketing	Supported (n_sig_figs, mantissa)	Supported (n_sig_figs, mantissa)
Am besten geeignet für	Efficient local book maintenance at scale	Simplest depth consumption

Wichtige Hinweise

• 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_levels 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 Münze field on each diff
• zstd compression recommended: Enable zstd compression on your gRPC channel to reduce bandwidth, especially when streaming multiple coins

Verwandte Streams

• 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