---
title: Liquidation Heatmap
description: Liquidation data aggregated by price level for heatmap rendering. Advanced and Enterprise tiers only.
---

# Liquidation Heatmap

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

<TypeHeader type="HYPERLIQUID_LIQUIDATION_AGG" meta="Weight: 5x | Max points: 5,000 | Advanced/Enterprise only"></TypeHeader>

Liquidation data aggregated by price level for rendering liquidation heatmaps. Currently sourced from Hyperliquid exchange data.
This endpoint is coin-based. Query it with `coin` (for example `BTC`), not `rawSymbol` -- there is no exchange-native symbol parameter for Hyperliquid liquidation heatmaps.
You can omit `exchange` for this type. `HYPERLIQUID_LIQUIDATION_AGG` already aggregates across Hyperliquid for the requested coin.

## Parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `maxDepth` | int | No | Maximum number of price levels. Default and included depth: 1500. |
| `flatten` | bool | No | When `true`, returns `flat_points` (a single array of floats) instead of `points`. See Flattened response below. |
| `transform.normalize.quote` | Normalize | No | Set to `USD` for USD-denominated levels. Default is coin values. |

## Weight impact

Requests above `maxDepth=1500` increase the depth multiplier by 20% for each additional 1500-level band. For example, `1501-3000` levels cost `1.2x` the base liquidation heatmap weight, and `3001-4500` levels cost `1.4x`. Lower values reduce payload size, but the multiplier does not go below `1.0x`.

## Response fields

| Field | Type | Description |
| --- | --- | --- |
| `levels` | double[] | Alternating `[price, liquidationVolume]` pairs, ordered ascending by price |
| `timestamp` | Timestamp | Snapshot time |

The outer `id` metadata includes the requested `coin`. The point payload contains only `timestamp` and `levels`.

## Examples

### Standard query (coin values)

Fetches 1 hour of hourly liquidation heatmap data for BTC. This type is selected by `coin=BTC`, not by symbol, and does not require an `exchange` parameter. Returns up to 1,500 price levels (default `maxDepth`) showing where liquidation clusters are concentrated. Values are in coin terms.

<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">HYPERLIQUID_LIQUIDATION_AGG</span>
    <span class="s-p">&coin</span>=<span class="s-s">BTC</span>
    <span class="s-p">&interval</span>=<span class="s-s">HOUR</span>
    <span class="s-p">&from</span>=<span class="s-n">1774800000</span>
    <span class="s-p">&period</span>=<span class="s-n">3600</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=HYPERLIQUID_LIQUIDATION_AGG&coin=BTC&interval=HOUR&from=1774800000&period=3600 "</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=HYPERLIQUID_LIQUIDATION_AGG&coin=BTC&interval=HOUR&from=1774800000&period=3600 "</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

Same query but with liquidation values converted to USD. Useful for comparing liquidation exposure across assets with different prices.

<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">HYPERLIQUID_LIQUIDATION_AGG</span>
    <span class="s-p">&coin</span>=<span class="s-s">BTC</span>
    <span class="s-p">&interval</span>=<span class="s-s">HOUR</span>
    <span class="s-p">&from</span>=<span class="s-n">1774800000</span>
    <span class="s-p">&period</span>=<span class="s-n">3600</span>
    <span class="s-p">&transform.normalize.quote</span>=<span class="s-s">USD</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=HYPERLIQUID_LIQUIDATION_AGG&coin=BTC&interval=HOUR&from=1774800000&period=3600&transform.normalize.quote=USD "</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=HYPERLIQUID_LIQUIDATION_AGG&coin=BTC&interval=HOUR&from=1774800000&period=3600&transform.normalize.quote=USD "</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">"HYPERLIQUID_LIQUIDATION_AGG"</span>,
        <span class="s-p">"interval"</span>: <span class="s-s">"HOUR"</span>,
        <span class="s-p">"coin"</span>: <span class="s-s">"BTC"</span>
      },
      <span class="s-p">"points"</span>: [
        {
          <span class="s-p">"Point"</span>: {
            <span class="s-p">"timestamp"</span>: { <span class="s-p">"s"</span>: <span class="s-n">1774800000</span> },
            <span class="s-p">"levels"</span>: [<span class="s-n">66210</span>, <span class="s-n">0.07923</span>, <span class="s-n">66220</span>, <span class="s-n">1.6482400000000001</span>, <span class="s-n">66230</span>, <span class="s-n">0.16869</span>, <span class="s-o">...</span>]
          }
        }
      ]
    }
  ]
}</pre>
</CodeBlock>

### How to read `levels`

`levels` is a flat array of alternating price-volume pairs:
`[price1, liquidationVolume1, price2, liquidationVolume2, ...]`
So:
- `levels[0]` is the first price level
- `levels[1]` is the liquidation volume at that price
- `levels[2]` is the next price level
- `levels[3]` is the liquidation volume at that next price
Prices are ordered ascending. By default the liquidation volume is in coin terms; with `transform.normalize.quote=USD`, the volume values are USD-denominated instead.

### 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 in that snapshot, `timestamp_micros` is the snapshot time in microseconds, and each price-volume pair represents one liquidation level. Multiple snapshots are concatenated back-to-back in the same array.

<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">"HYPERLIQUID_LIQUIDATION_AGG"</span>,
      <span class="s-p">"interval"</span>: <span class="s-s">"MINUTE"</span>,
      <span class="s-p">"coin"</span>: <span class="s-s">"BTC"</span>
    },
    <span class="s-p">"flat_points"</span>: [
      <span class="s-n">4</span>, <span class="s-n">1.77608004e+15</span>,
      <span class="s-n">70390</span>, <span class="s-n">0.53449</span>, <span class="s-n">70400</span>, <span class="s-n">0.00057</span>, <span class="s-n">70410</span>, <span class="s-n">8.36632</span>, <span class="s-n">70420</span>, <span class="s-n">0.04943</span>,
      <span class="s-n">4</span>, <span class="s-n">1.7760801e+15</span>,
      <span class="s-n">70300</span>, <span class="s-n">0.0077</span>, <span class="s-n">70310</span>, <span class="s-n">0.00027</span>, <span class="s-n">70350</span>, <span class="s-n">1.50843</span>, <span class="s-n">70370</span>, <span class="s-n">0.00486</span>
    ]
  }]
}</pre>
</CodeBlock>