Overview

The 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

How It Works

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

Each 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

Field	Type	Required	Description
coin	string	Yes	Symbol to subscribe to — perps use names (e.g., "BTC", "ETH"), spot uses @index format (e.g., "@142")
n_levels	uint32	Yes	Maximum number of price levels to return per side (default 20, max 100)
n_sig_figs	uint32	No	Significant figures for price bucketing (2–5). Omit for exact price-level aggregation.
mantissa	uint64	No	Mantissa for price bucketing (1, 2, or 5). Used with n_sig_figs to control bucket width.

Coin Naming

The coin 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 or spotMeta info endpoints.

Price Bucketing

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

Field	Type	Description
coin	string	Symbol (e.g., "BTC", "ETH")
time	uint64	Block timestamp in milliseconds
block_number	uint64	Block number
bids	L2Level[]	Aggregated bid levels, ordered best (highest) price first
asks	L2Level[]	Aggregated ask levels, ordered best (lowest) price first

L2Level

Field	Type	Description
px	string	Price as a decimal string
sz	string	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 and 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 Streaming

// 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	No	Yes (Info endpoint l2Book)
Client-side state management	None	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)	Not available

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
• Book Updates - Forward-only incremental diffs via StreamData
• Orders - Order lifecycle events (open, filled, canceled, etc.)
• Trades - Executed trade data with maker/taker information