Perpetuals API

Liquidation heatmap brief: strongest liquidation levels above and below price

A coin's price and the price levels with the most US dollars modelled to liquidate, top 10 above and below it.

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

Get a free API key Try it in the API reference

What it returns

The compact answer of the liquidation heatmap: the coin's price and the price levels where the most US dollars of leveraged derivatives positions are modelled to be force-liquidated, the strongest 10 above the price and the strongest 10 below it. It reads the same map as derivatives-liquidation-heatmap and takes the same parameters; the levels are the map's latest candle, the model's current state, and price is that candle's close. Prefer it to the full heatmap unless you need the price-by-time grid. The levels 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-brief/<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 brief: strongest liquidation levels above and below price
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`.
`updatedAt`	number \| null	When the model was last recomputed, unix seconds; null when not stated (180d and 1y).
`at`	number	Open of the map's latest candle, unix seconds: the snapshot the levels and price come from.
`price`	number	The coin's price: the close of the map's latest candle.
`above`	object[]	Up to 10 price levels strictly above `price`, largest US dollars first (a tie goes to the level nearer the price). Empty when the model has none on that side.
`above[].price`	number	The price level.
`above[].usd`	number	US dollars of positions modelled to liquidate at that level.
`below`	object[]	Up to 10 price levels strictly below `price`, largest US dollars first (a tie goes to the level nearer the price). Empty when the model has none on that side.
`below[].price`	number	The price level.
`below[].usd`	number	US dollars of positions modelled to liquidate at that level.
`note`	string	Says the levels are modelled, not observed.

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 for one coin: modelled liquidations by price, over time
The full answer this one condenses
Price levels where one coin's leveraged positions would be liquidated
The strongest modelled levels around the price now, or the model at one instant split by exchange.
Perpetual-futures markets, all of them
Every perpetual-futures market this surface covers, with its current state. A MARKET is keyed by trading symbol, not by chain and mint — these are derivatives, not tokens you hold.
One perpetual-futures market, by symbol
The current state of ONE perpetual-futures market, keyed by trading SYMBOL. No chain, no mint — an unrecognised symbol is refused rather than guessed at.
Open positions in one perpetual-futures market
The positions currently open in ONE perpetual-futures market, keyed by trading symbol. Answers who is exposed and on which side, not what a token is worth.
Liquidation levels for one perpetual-futures market
Where open positions in ONE perpetual-futures market would be liquidated, keyed by trading symbol. A risk map for a derivatives market, unrelated to a token's on-chain holders.

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