Skip to main content

L2 Order Book Dataset

Updated on
Feb 25, 2026

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 (e.g., "BTC", "ETH")
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.

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
// StreamL2Book — OrderBookStreaming service
const request = {
  coin: 'BTC',
  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
Includes current book state
StreamL2Book
Yes — every message is a full snapshot
BOOK_UPDATES (StreamData)
No — forward-only diffs from subscribe time
Feature
Needs REST bootstrap
StreamL2Book
No
BOOK_UPDATES (StreamData)
Yes (Info endpoint l2Book)
Feature
Client-side state management
StreamL2Book
None
BOOK_UPDATES (StreamData)
Build and maintain local book from diffs
Feature
Data granularity
StreamL2Book
Aggregated by price level
BOOK_UPDATES (StreamData)
Individual order-level diffs
Feature
Reconnect handling
StreamL2Book
Automatic — full snapshot resumes
BOOK_UPDATES (StreamData)
Must re-bootstrap from REST
Feature
Price bucketing
StreamL2Book
Supported (n_sig_figs, mantissa)
BOOK_UPDATES (StreamData)
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

  • 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
Last updated on
Share this doc