| View | How it is built |
|---|---|
| Heatmap | Each bucket by its distance from the snapshot's mid_price, with time across |
| Price ladder | The latest snapshot, each bucket at its center price |
| Cumulative exposure | The latest snapshot sorted by distance from mid_price, summed outward |
| Average per position | long_notional divided by long_count, and short_notional by short_count |
| Distance bands | Notional summed into 0 to 3%, 3 to 6% and 6 to 10% from mid_price |
A liquidation heatmap is useful, but it is not the only way to read projected forced-liquidation price-level history. This guide uses one real 48-hour BTC response to show where projected long- and short-side notional sits, how it accumulates, how position counts change by bucket and how distance-band clusters move over time.
What this is: a view of projected forced-liquidation price levels from the history endpoint. What this is not: a record of completed forced executions or a map of pending take-profit and stop-loss triggers. Those are separate datasets.
Example update: these charts use BTC projected forced-liquidation-level history from August 30, 2026 at 19:20:25.413 UTC to September 1, 2026 at 19:20:25.413 UTC. The example window stays fixed so it can be reproduced.
GET /v1/hyperliquid/liquidations/BTC/levels/history
?start=1788117625413
&end=1788290425413
&limit=100
&range_pct=10
&buckets=50Each snapshot includes snapshot_ts, block_number, mid_price, total_long, total_short, flagged_notional and price buckets with long_notional, short_notional, long_count and short_count.
1. Projected forced-liquidation heatmap
Normalize each bucket by its distance from that snapshot's mid_price, then place time on the horizontal axis. Red cells show short positions projected to liquidate above the mark. Green cells show long positions projected to liquidate below the mark. Brightness uses the same log-scaled USD-notional range on both sides.

2. Projected notional by price bucket
Take the latest snapshot and plot each bucket at its center price. Long-side projected notional extends left and short-side projected notional extends right. The dashed line marks the snapshot's mid_price.

3. Cumulative projected notional
Sort the latest snapshot by absolute distance from mid_price, then sum projected notional outward. The result shows how much long-side exposure sits below the mark and how much short-side exposure sits above it as the distance widens.

4. Average projected notional per position
Notional alone cannot distinguish many smaller positions from a smaller number of larger ones. For buckets with nonzero counts, divide long_notional by long_count and short_notional by short_count.

5. Distance-band movement over time
For every snapshot, sum long- and short-side projected notional into three absolute distance bands: 0–3%, 3–6% and 6–10% from mid_price. This separates changes near the mark from shifts farther away.

Build all five charts from one response
Example update: these charts use BTC projected forced-liquidation-level history from August 30, 2026 at 19:20:25.413 UTC to September 1, 2026 at 19:20:25.413 UTC. The example window stays fixed so it can be reproduced.
{
"snapshot_ts": "2026-08-30 19:24:31.000",
"block_number": 1129510000,
"mid_price": 78910.0,
"total_long": 1156845230.97,
"total_short": 1111012990.69,
"flagged_notional": 217914673.56,
"levels": [
{
"price": 71176.82,
"long_notional": 15710644.53,
"short_notional": 0.0,
"long_count": 313,
"short_count": 0
}
]
}Group the bucket rows by price, long or short side, position count, distance from mid_price or snapshot_ts, depending on the chart. The response stays the same.
For exact endpoint fields and parameters, see the projected forced-liquidation level history reference. For completed forced executions, use the completed liquidation-events guide. Pending take-profit and stop-loss concentrations use the separate trigger-level history contract.
Common questions about Hyperliquid liquidation heatmaps
What is a Hyperliquid liquidation heatmap?
A chart of where open Hyperliquid positions are projected to be force-liquidated, with distance from the mark price on one axis and time on the other. Shorts sit above the mark, longs below it, and brighter cells hold more projected notional.
Is a liquidation heatmap the same as liquidation history?
Not in this guide. Its heatmap is built from projected forced-liquidation price levels, estimated from positions and margin at each snapshot. Forced executions that already happened, with price, size and wallet, come from a separate liquidation events route.
What is the difference between a liquidation map and a heatmap?
The map here is the latest snapshot drawn as a price ladder: projected long notional at each price below the mark and short notional above it. The heatmap adds time, so you can watch those clusters move.
Why are long liquidations below the price and short liquidations above it?
A long is forced out when price falls far enough to use up its margin, so its projected level sits below the mark. A short is forced out when price rises, so its level sits above.
Is there an API for Hyperliquid liquidation levels?
Yes. 0xArchive's projected forced-liquidation level history returns snapshots for a symbol, each with the mid price, long and short totals, and price buckets holding notional and position counts. One response builds all five charts in this guide.