TP/SL Heatmap — Kiyotaka Docs

GET/v1/points

HYPERLIQUID_TRIGGER_LIQUIDITY_AGGWeight: 5x | Max points: 5,000 | Advanced/Enterprise only

Resting take-profit (TP) and stop-loss (SL) trigger orders aggregated by price level for rendering trigger-liquidity heatmaps. Sourced from Hyperliquid order data, this endpoint exposes where reduce-only conditional orders sit on the book before they are activated -- useful for spotting clusters that can fuel cascades when price sweeps through them.

Trigger orders split into two order-side arrays:

Buy-side triggers (buy_levels) -- resting reduce-only trigger orders whose order side is buy. A buy-side trigger can represent a short take-profit or short stop-loss depending on Hyperliquid's trigger condition.
Sell-side triggers (sell_levels) -- resting reduce-only trigger orders whose order side is sell. A sell-side trigger can represent a long take-profit or long stop-loss depending on Hyperliquid's trigger condition.

Non-reduce-only breakout and breakdown trigger orders are intentionally excluded.

Query the endpoint with exchange=HYPERLIQUID_FUTURES and rawSymbol for the Hyperliquid symbol. The metadata block on the response includes exchange, rawSymbol, normalizedSymbol, coin, and category when available.

Parameters

Parameter	Type	Required	Description
`exchange`	string	Conditional	`HYPERLIQUID_FUTURES` for Hyperliquid perpetual trigger liquidity. Combine with `rawSymbol` for a single symbol.
`rawSymbol`	string	Conditional	Hyperliquid symbol (for example `BTC`). Pair with `exchange`.
`coin`	string	Conditional	Base asset filter. This returns matching symbol-level series; it does not aggregate them into one TP/SL book.
`maxDepth`	int	No	Maximum number of price levels per side. 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 trigger volumes. Default is base-asset units.

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 TP/SL 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
`buy_levels`	double[]	Alternating `[price, triggerVolume]` pairs for resting buy-side trigger orders, ordered ascending by price
`sell_levels`	double[]	Alternating `[price, triggerVolume]` pairs for resting sell-side trigger orders, ordered ascending by price
`timestamp`	Timestamp	Snapshot time

The outer id metadata includes the requested exchange and rawSymbol, plus coin, normalizedSymbol, and category when available.

Examples

Standard query

Fetches 1 hour of hourly TP/SL trigger liquidity for BTC on Hyperliquid. Returns up to 1,500 price levels per side (default maxDepth) showing where buy-side and sell-side triggers are stacked. Values are in coin terms.

curl "https://api.kiyotaka.ai/v1/points
    ?type=HYPERLIQUID_TRIGGER_LIQUIDITY_AGG
    &exchange=HYPERLIQUID_FUTURES
    &rawSymbol=BTC
    &interval=HOUR
    &from=1774800000
    &period=3600" \\
  -H "X-Kiyotaka-Key: YOUR_API_KEY"

import requests


response = requests.get(
    "https://api.kiyotaka.ai/v1/points?type=HYPERLIQUID_TRIGGER_LIQUIDITY_AGG&exchange=HYPERLIQUID_FUTURES&rawSymbol=BTC&interval=HOUR&from=1774800000&period=3600 ",
    headers={"X-Kiyotaka-Key": "YOUR_API_KEY"}
)
data = response.json()

const response = await fetch(
  "https://api.kiyotaka.ai/v1/points?type=HYPERLIQUID_TRIGGER_LIQUIDITY_AGG&exchange=HYPERLIQUID_FUTURES&rawSymbol=BTC&interval=HOUR&from=1774800000&period=3600 ",
  { headers: { "X-Kiyotaka-Key": "YOUR_API_KEY" } }
)
const data = await response.json()

Minute interval query

Fetches minute-level TP/SL trigger liquidity for the same Hyperliquid Futures symbol.

curl "https://api.kiyotaka.ai/v1/points
    ?type=HYPERLIQUID_TRIGGER_LIQUIDITY_AGG
    &exchange=HYPERLIQUID_FUTURES
    &rawSymbol=BTC
    &interval=MINUTE
    &from=1774800000
    &period=60" \\
  -H "X-Kiyotaka-Key: YOUR_API_KEY"

import requests


response = requests.get(
    "https://api.kiyotaka.ai/v1/points?type=HYPERLIQUID_TRIGGER_LIQUIDITY_AGG&exchange=HYPERLIQUID_FUTURES&rawSymbol=BTC&interval=MINUTE&from=1774800000&period=60 ",
    headers={"X-Kiyotaka-Key": "YOUR_API_KEY"}
)
data = response.json()

const response = await fetch(
  "https://api.kiyotaka.ai/v1/points?type=HYPERLIQUID_TRIGGER_LIQUIDITY_AGG&exchange=HYPERLIQUID_FUTURES&rawSymbol=BTC&interval=MINUTE&from=1774800000&period=60 ",
  { headers: { "X-Kiyotaka-Key": "YOUR_API_KEY" } }
)
const data = await response.json()

USD-denominated

Same symbol query but with trigger volumes converted to USD. Useful for comparing TP/SL trigger exposure across assets with different prices.

curl "https://api.kiyotaka.ai/v1/points
    ?type=HYPERLIQUID_TRIGGER_LIQUIDITY_AGG
    &exchange=HYPERLIQUID_FUTURES
    &rawSymbol=BTC
    &interval=HOUR
    &from=1774800000
    &period=3600
    &transform.normalize.quote=USD" \\
  -H "X-Kiyotaka-Key: YOUR_API_KEY"

import requests


response = requests.get(
    "https://api.kiyotaka.ai/v1/points?type=HYPERLIQUID_TRIGGER_LIQUIDITY_AGG&exchange=HYPERLIQUID_FUTURES&rawSymbol=BTC&interval=HOUR&from=1774800000&period=3600&transform.normalize.quote=USD ",
    headers={"X-Kiyotaka-Key": "YOUR_API_KEY"}
)
data = response.json()

const response = await fetch(
  "https://api.kiyotaka.ai/v1/points?type=HYPERLIQUID_TRIGGER_LIQUIDITY_AGG&exchange=HYPERLIQUID_FUTURES&rawSymbol=BTC&interval=HOUR&from=1774800000&period=3600&transform.normalize.quote=USD ",
  { headers: { "X-Kiyotaka-Key": "YOUR_API_KEY" } }
)
const data = await response.json()

Response

JSON

{
  "series": [
    {
      "id": {
        "type": "HYPERLIQUID_TRIGGER_LIQUIDITY_AGG",
        "exchange": "HYPERLIQUID_FUTURES",
        "normalizedSymbol": "BTC-USD",
        "category": "PERPETUAL",
        "interval": "MINUTE",
        "coin": "BTC"
      },
      "points": [
        {
          "Point": {
            "timestamp": { "s": 1777452840 },
            "buy_levels": [76830, 5.50015, 76840, 3.55056, 76850, 1.36953, ...],
            "sell_levels": [77000, 2.41020, 77100, 8.13422, 77200, 12.65331, ...]
          }
        }
      ]
    }
  ]
}

How to read `buy_levels` and `sell_levels`

Each array is a flat sequence of alternating price-volume pairs: [price1, triggerVolume1, price2, triggerVolume2, ...] So:

buy_levels[0] is the first buy-side trigger price level
buy_levels[1] is the resting trigger volume at that price
buy_levels[2] is the next price level

Both arrays are ordered ascending by price. Buy-side and sell-side triggers can overlap in price -- they describe two different conditional-order side books, not trigger directions or a single bid/ask spread. By default the trigger volume is in coin terms; with transform.normalize.quote=USD, the 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 (buy-side triggers + sell-side triggers combined), timestamp_micros is the snapshot time in microseconds, and price-volume pairs are sorted ascending by price. Flat mode does not preserve whether a price-volume pair came from buy_levels or sell_levels; clients that need separate buy/sell trigger levels should use structured points. Multiple snapshots are concatenated back-to-back in the same array.