Skip to main content
Type: BLOCK_BOOK_SNAPSHOT_AGG | Weight: 10x | Max points: 4,000 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.
ResolutionBlock SizeDescription
4KValue from /v1/block-sizesFinest granularity. More detail at each price step.
HD5x the /v1/block-sizes valueStandard 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

ParameterTypeRequiredDescription
blockSizedoubleYesPrice bucket size in USD. Determines the granularity of each price level.
maxDepthintNoNumber of price levels to return. Each level spans one blockSize. Default and included depth: 3500.
flattenboolNoWhen true, returns flat_points (a single array of floats) instead of points. See Flattened response.
transform.groupBy.typeGroupByNoSet to GROUP_BY_TYPE_SUM for multi-exchange aggregation.
transform.normalize.quoteNormalizeNoSet 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

FieldTypeDescription
bidsdouble[]Alternating [price, volume] bid pairs, ordered from closest to furthest from mid price
asksdouble[]Alternating [price, volume] ask pairs, ordered from closest to furthest from mid price
timestampTimestampSnapshot 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)
bids move down in price as you go through the array. asks use 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, ...
    ]
  }]
}