How to read the Hyperliquid liquidation map, and how it's built

The liquidation map shows where open Hyperliquid perp positions would be liquidated if the price moved. This page explains how to read it, how each liquidation price is computed, how we check it against Hyperliquid, where it can be wrong, and how to get the same data from the API or an AI agent.

The short version#

• What: every open perp position, placed at the price where it would be liquidated. Longs sit below the price, shorts above.
• Columns: the left one is what liquidates in each price range, the right one is the running total from the price to that range.
• Source: our node's state snapshot, about every 12 minutes. Around 139,000 wallets and 419,000 positions.
• Accuracy: checked every cycle against Hyperliquid's own liquidationPx. 99.4% of sampled positions are within 0.1%.
• Data: GET /v1/liquidations/map over REST, or get_liquidation_map over MCP.

1. What the map shows#

The map is a projection. It takes the positions that are open now and puts each one at the price where it would be liquidated. Liquidations that already happened are on the liquidation heatmap.

• A long is liquidated when the price falls, so longs sit below the current price. Shorts sit above it.
• Each row is one price range. Its width is the bucket_size, about 0.25% of the price rounded to 1, 2 or 5 times a power of ten: 200 USD for BTC near 75,000. The page merges rows into wider ranges so the ladder fits a phone.
• The left column, IN THIS RANGE, is the notional liquidated inside the range: size times liquidation price, summed over every position there.
• The right column, FROM THE PRICE TO HERE, is the running total: everything between the current price and that row. It is what a move to that price would liquidate.
• The tiles above the chart give longs and shorts within 5% and 10% of the price, and the largest cluster.
• The line is the current mark price. The line under the market name gives the snapshot's block and age.

2. Reading a wall and a cascade#

A wall#

A wall is one price range with much more notional than the ranges around it. It shows as a long bar in the left column and a step in the running total. If the price gets there, those positions are liquidated together: market sells for longs, market buys for shorts, all near one price.

On BTC on 6 November 2026, with the price at 75,866, longs at 71,600 to 71,800 held $33.3M. That was the largest range within 10% of the price.

A cascade#

A cascade is many ranges close together with notional in each. The running total climbs steeply over a short distance. Each liquidation sells or buys into the book, and that can move the price into the next range. Read the running total at the price you care about. On the same day, a BTC fall to 70,400 would have liquidated $400M of longs.

Gaps and the two sides#

An empty stretch means few positions would be liquidated there. Compare the two sides with the tiles: when longs within 5% are several times the shorts within 5%, a 5% fall would force more liquidations than a 5% rise. The map says where forced orders would hit the book. It says nothing about whether the price goes there.

3. How it is built#

• Positions. Our Hyperliquid node writes a full state snapshot about every 12 minutes. We read every open perp position from it, on every live dex, HIP-3 markets included: around 139,000 wallets and 419,000 positions.
• Collateral. It depends on the account mode. A standard account margins each dex on its own collateral. A unified account has one USDC balance that backs its cross positions on every USDC dex, spot USDC included. An isolated position uses only its own margin.
• Maintenance margin. It follows Hyperliquid's margin tiers: notional divided by twice the tier's max leverage, minus the tier's deduction. Large positions fall into tiers with lower leverage, so they need more margin.
• The price. For a cross position we hold the account's other positions at the mark and solve for the price where account equity equals maintenance margin. If no positive price works, the position has no liquidation price. It is fully backed or hedged and stays off the map.
• Portfolio margin. These accounts use HYPE, BTC, USDC and USDT together as collateral. For them we take Hyperliquid's own liquidationPx from our node. They hold about 6% of open notional.
• Updates. Prices are re-applied with fresh marks every minute. Positions are rebuilt when the next snapshot lands. Notional is summed on a grid of 0.25% of the price, then spread into round price ranges.

4. Accuracy#

Every cycle the service takes a random sample of wallets and asks our node for Hyperliquid's liquidationPx on each of their positions, the same number clearinghouseState returns. Wallets that traded between the snapshot and the check are left out, because their positions changed.

• 99.4% of sampled positions are within 0.1% of Hyperliquid's price.
• The median error is around 5e-13. That is floating point rounding.
• In our first tests the misses were wallets whose balances moved after the snapshot, mostly market makers trading spot.

5. Limits#

• Correlated moves. A cross price assumes the account's other positions stay at the mark. In a real sell-off correlated markets fall together, so an account holding several longs is liquidated earlier, closer to the current price, than the map shows.
• Partial liquidations. For a position above 100,000 USDC, Hyperliquid sends only 20% to the book at first, then waits 30 seconds. A large position is liquidated in steps and can survive the first one. Below 2/3 of maintenance margin the liquidator vault takes the position over.
• Portfolio margin. About 6% of open notional comes from Hyperliquid's own number, which we do not compute. The share per market is in coverage.portfolio_margin_pct.
• Snapshot age. Positions are up to about 12 minutes old. A position opened after the snapshot appears at the next one, and a position liquidated meanwhile stays on the map until then.
• Fully backed positions. Positions without a liquidation price are left out. coverage.with_liq_px_pct says how much of a market's notional is on the map.

6. Getting the data#

curl#

One call returns the map for any Hyperliquid perp, HIP-3 markets included:

curl -s "https://api.ironflow.sh/v1/liquidations/map?market=BTC-PERP&range_pct=10" \
  -H "Authorization: Bearer $IRONFLOW_API_KEY"

{
  "market": "BTC-PERP",
  "mark_px": 75866,
  "snapshot": { "height": 1211710000, "time": "2026-11-06T21:04:37Z", "age_s": 199 },
  "bucket_size": 200,
  "levels": [
    {
      "price_lo": 71600,
      "price_hi": 71800,
      "long_usd": 33326316,
      "long_positions": 191,
      "short_usd": 0,
      "short_positions": 0,
      "cum_long_usd": 325972581,
      "cum_short_usd": 0
    }
  ],
  "coverage": { "notional_usd": 3211097479, "with_liq_px_pct": 97.7, "portfolio_margin_pct": 3.2 },
  "stale": false
}
# trimmed: as_of, range_pct, side, method and the other levels omitted

• Parameters: market (BTC and BTC-PERP both work), bucket_size (auto or a width in price units), range_pct (default 20, max 50) and side (both, long or short).
• cum_long_usd and cum_short_usd are the running totals from the price to each level.
• snapshot.age_s is how old the positions are. stale: true means the map service did not answer and this is the last map, up to 30 minutes old.
• GET /v1/liquidations/map/markets lists every market on the map with its long and short notional, no key needed.

The largest long wall in one line:

curl -s "https://api.ironflow.sh/v1/liquidations/map?market=BTC-PERP" \
  | jq -c '.levels | max_by(.long_usd) | {price_lo, price_hi, long_usd, cum_long_usd}'

{"price_lo":71600,"price_hi":71800,"long_usd":33326316,"cum_long_usd":325972581}

Python#

Longs and shorts within 5% of the price, and the largest wall:

import os
import requests

key = os.environ.get("IRONFLOW_API_KEY")
r = requests.get(
    "https://api.ironflow.sh/v1/liquidations/map",
    params={"market": "BTC-PERP", "range_pct": 10},
    headers={"Authorization": f"Bearer {key}"} if key else {},
    timeout=10,
)
r.raise_for_status()
m = r.json()
mark = m["mark_px"]
levels = m["levels"]

# The running totals count everything between the price and each level,
# so the farthest level inside 5% holds the answer.
longs_5 = max((l["cum_long_usd"] for l in levels if l["price_lo"] >= mark * 0.95), default=0)
shorts_5 = max((l["cum_short_usd"] for l in levels if l["price_hi"] <= mark * 1.05), default=0)

# The largest wall: the one price range with the most notional.
wall = max(levels, key=lambda l: max(l["long_usd"], l["short_usd"]))
side = "longs" if wall["long_usd"] >= wall["short_usd"] else "shorts"
usd = max(wall["long_usd"], wall["short_usd"])

print(f"{m['market']} at {mark:,.0f}, positions from {m['snapshot']['age_s'] // 60} min ago")
print(f"longs within 5%:  ${longs_5:,.0f}")
print(f"shorts within 5%: ${shorts_5:,.0f}")
print(f"largest wall: {side} at {wall['price_lo']:,.0f} to {wall['price_hi']:,.0f}, ${usd:,.0f}")

BTC-PERP at 75,872, positions from 4 min ago
longs within 5%:  $244,308,944
shorts within 5%: $22,547,736
largest wall: longs at 71,600 to 71,800, $32,108,161

Without a key the response holds only the 10 largest levels, so the 5% totals stop at the farthest of those inside 5%. With a key every level is there.

MCP#

AI agents read the same map with the get_liquidation_map tool on our hosted MCP server at https://mcp.ironflow.sh/mcp. It takes market, bucket_size, range_pct and side, works without a key, and returns the API's JSON. In Claude Code:

claude mcp add --transport http ironflow https://mcp.ironflow.sh/mcp

Other clients take the URL. Setup for each is in the MCP docs.

Prompts to ask an agent#

• “Where would BTC longs get liquidated if the price fell 5%?”
• “Which Hyperliquid market has the biggest liquidation wall within 3%?”
• “How much ETH short notional would a 10% rise liquidate?”
• “Compare the HYPE liquidation map with HYPE liquidations in the last 24 hours.”

The last one makes the agent call get_liquidation_map for the projection and get_liquidation_levels for the past liquidations, then compare them.

Questions#

Related guides#

• Hyperliquid liquidation data: history, live feed, levels and API
• Hyperliquid historical data: API, S3 archive and Python
• Hyperliquid API rate limits explained

References#

• Hyperliquid docs: Liquidations. Maintenance margin, partial liquidations above 100k USDC and the liquidator vault.
• Hyperliquid docs: Margin tiers. Max leverage and maintenance margin by position size.
• Hyperliquid docs: Account abstraction modes. Standard, unified and portfolio margin accounts.
• Hyperliquid docs: Portfolio margin. Collateral and liquidation for portfolio margin accounts.
• Hyperliquid docs: Info endpoint, perpetuals. clearinghouseState and liquidationPx, one address per request.
• Ironflow docs: Liquidation map. Parameters and fields of /v1/liquidations/map.
• Ironflow docs: Liquidation map markets. The markets the map covers.