L2 Book Diff Dataset

概述

该 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 Service: 订单流
gRPC Method: StreamL2BookDiff
Update Model: Initial per-coin snapshot (optional), then incremental diffs per block with sequence numbers

工作原理

On subscribe: 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)
Per block thereafter: 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.

Data Structure

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

Diff (subsequent messages)

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

Request Parameters

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

Coin Naming

该 coins parameter follows Hyperliquid's naming convention, which unambiguously distinguishes perpetuals from spot:

Perpetuals: Human-readable names, such as "BTC", "ETH", "HYPE", "SOL"
Spot tokens: @{index} format, such as "@1", "@107", "@142", "@166"
Outcome markets (HIP-4): #N format. Each outcome has two #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 to map coin indices to market names and sides.
Exception: "PURR/USDC" is the only spot coin with a readable name

There is no overlap between formats. "BTC" always refers to the BTC perpetual; spot BTC is "@142". To discover @index mappings for spot tokens, query the 元数据或 spotMeta info endpoints.

Response Fields

L2BookDiffUpdate

字段	类型	描述
时间	uint64	Block timestamp in milliseconds
高度	uint64	Block height
snapshot	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

字段	类型	描述
硬币	字符串	Symbol (e.g., "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
bids	L2Level[]	Changed bid levels. A level with sz "0" was removed
asks	L2Level[]	Changed ask levels. A level with sz "0" was removed
snapshot	bool	True when this diff carries the initial levels for the coin as a snapshot

L2Level

字段	类型	描述
px	字符串	Price as a decimal string
sz	字符串	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 is defined 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;
}

Example Updates

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

API Usage

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 Only

StreamL2BookDiff is only available via the gRPC Streaming API (订单流 service). It is not available through JSON-RPC or WebSocket.

Comparison with StreamL2Book

Feature	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	无
Gap detection	seq / prev_seq per coin	Not needed
Coins per stream	Multiple (or all coins)	One coin per stream
Bandwidth	Low (diffs only)	Medium (capped by n_levels)
Price bucketing	Supported (n_sig_figs, mantissa)	Supported (n_sig_figs, mantissa)
最适合	Efficient local book maintenance at scale	Simplest depth consumption

Important Notes

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 硬币 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

概述​

工作原理​

Data Structure​

Initial snapshot (first message per coin)​

Diff (subsequent messages)​

Request Parameters​

Coin Naming​

Response Fields​

L2BookDiffUpdate​

L2CoinDiff​

L2Level​

Proto Definition​

Example Updates​

API Usage​

Comparison with StreamL2Book​

Important Notes​

Related Streams​

概述