Skip to main content
The l2Book query returns a full L2 order book snapshot containing all price levels for a contract at a point in time. This is useful for initializing local order book state before connecting to the WebSocket feed. For ongoing updates, subscribe to the WebSocket l2Book channel: it delivers the current snapshot on subscribe and every change after it, which makes this REST call unnecessary for a streaming client. Use this endpoint for a one-off read.
This endpoint returns HTTP 503 with code NOT_READY (message "no book data yet") when no book data is available for the contract. This is not an empty book. Retry with exponential backoff; do not poll in a tight loop.
The response carries every level the snapshot holds, up to a fixed depth limit. There is no parameter to request a smaller number of levels.

​
Request

​
string
required
type (required) — Must be "l2Book".
​
string
required
asset (required) — The contract ID to fetch the order book for, expressed as a decimal string (e.g. "1"). Use the contractId from configs.
​
integer | string
group — Price aggregation bucket width, as a raw integer in the same units as tickSize and prices. The value must be one of the entries in that contract’s digitMerge list from configs. Omit it to receive the unaggregated book.A digitMerge entry equal to tickSize is accepted and returns the unaggregated book unchanged, so a precision selector can offer the whole digitMerge list without special-casing any entry.Bids round down to the bucket boundary and asks round up: the bid bucket [B, B+group) and the ask bucket (B-group, B] are both reported at price B. Within a bucket, sz and n are summed.A group value that is not configured for the contract returns HTTP 400 with code BAD_REQUEST and message "group not configured for this asset". The result is deterministic; retrying does not change it.

​
Response

​
string
Contract ID.
​
integer
Timestamp of the snapshot in Unix milliseconds. It is the block time of the snapshot, identical across servers and non-decreasing per contract. Use it to determine which point in time a snapshot represents.
​
string
Current mark price (raw integer string). Returns "0" if the mark price has not yet been published for this contract.
​
string
Current oracle (index) price (raw integer string). Returns "0" if the oracle price has not yet been published for this contract.
​
integer
The aggregation bucket width of this snapshot, echoing the requested group value. 0 is returned when group is omitted and means the unaggregated book.
​
boolean
A JSON boolean, not a string. true means the book at this aggregation level does not have enough depth to fill the depth limit, so fewer levels than the limit are returned. false means it does.
​
array[]
Two-element array: levels[0] contains bids sorted from highest to lowest price; levels[1] contains asks sorted from lowest to highest price.

​
Applying snapshots

The response carries no version number. Every l2Book snapshot is complete, so overwrite local book state with each snapshot in the order it arrives; no version comparison or gap detection is needed, and applying the same snapshot twice is idempotent. To determine which point in time a snapshot represents, use time.