---
title: Orderbook Heatmap
description: Orderbook depth data bucketed by price level for heatmap rendering.
---

# Orderbook Heatmap

<EndpointBar method="GET" path="/v1/points"></EndpointBar>

<TypeHeader type="BLOCK_BOOK_SNAPSHOT_AGG" meta="Weight: 10x | Max points: 4,000"></TypeHeader>

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:

<CodeTabs>

<CodePanel lang="curl">
<pre><span class="s-c"># Get the 4K block size for BTCUSDT on Binance Futures</span>
<span class="s-f">curl</span> <span class="s-s">"https://api.kiyotaka.ai/v1/block-sizes</span>
    <span class="s-p">?exchange</span>=<span class="s-s">BINANCE_FUTURES</span>
    <span class="s-p">&rawSymbol</span>=<span class="s-s">BTCUSDT</span>
    <span class="s-p">&type</span>=<span class="s-s">BLOCK_BOOK_SNAPSHOT_AGG</span><span class="s-s">"</span> \\
  <span class="s-k">-H</span> <span class="s-s">"X-Kiyotaka-Key: YOUR_API_KEY"</span></pre>
</CodePanel>

<CodePanel lang="python">
<pre><span class="s-k">import</span> <span class="s-v">requests</span>
&#10;
<span class="s-v">response</span> = requests.<span class="s-f">get</span>(
    <span class="s-s">"https://api.kiyotaka.ai/v1/block-sizes?exchange=BINANCE_FUTURES&rawSymbol=BTCUSDT&type=BLOCK_BOOK_SNAPSHOT_AGG "</span>,
    headers={<span class="s-s">"X-Kiyotaka-Key"</span>: <span class="s-s">"YOUR_API_KEY"</span>}
)
<span class="s-v">data</span> = response.<span class="s-f">json</span>()</pre>
</CodePanel>

<CodePanel lang="javascript">
<pre><span class="s-k">const</span> <span class="s-v">response</span> = <span class="s-k">await</span> <span class="s-f">fetch</span>(
  <span class="s-s">"https://api.kiyotaka.ai/v1/block-sizes?exchange=BINANCE_FUTURES&rawSymbol=BTCUSDT&type=BLOCK_BOOK_SNAPSHOT_AGG "</span>,
  { headers: { <span class="s-s">"X-Kiyotaka-Key"</span>: <span class="s-s">"YOUR_API_KEY"</span> } }
)
<span class="s-k">const</span> <span class="s-v">data</span> = <span class="s-k">await</span> response.<span class="s-f">json</span>()</pre>
</CodePanel>

</CodeTabs>

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.

<CodeTabs>

<CodePanel lang="curl">
<pre><span class="s-f">curl</span> <span class="s-s">"https://api.kiyotaka.ai/v1/points</span>
    <span class="s-p">?type</span>=<span class="s-s">BLOCK_BOOK_SNAPSHOT_AGG</span>
    <span class="s-p">&exchange</span>=<span class="s-s">BINANCE_FUTURES</span>
    <span class="s-p">&rawSymbol</span>=<span class="s-s">BTCUSDT</span>
    <span class="s-p">&interval</span>=<span class="s-s">MINUTE</span>
    <span class="s-p">&period</span>=<span class="s-n">1140</span>
    <span class="s-p">&blockSize</span>=<span class="s-n">25</span>
    <span class="s-p">&maxDepth</span>=<span class="s-n">1000</span>
    <span class="s-p">&sortDirection</span>=<span class="s-s">SORT_DIRECTION_DESC</span><span class="s-s">"</span> \\
  <span class="s-k">-H</span> <span class="s-s">"X-Kiyotaka-Key: YOUR_API_KEY"</span></pre>
</CodePanel>

<CodePanel lang="python">
<pre><span class="s-k">import</span> <span class="s-v">requests</span>
&#10;
<span class="s-v">response</span> = requests.<span class="s-f">get</span>(
    <span class="s-s">"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 "</span>,
    headers={<span class="s-s">"X-Kiyotaka-Key"</span>: <span class="s-s">"YOUR_API_KEY"</span>}
)
<span class="s-v">data</span> = response.<span class="s-f">json</span>()</pre>
</CodePanel>

<CodePanel lang="javascript">
<pre><span class="s-k">const</span> <span class="s-v">response</span> = <span class="s-k">await</span> <span class="s-f">fetch</span>(
  <span class="s-s">"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 "</span>,
  { headers: { <span class="s-s">"X-Kiyotaka-Key"</span>: <span class="s-s">"YOUR_API_KEY"</span> } }
)
<span class="s-k">const</span> <span class="s-v">data</span> = <span class="s-k">await</span> response.<span class="s-f">json</span>()</pre>
</CodePanel>

</CodeTabs>

### 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.

<CodeTabs>

<CodePanel lang="curl">
<pre><span class="s-f">curl</span> <span class="s-s">"https://api.kiyotaka.ai/v1/points</span>
    <span class="s-p">?type</span>=<span class="s-s">BLOCK_BOOK_SNAPSHOT_AGG</span>
    <span class="s-p">&exchange</span>=<span class="s-s">BINANCE_FUTURES</span>
    <span class="s-p">&rawSymbol</span>=<span class="s-s">BTCUSDT</span>
    <span class="s-p">&interval</span>=<span class="s-s">MINUTE</span>
    <span class="s-p">&period</span>=<span class="s-n">1140</span>
    <span class="s-p">&blockSize</span>=<span class="s-n">5</span>
    <span class="s-p">&maxDepth</span>=<span class="s-n">1000</span>
    <span class="s-p">&sortDirection</span>=<span class="s-s">SORT_DIRECTION_DESC</span><span class="s-s">"</span> \\
  <span class="s-k">-H</span> <span class="s-s">"X-Kiyotaka-Key: YOUR_API_KEY"</span></pre>
</CodePanel>

<CodePanel lang="python">
<pre><span class="s-k">import</span> <span class="s-v">requests</span>
&#10;
<span class="s-v">response</span> = requests.<span class="s-f">get</span>(
    <span class="s-s">"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 "</span>,
    headers={<span class="s-s">"X-Kiyotaka-Key"</span>: <span class="s-s">"YOUR_API_KEY"</span>}
)
<span class="s-v">data</span> = response.<span class="s-f">json</span>()</pre>
</CodePanel>

<CodePanel lang="javascript">
<pre><span class="s-k">const</span> <span class="s-v">response</span> = <span class="s-k">await</span> <span class="s-f">fetch</span>(
  <span class="s-s">"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 "</span>,
  { headers: { <span class="s-s">"X-Kiyotaka-Key"</span>: <span class="s-s">"YOUR_API_KEY"</span> } }
)
<span class="s-k">const</span> <span class="s-v">data</span> = <span class="s-k">await</span> response.<span class="s-f">json</span>()</pre>
</CodePanel>

</CodeTabs>

### 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.

<CodeTabs>

<CodePanel lang="curl">
<pre><span class="s-f">curl</span> <span class="s-s">"https://api.kiyotaka.ai/v1/points</span>
    <span class="s-p">?type</span>=<span class="s-s">BLOCK_BOOK_SNAPSHOT_AGG</span>
    <span class="s-p">&exchange</span>=<span class="s-s">BINANCE_FUTURES</span>
    <span class="s-p">&exchange</span>=<span class="s-s">BYBIT</span>
    <span class="s-p">&exchange</span>=<span class="s-s">BINANCE</span>
    <span class="s-p">&coin</span>=<span class="s-s">BTC</span>
    <span class="s-p">&interval</span>=<span class="s-s">MINUTE</span>
    <span class="s-p">&period</span>=<span class="s-n">1140</span>
    <span class="s-p">&blockSize</span>=<span class="s-n">25</span>
    <span class="s-p">&maxDepth</span>=<span class="s-n">1000</span>
    <span class="s-p">&transform.groupBy.type</span>=<span class="s-s">GROUP_BY_TYPE_SUM</span>
    <span class="s-p">&sortDirection</span>=<span class="s-s">SORT_DIRECTION_DESC</span><span class="s-s">"</span> \\
  <span class="s-k">-H</span> <span class="s-s">"X-Kiyotaka-Key: YOUR_API_KEY"</span></pre>
</CodePanel>

<CodePanel lang="python">
<pre><span class="s-k">import</span> <span class="s-v">requests</span>
&#10;
<span class="s-v">response</span> = requests.<span class="s-f">get</span>(
    <span class="s-s">"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 "</span>,
    headers={<span class="s-s">"X-Kiyotaka-Key"</span>: <span class="s-s">"YOUR_API_KEY"</span>}
)
<span class="s-v">data</span> = response.<span class="s-f">json</span>()</pre>
</CodePanel>

<CodePanel lang="javascript">
<pre><span class="s-k">const</span> <span class="s-v">response</span> = <span class="s-k">await</span> <span class="s-f">fetch</span>(
  <span class="s-s">"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 "</span>,
  { headers: { <span class="s-s">"X-Kiyotaka-Key"</span>: <span class="s-s">"YOUR_API_KEY"</span> } }
)
<span class="s-k">const</span> <span class="s-v">data</span> = <span class="s-k">await</span> response.<span class="s-f">json</span>()</pre>
</CodePanel>

</CodeTabs>

### 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.

<CodeTabs>

<CodePanel lang="curl">
<pre><span class="s-f">curl</span> <span class="s-s">"https://api.kiyotaka.ai/v1/points</span>
    <span class="s-p">?type</span>=<span class="s-s">BLOCK_BOOK_SNAPSHOT_AGG</span>
    <span class="s-p">&exchange</span>=<span class="s-s">BINANCE_FUTURES</span>
    <span class="s-p">&rawSymbol</span>=<span class="s-s">BTCUSDT</span>
    <span class="s-p">&interval</span>=<span class="s-s">MINUTE</span>
    <span class="s-p">&period</span>=<span class="s-n">1140</span>
    <span class="s-p">&blockSize</span>=<span class="s-n">25</span>
    <span class="s-p">&maxDepth</span>=<span class="s-n">1000</span>
    <span class="s-p">&transform.normalize.quote</span>=<span class="s-s">USD</span>
    <span class="s-p">&sortDirection</span>=<span class="s-s">SORT_DIRECTION_DESC</span><span class="s-s">"</span> \\
  <span class="s-k">-H</span> <span class="s-s">"X-Kiyotaka-Key: YOUR_API_KEY"</span></pre>
</CodePanel>

<CodePanel lang="python">
<pre><span class="s-k">import</span> <span class="s-v">requests</span>
&#10;
<span class="s-v">response</span> = requests.<span class="s-f">get</span>(
    <span class="s-s">"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 "</span>,
    headers={<span class="s-s">"X-Kiyotaka-Key"</span>: <span class="s-s">"YOUR_API_KEY"</span>}
)
<span class="s-v">data</span> = response.<span class="s-f">json</span>()</pre>
</CodePanel>

<CodePanel lang="javascript">
<pre><span class="s-k">const</span> <span class="s-v">response</span> = <span class="s-k">await</span> <span class="s-f">fetch</span>(
  <span class="s-s">"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 "</span>,
  { headers: { <span class="s-s">"X-Kiyotaka-Key"</span>: <span class="s-s">"YOUR_API_KEY"</span> } }
)
<span class="s-k">const</span> <span class="s-v">data</span> = <span class="s-k">await</span> response.<span class="s-f">json</span>()</pre>
</CodePanel>

</CodeTabs>

### Response

<CodeBlock lang="JSON">
<pre>{
  <span class="s-p">"series"</span>: [
    {
      <span class="s-p">"id"</span>: {
        <span class="s-p">"type"</span>: <span class="s-s">"BLOCK_BOOK_SNAPSHOT_AGG"</span>,
        <span class="s-p">"interval"</span>: <span class="s-s">"MINUTE"</span>
      },
      <span class="s-p">"points"</span>: [
        {
          <span class="s-p">"Point"</span>: {
            <span class="s-p">"bids"</span>: [<span class="s-n">70800</span>, <span class="s-n">156.241</span>, <span class="s-n">70775</span>, <span class="s-n">44.591</span>, <span class="s-n">70750</span>, <span class="s-n">45.816</span>, <span class="s-o">...</span>],
            <span class="s-p">"asks"</span>: [<span class="s-n">70825</span>, <span class="s-n">43.533</span>, <span class="s-n">70850</span>, <span class="s-n">64.607</span>, <span class="s-n">70875</span>, <span class="s-n">100.674</span>, <span class="s-o">...</span>],
            <span class="s-p">"timestamp"</span>: { <span class="s-p">"s"</span>: <span class="s-n">1776080100</span> }
          }
        }
      ]
    }
  ]
}</pre>
</CodeBlock>

### 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.

<CodeBlock lang="JSON">
<pre>{
  <span class="s-p">"series"</span>: [{
    <span class="s-p">"id"</span>: { <span class="s-p">"type"</span>: <span class="s-s">"BLOCK_BOOK_SNAPSHOT_AGG"</span>, <span class="s-p">"interval"</span>: <span class="s-s">"MINUTE"</span> },
    <span class="s-p">"flat_points"</span>: [
      <span class="s-n">20</span>, <span class="s-n">1.7760801e+15</span>,
      <span class="s-n">70575</span>, <span class="s-n">179.06799999999998</span>, <span class="s-n">70600</span>, <span class="s-n">771.27</span>, <span class="s-n">70625</span>, <span class="s-n">136.633</span>,
      <span class="s-n">70650</span>, <span class="s-n">120.14299999999999</span>, <span class="s-n">70675</span>, <span class="s-n">91.935</span>, <span class="s-n">70700</span>, <span class="s-n">85.773</span>, <span class="s-o">...</span>
    ]
  }]
}</pre>
</CodeBlock>