Perpetuals API

Liquidation heatmap for one coin: modelled liquidations by price, over time

A liquidation heatmap: US dollars of a coin's leveraged positions modelled to liquidate at each price, over time, summed across major exchanges or for one exchange. Keyed by coin ticker.

GET/api/external/perps/derivatives-liquidation-heatmap/{symbol}

Get a free API key Try it in the API reference

What it returns

A liquidation heatmap: where one coin's leveraged derivatives positions were modelled to be force-liquidated, by price level and over time. prices is the price axis (lowest first), candles the time axis (oldest first, with the price candle of each step), and each cell [candleIndex, priceIndex, usd] is the US dollars of positions modelled to liquidate at that price at that time; only non-zero cells are listed. By default the map is summed across the major centralized venues; venue (with an optional instrument, else the venue's main USD-margined perpetual) narrows it to one venue, Hyperliquid included, always in US dollars. range sets the window and with it the candle spacing: 5 minutes up to 24h, 15 minutes at 3d, 30 at 7d, 2 hours at 30d, 6 at 90d, 12 at 180d, a day at 1y (the wide model: 1 minute at 12h, 5 up to 3d, 30 at 7d, 1 hour at 30d, 4 at 90d, 8 at 180d and 1y). model picks one of two liquidation models, standard by default. Large maps keep only their largest cells: cellCount says how many there were and capped whether some were dropped. The cells are a model, not a record of real liquidations. A coin or instrument that is not mapped answers 404.

Chains

This endpoint is not tied to a chain: it takes no chain in its request.

Request

Send your key in the x-dex-data-key header. Replace each <placeholder> with a real value.

curl -H "x-dex-data-key: $DEXDATA_API_KEY" \
  "https://api.dexdata.io/api/external/perps/derivatives-liquidation-heatmap/<symbol>"

Parameters
Parameter	Description
`range` query · string · optional	The window: 12h, 24h, 3d, 7d, 30d, 90d, 180d or 1y. A longer one spaces its candles wider. Defaults to 24h.`12h24h3d7d30d90d180d1y`
`model` query · string · optional	The liquidation model. `standard` (the default) maps a narrow band around the price. `wide` is a second model over a band about four times wider on about three times as many levels; its dollars are a separate, much smaller estimate (about 3-5% of the standard total), so compare levels within one model, never across the two. With `venue`, `wide` maps only Binance, OKX, Bybit, Bitget.`standardwide`
`venue` query · string · optional	One venue to map, spelled as listed. Omit it for the map summed across venues.`BinanceOKXBybitGateBitgetDeribitMEXCBingXKrakenHTXAsterHyperliquid`
`instrument` query · string · optional	The venue's instrument id, e.g. "BTCUSDT", "BTC-USDT-SWAP" or "BTC-USD" on Hyperliquid; case-insensitive. Only with `venue`; omitted, the venue's main USD-margined perpetual for the coin.
`symbol` path · string · required	The coin (base asset) ticker, e.g. "BTC" or "SOL" — not a venue instrument id such as "BTCUSDT" (that goes in `instrument`), and not a token mint or contract address. Case-insensitive.

Response fields

A JSON response. Every field is always present; null means the value could not be established, never zero.

Response fields of Liquidation heatmap for one coin: modelled liquidations by price, over time
Field	Type	Description
`symbol`	string	The coin ticker, upper-cased.
`venue`	string \| null	The venue mapped; null for the map summed across venues.
`instrument`	string \| null	The venue's instrument id mapped, upper-cased; null for the map summed across venues.
`range`	string	The window asked for.
`model`	string	The liquidation model asked for: `standard` or `wide`.
`interval`	number \| null	Seconds between candles; null with fewer than two.
`updatedAt`	number \| null	When the model was last recomputed, unix seconds; null when not stated (180d and 1y).
`prices`	number[]	The price axis, lowest first. A cell's priceIndex points into it.
`candles`	object[]	The time axis, oldest first, with the coin's price candle at each step. A cell's candleIndex points into it.
`candles[].at`	number	The candle's open, unix seconds.
`candles[].open`	number	Opening price.
`candles[].high`	number	Highest price.
`candles[].low`	number	Lowest price.
`candles[].close`	number	Closing price.
`cells`	number[][]	[candleIndex, priceIndex, usd]: US dollars of positions modelled to liquidate at prices[priceIndex] during candles[candleIndex]. Non-zero cells only, by candle then price.
`cellCount`	number	Non-zero cells in the whole map, before any were dropped.
`capped`	boolean	true when the map had more cells than one response carries and only the largest are listed.
`maxUsd`	number \| null	The largest cell in the map, US dollars — the top of the colour scale; null when the map has no cell.

Price per call

Every call: 6 credits

Charged only when the call succeeds. Prices as of 2026-10-30; the current ones are always in the API reference.

Liquidation heatmap brief: strongest liquidation levels above and below price
The same answer in a compact response
Price levels where one coin's leveraged positions would be liquidated
The same liquidation model over time as a heatmap, or at one instant split by exchange.
Liquidation levels for one perpetual-futures market
A price-by-time liquidation heatmap for a coin, or one perpetual market's positions bucketed by liquidation price now.
One coin's long and short liquidations summed across venues, over time
Where liquidations were modelled over time, against what was actually liquidated.
Order book heatmap for one coin on one exchange: resting orders by price
Resting order walls by price over time, against modelled liquidation clusters by price over time.
Order book heatmap brief: largest resting bids and asks over time
Resting order walls by price over time, against modelled liquidation clusters by price over time.

Start building with DexData today

Sign in, create a key and make your first call in a minute. Free credits every month, and you only pay for calls that succeed.

Get a free API key