概要

その 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 Service: OrderBookStreaming
gRPC Method: StreamL2Book
Update Model: Full snapshot every block — no client-side state management required

仕組み

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.

Data Structure

それぞれ L2BookUpdate 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 }
  ]
}

Request Parameters

フィールド	種類	Required	説明
コイン	文字列	はい	Symbol to subscribe to — perps use names (e.g., "BTC", "ETH"), spot uses @index format (e.g., "@142")
n_levels	uint32	はい	Maximum number of price levels to return 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.

Coin Naming

その コイン parameter follows Hyperliquid's naming convention, which unambiguously distinguishes perpetuals from spot:

• Perpetuals: Human-readable names — "BTC", "ETH", "HYPE", "SOL"
• Spot tokens: @{index} format — "@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 meta または spotMeta info endpoints.

Price Bucketing

The optional n_sig_figs そして 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

Response Fields

L2BookUpdate

フィールド	種類	説明
コイン	文字列	Symbol (e.g., "BTC", "ETH")
時間	uint64	Block timestamp in milliseconds
ブロック番号	uint64	Block number
bids	L2Level[]	Aggregated bid levels, ordered best (highest) price first
asks	L2Level[]	Aggregated ask levels, ordered best (lowest) price first

L2Level

フィールド	種類	説明
px	文字列	Price as a decimal string
sz	文字列	Total size across all orders at this price level, as a decimal string
n	uint32	Number of individual orders at this price level

Proto Definition

StreamL2Book is defined in 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;
}

Example Updates

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 そして 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 }
  ]
}

API Usage

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 Only

StreamL2Book is only available via the gRPC Streaming API (OrderBookStreaming service). It is not available through JSON-RPC or WebSocket.

Comparison with Book Updates Dataset

Feature	StreamL2Book	BOOK_UPDATES (StreamData)
Includes current book state	Yes — every message is a full snapshot	No — forward-only diffs from subscribe time
Needs REST bootstrap	いいえ	Yes (Info endpoint l2Book)
Client-side state management	なし	Build and maintain local book from diffs
Data granularity	Aggregated by price level	Individual order-level diffs
Reconnect handling	Automatic — full snapshot resumes	Must re-bootstrap from REST
Price bucketing	Supported (n_sig_figs, mantissa)	利用不可

Important Notes

• Full snapshot every block: Each L2BookUpdate 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

Related Streams

• 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
• Orders - Order lifecycle events (open, filled, canceled, etc.)
• Trades - Executed trade data with maker/taker information