Skip to main content
Type: HYPERLIQUID_LIQUIDATION_AGG | Weight: 5x | Max points: 5,000 | Advanced/Enterprise only 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

ParameterTypeRequiredDescription
maxDepthintNoMaximum number of price levels. Default and included depth: 1500.
flattenboolNoWhen true, returns flat_points (a single array of floats) instead of points. See Flattened response.
transform.normalize.quoteNormalizeNoSet 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

FieldTypeDescription
levelsdouble[]Alternating [price, liquidationVolume] pairs, ordered ascending by price
timestampTimestampSnapshot 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. 
curl "https://api.kiyotaka.ai/v1/points?type=HYPERLIQUID_LIQUIDATION_AGG&coin=BTC&interval=HOUR&from=1774800000&period=3600" \
  -H "X-Kiyotaka-Key: YOUR_API_KEY"

​
USD-denominated

Same query but with liquidation values converted to USD. Useful for comparing liquidation exposure across assets with different prices. 
curl "https://api.kiyotaka.ai/v1/points?type=HYPERLIQUID_LIQUIDATION_AGG&coin=BTC&interval=HOUR&from=1774800000&period=3600&transform.normalize.quote=USD" \
  -H "X-Kiyotaka-Key: YOUR_API_KEY"

​
Response

{
  "series": [
    {
      "id": {
        "type": "HYPERLIQUID_LIQUIDATION_AGG",
        "interval": "HOUR",
        "coin": "BTC"
      },
      "points": [
        {
          "Point": {
            "timestamp": { "s": 1774800000 },
            "levels": [66210, 0.07923, 66220, 1.6482400000000001, 66230, 0.16869, ...]
          }
        }
      ]
    }
  ]
}

​
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. 
{
  "series": [{
    "id": {
      "type": "HYPERLIQUID_LIQUIDATION_AGG",
      "interval": "MINUTE",
      "coin": "BTC"
    },
    "flat_points": [
      4, 1.77608004e+15,
      70390, 0.53449, 70400, 0.00057, 70410, 8.36632, 70420, 0.04943,
      4, 1.7760801e+15,
      70300, 0.0077, 70310, 0.00027, 70350, 1.50843, 70370, 0.00486
    ]
  }]
}