Get liquidation heatmap data (Model 1) for a futures trading pair on an exchange: the price (vertical) axis, time-stamped price candles, and the liquidation intensity at each time and price position. Useful for drawing a liquidation heatmap and spotting price zones where liquidations cluster.
| Time | Status | User Agent | |
|---|---|---|---|
Retrieving recent requests… | |||
Available on these API plans: Professional Enterprise
Response Data
data has four parts: y_axis is the price (vertical) axis, price_candlesticks are the price candles along the horizontal axis in time order, liquidation_leverage_data holds the heatmap points, and update_time is the time the result was generated. Each heatmap point refers to the first two by index: [i, j, v] means that the liquidation intensity is v at the time of the candle price_candlesticks[i] and at the price y_axis[j].
Note the Intensity and Time UnitsEach array in
liquidation_leverage_datais[X-axis index, price index, liquidation intensity]: the X-axis index points to a position inprice_candlesticks, and the price index points to a position iny_axis. The liquidation intensity is a model output and must not be treated as an actual liquidation amount or a dollar amount, so do not add a currency symbol when displaying it; the sum of the intensities at different positions must not be treated as an expected total liquidation amount either.The first value in each
price_candlestickselement is the start time of the candle period, in seconds, whileupdate_time(the time the result was generated) is in milliseconds. Do not mix the two.
200 · application/json · See the response example in the right panel.
| Field | Type | Always Returned | Description |
|---|---|---|---|
code | string | Yes | Business status code; "0" means success |
msg | string | No | Result message |
data | object | Yes | Heatmap data |
data.y_axis | array of number | Yes | Y-axis coordinates, i.e., price levels; the index at position 1 of liquidation_leverage_data points here |
data.liquidation_leverage_data | array of array | Yes | Array of heatmap points; each element is [X-axis index, Y-axis index, liquidation intensity]: position 0 is an integer pointing to a position in price_candlesticks (0-based); position 1 is an integer pointing to a position in y_axis (0-based); position 2 is the liquidation intensity at that position, a model output that must not be treated as an amount |
data.price_candlesticks | array of array | Yes | Array of price candles; each element is [open time, open, high, low, close, volume]: position 0 is the start time of the candle period, a timestamp in seconds (UTC); positions 1–4 are prices, as strings; position 5 is the trading volume in USD, as a string |
data.update_time | integer (int64) | Yes | Time the result was generated, timestamp in milliseconds (UTC) |
Positions in each liquidation_leverage_data element
| Position | Meaning | Description |
|---|---|---|
| 0 | X-axis index | Integer, 0-based; points to the candle at the same position in price_candlesticks (i.e., the time) |
| 1 | Y-axis index | Integer, 0-based; points to the price at the same position in y_axis |
| 2 | Liquidation intensity | Liquidation intensity at that time and price; a model output that must not be treated as an actual liquidation amount |
Positions in each price_candlesticks element
| Position | Meaning | Description |
|---|---|---|
| 0 | Open time | Start time of the candle period, timestamp in seconds (UTC) |
| 1 | Open | String |
| 2 | High | String |
| 3 | Low | String |
| 4 | Close | String |
| 5 | Volume (USD) | Trading volume of the candle in USD, as a string |
API Plans
Only the API plans marked Yes in the table below can call this endpoint. For the price of each plan, see API Plans.
| API Plan | Access |
|---|---|
| Hobbyist | ❌ No |
| Startup | ❌ No |
| Standard | ❌ No |
| Professional | ✅ Yes |
| Enterprise | ✅ Yes |
Use This Endpoint with AI
Pick a task and click Open in ChatGPT or Open in Claude: the AI reads this page first and then gives you the result. You can also click Copy and paste the full prompt into the AI tool you use.
This endpoint provides data through the REST API. Use the prompts above to have AI write the request code. For the tools available through MCP, see CoinGlass MCP.
Use Cases
| Scenario | Description |
|---|---|
| Identify Liquidation Clusters | Find price zones with high liquidation intensity to see which levels may trigger more liquidations as price approaches them. |
| Plan Stop-Losses and Orders | Use liquidation clusters as a reference when placing stop-losses and orders, avoiding prices that are likely to be hit by cascading liquidations. |
| Review Past Moves | Look back, alongside the candles, at how the distribution of liquidation intensity changed before and after large price swings. |
| Market Dashboard | Show a trading pair's liquidation heatmap on a dashboard and watch, together with price, where leverage is concentrated. |
Related Endpoints
| Endpoint | How It Differs |
|---|---|
| Pair Liquidation Heatmap (Model 2) | Same type of heatmap, calculated with Model 2 |
| Pair Liquidation Heatmap (Model 3) | Same type of heatmap, calculated with Model 3 |
| Coin Liquidation Heatmap (Model 1) | Heatmap that aggregates multiple markets by coin |
| Pair Liquidation Map | Gives the liquidation intensity by price level only, without a time axis |
FAQ
Is the liquidation intensity a dollar amount?
It should not be read as a dollar amount. The liquidation intensity is a model output; it must not be treated as an actual liquidation amount, nor as a USD or USDT amount. Do not add a currency symbol when displaying it.
Why are the timestamps 10 digits long?
Position 0 of each price_candlesticks element is a timestamp in seconds, while update_time is a timestamp in milliseconds. Convert them to the same unit before converting times, e.g., multiply the seconds by 1000.
What should I pass for symbol?
Pass a trading pair here, not a coin; for example, the BTC perpetual contract on Binance is BTCUSDT. Exchanges write pairs differently, so go by what the Supported Exchanges and Pairs endpoint returns.
What is the difference between Models 1, 2 and 3?
The three models are calculated separately, so liquidation intensities cannot be compared or added across models. For example, with range=12h, the price_candlesticks of Models 1 and 2 are 5 minutes apart and those of Model 3 are 1 minute apart, and the y_axis price ranges of the three also differ.
Learn More: Liquidation Heatmap
What Is a Liquidation Heatmap?
A liquidation heatmap plots the model-estimated distribution of liquidations on a time–price plane: the horizontal axis is time, the vertical axis is price, and a brighter color means a higher liquidation intensity at that time and price.
How Do I Draw a Heatmap from the Response Data?
Create a matrix with as many columns as the length of price_candlesticks and as many rows as the length of y_axis, put each [i, j, v] into row j, column i, and then draw the candles on the same chart.
How Is a Liquidation Heatmap Different from a Liquidation Map?
A heatmap has a time axis, so you can see how the liquidation intensity changes over time; a liquidation map (such as Pair Liquidation Map) has no time axis and only gives the liquidation intensity by price level, which suits a bar-chart distribution.