Orderbook depth data bucketed by price level for rendering heatmaps. Supports both single-exchange snapshots and multi-exchange aggregated views, at HD or 4K resolution.
Block size, depth, and resolution
The blockSize parameter controls price bucket granularity, and maxDepth controls how many price levels are returned. Together they define the price range covered by the heatmap.
For example, with blockSize=5 and maxDepth=500, the response contains 500 price levels bucketed at 5 USD intervals, covering a 2,500 USD range above and below the current price.
Use the GET /v1/block-sizes endpoint to get the recommended block size for a given symbol:
# Get the 4K block size for BTCUSDT on Binance Futures curl "https://api.kiyotaka.ai/v1/block-sizes ?exchange=BINANCE_FUTURES &rawSymbol=BTCUSDT &type=BLOCK_BOOK_SNAPSHOT_AGG" \\ -H "X-Kiyotaka-Key: YOUR_API_KEY"
The returned value is the 4K (finest) block size. Multiply by 5 for the HD block size.
| Resolution | Block Size | Description |
|---|---|---|
| 4K | Value from /v1/block-sizes | Finest granularity. More detail at each price step. |
| HD | 5x the /v1/block-sizes value | Standard resolution. Broader buckets that usually let you cover the same price range with a lower maxDepth. |
For example, if /v1/block-sizes returns 5 for BTCUSDT, use blockSize=5 for 4K and blockSize=25 for HD.
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
blockSize | double | Yes | Price bucket size in USD. Determines the granularity of each price level. |
maxDepth | int | No | Number of price levels to return. Each level spans one blockSize. Default and included depth: 3500. |
flatten | bool | No | When true, returns flat_points (a single array of floats) instead of points. See Flattened response below. |
transform.groupBy.type | GroupBy | No | Set to GROUP_BY_TYPE_SUM for multi-exchange aggregation. |
transform.normalize.quote | Normalize | No | Set to USD for USD-denominated depth. Default is coin values. |
Weight impact
Requests above maxDepth=3500 increase the depth multiplier by 20% for each additional 3500-level band. For example, 3501-7000 levels cost 1.2x the base orderbook weight, and 7001-10500 levels cost 1.4x. Lower values reduce payload size, but the multiplier does not go below 1.0x.
Response fields
| Field | Type | Description |
|---|---|---|
bids | double[] | Alternating [price, volume] bid pairs, ordered from closest to furthest from mid price |
asks | double[] | Alternating [price, volume] ask pairs, ordered from closest to furthest from mid price |
timestamp | Timestamp | Snapshot time |
Examples
Regular HD heatmap (single exchange)
Fetches 19 minutes of orderbook heatmap data for BTCUSDT on Binance Futures at HD resolution (blockSize=25, which is 5x the base block size of 5). Returns up to 1,000 price levels at 25 USD intervals, sorted newest first.
curl "https://api.kiyotaka.ai/v1/points ?type=BLOCK_BOOK_SNAPSHOT_AGG &exchange=BINANCE_FUTURES &rawSymbol=BTCUSDT &interval=MINUTE &period=1140 &blockSize=25 &maxDepth=1000 &sortDirection=SORT_DIRECTION_DESC" \\ -H "X-Kiyotaka-Key: YOUR_API_KEY"
4K heatmap (fine resolution)
Same query but at 4K resolution (blockSize=5, the raw value from /v1/block-sizes). Returns 1,000 price levels at 5 USD intervals -- 5x the detail of HD for the same depth range.
curl "https://api.kiyotaka.ai/v1/points ?type=BLOCK_BOOK_SNAPSHOT_AGG &exchange=BINANCE_FUTURES &rawSymbol=BTCUSDT &interval=MINUTE &period=1140 &blockSize=5 &maxDepth=1000 &sortDirection=SORT_DIRECTION_DESC" \\ -H "X-Kiyotaka-Key: YOUR_API_KEY"
Aggregated heatmap (multi-exchange)
Combines orderbook depth from Binance Futures, Bybit, and Binance Spot into a single heatmap. Uses coin=BTC instead of rawSymbol since symbols differ across exchanges, and GROUP_BY_TYPE_SUM to sum the depth at each price level.
curl "https://api.kiyotaka.ai/v1/points ?type=BLOCK_BOOK_SNAPSHOT_AGG &exchange=BINANCE_FUTURES &exchange=BYBIT &exchange=BINANCE &coin=BTC &interval=MINUTE &period=1140 &blockSize=25 &maxDepth=1000 &transform.groupBy.type=GROUP_BY_TYPE_SUM &sortDirection=SORT_DIRECTION_DESC" \\ -H "X-Kiyotaka-Key: YOUR_API_KEY"
USD-denominated heatmap
Returns depth values in USD instead of coin terms. Useful when comparing depth across assets with different prices. All other parameters remain the same.
curl "https://api.kiyotaka.ai/v1/points ?type=BLOCK_BOOK_SNAPSHOT_AGG &exchange=BINANCE_FUTURES &rawSymbol=BTCUSDT &interval=MINUTE &period=1140 &blockSize=25 &maxDepth=1000 &transform.normalize.quote=USD &sortDirection=SORT_DIRECTION_DESC" \\ -H "X-Kiyotaka-Key: YOUR_API_KEY"
Response
{
"series": [
{
"id": {
"type": "BLOCK_BOOK_SNAPSHOT_AGG",
"interval": "MINUTE"
},
"points": [
{
"Point": {
"bids": [70800, 156.241, 70775, 44.591, 70750, 45.816, ...],
"asks": [70825, 43.533, 70850, 64.607, 70875, 100.674, ...],
"timestamp": { "s": 1776080100 }
}
}
]
}
]
}
How to read the arrays
bids and asks are flat arrays of alternating price-volume pairs:
[price1, volume1, price2, volume2, ...]
For example, in the response above:
bids[0]is the first bid price (70800)bids[1]is the volume at that price (156.241)bids[2]is the next bid price (70775)bids[3]is the volume at that price (44.591)bidsmove down in price as you go through the array.asksuse the same alternating format, but move up in price.
Flattened response
When flatten=true, the response replaces points with flat_points -- a single array of floats. Each point is encoded as:
[num_levels, timestamp_micros, price1, volume1, price2, volume2, ...]
Where num_levels is the total number of price-volume pairs (bids + asks combined), timestamp_micros is the snapshot time in microseconds, and price-volume pairs are sorted ascending by price -- bids first, then asks.
{
"series": [{
"id": { "type": "BLOCK_BOOK_SNAPSHOT_AGG", "interval": "MINUTE" },
"flat_points": [
20, 1.7760801e+15,
70575, 179.06799999999998, 70600, 771.27, 70625, 136.633,
70650, 120.14299999999999, 70675, 91.935, 70700, 85.773, ...
]
}]
}