Get historical order book snapshots for a futures trading pair; each snapshot lists the order quantity at every bid and ask price level. Useful for drawing an order book heatmap and watching where order walls are and how they change.
| Time | Status | User Agent | |
|---|---|---|---|
Retrieving recent requests… | |||
Available on these API plans: Standard Professional Enterprise
Response Data
data is an array; each element is an order book snapshot at one point in time. A snapshot is a positional array without field names, read by position: [0] is the snapshot time (Unix seconds), [1] is the list of bid price levels, and [2] is the list of ask price levels; each price level is in turn [price, quantity]. In the table below, data[].0 means the first position of the snapshot, data[].1[].0 means the price of a bid price level, and so on.
Time Units: Milliseconds in the Request, Seconds in the ResponsePass
start_timeandend_timeas timestamps in milliseconds; the returned snapshot timedata[].0is a Unix timestamp in seconds, e.g.,1792458000. In languages such as JavaScript that handle time in milliseconds, multiply it by 1000 before converting it to a date.
Supported Exchanges and PairsThis endpoint supports only perpetual contracts quoted in USDT or USD; coin-margined contracts are not supported. Binance, Hyperliquid and tradeXYZ support all available coins; Gate, Bitget and OKX support only BTC and ETH. Even for pairs in the list, data is not guaranteed at every historical point in time.
200 · application/json · See the response example in the right panel.
| Field | Type | Always Returned | Description |
|---|---|---|---|
code | string | Yes | Business status code; "0" means success |
msg | string | No | Result message |
data | array of array | Yes | Array of order book snapshots; each snapshot is a positional array [time, bid levels, ask levels] |
data[].0 | integer | Yes | Position 0: snapshot time, Unix timestamp in seconds (UTC), not milliseconds |
data[].1 | array of array | Yes | Position 1: list of bid price levels (bids); each price level is [price, quantity] |
data[].1[].0 | number | Yes | Bid price level, position 0: price, in the quote currency (e.g., USDT) |
data[].1[].1 | number | Yes | Bid price level, position 1: order quantity at that price, i.e., the raw quantity provided by the exchange, not a dollar amount |
data[].2 | array of array | Yes | Position 2: list of ask price levels (asks); each price level is [price, quantity] |
data[].2[].0 | number | Yes | Ask price level, position 0: price, in the quote currency (e.g., USDT) |
data[].2[].1 | number | Yes | Ask price level, position 1: order quantity at that price, i.e., the raw quantity provided by the exchange, not a dollar amount |
The data volume is large: for Binance BTCUSDT, each snapshot has about 680–1160 price levels on each of the bid and ask sides, and a response with 3 snapshots is about 79 KB. Control limit and the time range as needed.
Bid and ask price levels are not guaranteed to be returned in any particular order. Sort them by price yourself before use: the best bid is the highest price among the bids, and the best ask is the lowest price among the asks.
API Plans
Only the API plans marked Yes in the table below can call this endpoint. For the price of each plan, see API Plans.
| API Plan | Access |
|---|---|
| Hobbyist | ❌ No |
| Startup | ❌ No |
| Standard | ✅ Yes |
| Professional | ✅ Yes |
| Enterprise | ✅ Yes |
Use This Endpoint with AI
Pick a task and click Open in ChatGPT or Open in Claude: the AI reads this page first and then gives you the result. You can also click Copy and paste the full prompt into the AI tool you use.
This endpoint provides data through the REST API. Use the prompts above to have AI write the request code. For the tools available through MCP, see CoinGlass MCP.
Use Cases
| Scenario | Description |
|---|---|
| Draw an Order Book Heatmap | Plot order quantity as color intensity by time and price to see at a glance where order walls are and how long they last. |
| Identify Order Walls | Find single prices with an especially large number of orders as a reference for potential support or resistance. |
| Watch Orders Being Pulled and Replaced | Compare adjacent snapshots to spot large orders that suddenly appear or are pulled, and judge whether there are spoof orders. |
| Build Your Own Depth Metrics | Calculate the bid and ask totals within any price range yourself from the price-level details, without being limited to fixed range values. |
Related Endpoints
| Endpoint | How It Differs |
|---|---|
| Pair Order Book Depth History (±Range) | Bid and ask orders summed by price range, with a small data volume |
| Large Order Book | Large limit orders currently in the order book |
| Spot Order Book History (Heatmap) | Spot version of the same data |
| Pair Liquidation Heatmap (Model 1) | Estimated distribution of liquidation prices, often compared with the order book heatmap |
| Supported Exchanges and Pairs | Look up valid values for exchange and symbol |
FAQ
Why is the returned time 10 digits long?
The snapshot time data[].0 is a Unix timestamp in seconds, while the request parameters start_time and end_time use milliseconds. When handling time in milliseconds, multiply it by 1000 first.
Which exchanges and pairs can I query?
Only perpetual contracts quoted in USDT or USD are supported: Binance, Hyperliquid and tradeXYZ support all available coins, Gate, Bitget and OKX support only BTC and ETH, and coin-margined contracts are not supported. When you query an unsupported exchange or pair, the endpoint returns the failure message Exchange not supported.
What is the most I can query at once?
Up to 100 snapshots per request; larger values are treated as 100. Longest history you can query: 3 days for 1m, 15 days for 5m, and 150 days for the other intervals. Each snapshot has hundreds to over a thousand price levels on each of the bid and ask sides, so the data volume is large; narrow the range as needed.
What units are the price and quantity in?
The price is in the quote currency (e.g., USDT); the quantity is the order quantity at that price, i.e., the raw quantity provided by the exchange, not a dollar amount. If you need an amount, you can estimate it by multiplying the price by the quantity.
Learn More: Order Book Heatmap
How Do I Read an Order Book Heatmap?
The horizontal axis is time and the vertical axis is price; a brighter color means more orders at that price. A bright band that persists is usually a large order wall, and price may meet support or resistance as it approaches.
Do Order Walls Always Work?
Not necessarily. Orders can be canceled at any time, and some large orders are placed only to influence market sentiment and are pulled as price approaches. Watching whether an order wall persists and whether it gets filled as price approaches is more reliable than looking at a single snapshot.
How Is This Heatmap Different from a Liquidation Heatmap?
An order book heatmap shows the limit orders actually resting on the order book; a liquidation heatmap (see Pair Liquidation Heatmap (Model 1)) shows the distribution of liquidation prices estimated from open interest. Overlaying the two shows which prices have both orders and potential liquidations.