Hyperliquid liquidation data: history, live feed, levels and API

Hyperliquid has no liquidations feed. A liquidation is a fill with an extra field. This page covers how liquidations happen, how to find them in fill data, what the public API returns, and how to get liquidation history, a live stream and price levels from Ironflow's API.

The short version#

• Where they live: on fills. A liquidation fill has a liquidation object with liquidatedUser, markPx and method.
• Hyperliquid API: per wallet only, through userFills, userFillsByTime and the userEvents WebSocket.
• Every wallet: fills from a node, the S3 archive, or Ironflow's /v1/liquidations.
• Live: Ironflow's /v1/liquidations/stream pushes every liquidation as it lands. A free key is enough.
• Levels: Ironflow groups past liquidations by price. Hyperliquid gives a liquidation price per position, one address at a time.

1. How a liquidation happens#

From Hyperliquid's liquidations docs:

• A position is liquidated when account equity falls below the maintenance margin. Maintenance margin is half the initial margin at max leverage: 1.25% for 40x assets up to 16.7% for 3x assets.
• Liquidation checks use the mark price. During volatile periods the mark can differ from the book price.
• The first attempt sends market orders to the book for the full position. If the account meets maintenance margin afterwards, the trader keeps the remaining collateral.
• For positions above 100k USDC, only 20% is sent first. For 30 seconds after a partial liquidation, market liquidation orders for that user are for the whole position.
• Below 2/3 of the maintenance margin, the liquidator vault takes over the position and its margin. This is a backstop liquidation. The liquidator vault is a strategy inside HLP.

For data this means one liquidation can produce several fills. A market order can fill against several resting orders, and a large position can be liquidated in steps.

2. Liquidations in fill data#

A liquidation fill from userFillsByTime, as returned on 27 October 2026:

{
  "coin": "BTC",
  "px": "79700.0",
  "sz": "0.00297",
  "side": "A",
  "time": 1793070456365,
  "dir": "Close Long",
  "closedPnl": "-2.76804",
  "crossed": true,
  "liquidation": {
    "liquidatedUser": "0x8271...99d3",
    "markPx": "79699.0",
    "method": "market"
  }
}
# trimmed: hash, oid, tid, fee and other fields omitted

• liquidatedUser is the wallet that was liquidated.
• markPx is the mark price at the time of the liquidation.
• method is market for a liquidation through the book, backstop for the liquidator vault.
• The same object is on the counterparty's fill. To count each liquidation once, keep fills where the fill's address equals liquidatedUser.

3. What Hyperliquid's API returns#

The info endpoint has no request for all liquidations. You read them per wallet:

curl -s https://api.hyperliquid.xyz/info \
  -H 'Content-Type: application/json' \
  -d '{"type":"userFillsByTime","user":"0xYOUR_ADDRESS","startTime":1793000000000}' \
  | jq '[.[] | select(.liquidation != null)]'

• userFills and userFillsByTime return at most 2000 fills per response. Only the 10000 most recent fills of an address are available.
• The userEvents WebSocket sends a liquidation event for one user with liquidator, liquidated_user, liquidated_ntl_pos and liquidated_account_value.
• The userNonFundingLedgerUpdates WebSocket subscription includes liquidation entries with accountValue, leverageType and the liquidated positions.
• One IP can follow 10 unique users across user-specific WebSocket subscriptions.
• The public trades feed does not mark liquidations. A trade has coin, side, price, size, hash, time, trade id and the two users.

To see every liquidation you need every fill. A node writes them with --write-fills. The S3 archive has them in s3://hl-mainnet-node-data/node_fills_by_block. The historical data guide covers downloading it.

4. Ironflow /v1/liquidations#

Ironflow reads the liquidationfield from every fill our node writes and stores the liquidated wallet's side of each one. The endpoint covers every perp market, HIP-3 builder markets included. It works without a key: 10 requests a minute and the last 24 hours. A free key gives 60 requests a minute and 30 days.

curl -s "https://api.ironflow.sh/v1/liquidations?market=BTC-PERP&limit=1"

{
  "data": [
    {
      "market": "BTC-PERP",
      "timestamp": 1793086220460,
      "block_number": 1198880512,
      "address": "0x075b...a6d",
      "side": "buy",
      "price": "79691",
      "size": "0.001",
      "realized_pnl": "4.1467",
      "hash": "0x45d2...3138",
      "detection_method": "native"
    }
  ],
  "pagination": { "next_cursor": null, "has_more": false }
}
# trimmed: source, issuer, base_market, market_type, sequence and the fields below omitted

• Parameters: market, base_market, issuer, address, from and to in Unix milliseconds, limit up to 1000, and cursor.
• One row per fill of the liquidated wallet. Group by address and hash to count liquidation events.
• side is the side of the liquidated wallet's closing fill. sell closes a long. buy closes a short.
• Page with pagination.next_cursor while has_more is true.
• Not populated yet: account_value and margin_requirement read 0, leverage_type is empty and bankrupt is false. The response has no liquidator, mark price or method. Read those from the fill.

Liquidated notional per market over the last hour:

NOW=$(date +%s000)
curl -s "https://api.ironflow.sh/v1/liquidations?from=$((NOW - 3600000))&to=$NOW&limit=1000" \
  | jq -c '.data | group_by(.market)
      | map({market: .[0].market, fills: length, usd: (map((.price | tonumber) * (.size | tonumber)) | add | round)})
      | sort_by(-.usd) | .[:5][]'

Without from, a keyless request covers the last hour. Pass from and to for a longer range inside your history window. For one wallet, add address.

5. Live liquidation stream#

Polling /v1/liquidations for new rows works, but /v1/liquidations/stream pushes each liquidation as it lands, usually a few seconds behind the chain. It is a Server-Sent Events stream: one HTTP connection, one event per liquidation fill, in the same JSON shape as the REST rows. It needs a key. A free key works.

curl -N -H "Authorization: Bearer $IRONFLOW_KEY" \
  "https://api.ironflow.sh/v1/liquidations/stream?market=BTC,ETH&min_usd=10000"

id: 1793206626182-154
event: liquidation
data: {"market":"BTC-PERP","timestamp":1793206626182,"address":"0x075b...a6d","side":"sell","price":"79691","size":"0.5"}
# trimmed: the data line carries every field of a /v1/liquidations row

• Filters: market as a comma list of up to 50 (BTC matches BTC-PERP), address, and min_usd for price times size. Without filters you get every perp market.
• Every event has an id. Reconnect with the Last-Event-ID header, or ?last_event_id=, and the events you missed in the last 5 minutes come first. Browsers' EventSource sends the header for you.
• A : ping comment every 15 seconds keeps proxies from closing a quiet connection. After an hour the server sends event: reconnect and closes.
• A free key holds 2 streams at once. Use one stream with several markets rather than one per market.

A Python client that prints liquidations above 50,000 USD and resumes after a disconnect:

import json, os, time
import requests

URL = "https://api.ironflow.sh/v1/liquidations/stream"
headers = {"Authorization": f"Bearer {os.environ['IRONFLOW_KEY']}"}
last_id = None

while True:
    if last_id:
        headers["Last-Event-ID"] = last_id
    try:
        with requests.get(URL, headers=headers, params={"min_usd": 50000},
                          stream=True, timeout=(10, 60)) as r:
            r.raise_for_status()
            event = None
            for line in r.iter_lines(decode_unicode=True):
                if line.startswith("id: "):
                    last_id = line[4:]
                elif line.startswith("event: "):
                    event = line[7:]
                elif line.startswith("data: ") and event == "liquidation":
                    liq = json.loads(line[6:])
                    usd = float(liq["price"]) * float(liq["size"])
                    print(liq["market"], liq["side"], round(usd), liq["address"])
    except requests.RequestException:
        time.sleep(3)

6. Liquidation levels#

"Liquidation levels" means two different things. Past liquidations grouped by price show where positions were closed. Projected levels show where open positions would be closed.

Past liquidations by price#

/v1/analytics/liquidation-levels groups liquidations for one market into price buckets. It returns price_bucket, side, count and total_size, sorted by count. bucket_size is one of 1, 5, 10, 50, 100, 500, 1000 or 5000, default 100. The endpoint needs an API key; a free key works. A keyless call returns 403 with code TIER_FORBIDDEN.

curl -s "https://api.ironflow.sh/v1/analytics/liquidation-levels?market=BTC-PERP&bucket_size=500" \
  -H "Authorization: Bearer $IRONFLOW_KEY"

Without a key, the SQL endpoint answers the same question from hl.liquidations. It works keyless over the last day:

curl -s https://api.ironflow.sh/v1/query \
  -H 'Content-Type: application/json' \
  -d @- <<'EOF'
{"sql": "SELECT floor(price / 500) * 500 AS bucket, side, count() AS fills, round(sum(notional)) AS usd FROM hl.liquidations WHERE market = 'BTC-PERP' AND ts > now() - INTERVAL 1 DAY GROUP BY bucket, side ORDER BY usd DESC LIMIT 5"}
EOF

# rows from the run on 27 October 2026: bucket, side, fills, usd
[80500, "buy", 398, 2956336]
[79500, "sell", 129, 673402]
[79000, "sell", 80, 426685]

Shorts were closed between 80,500 and 81,000 for 2.96M USD that day. Longs were closed lower, between 79,000 and 80,000.

Projected liquidation prices#

clearinghouseState returns liquidationPx for each open position of one address. The formula is in the liquidations docs: liq_price = price - side * margin_available / position_size / (1 - l * side), with l = 1 / MAINTENANCE_LEVERAGE. For cross positions the price moves with funding and with PnL on the other positions.

curl -s https://api.hyperliquid.xyz/info \
  -H 'Content-Type: application/json' \
  -d '{"type":"clearinghouseState","user":"0xYOUR_ADDRESS"}' \
  | jq -c '.assetPositions[].position | {coin, szi, entryPx, liquidationPx}'

A market-wide map of projected levels needs the positions of every address. Hyperliquid has no request for that. Ironflow's API does not serve one either.

Questions#

Related guides#

• Hyperliquid historical data: API, S3 archive and Python
• Hyperliquid trades and fills data
• Hyperliquid candles and OHLCV data
• Hyperliquid funding rates: formula, history and API
• Hyperliquid order book data: L2, L4 and history
• Hyperliquid API rate limits explained

References#

• Hyperliquid docs: Liquidations. Maintenance margin, partial and backstop liquidations, the liquidation price formula.
• Hyperliquid docs: Info endpoint. userFills and userFillsByTime with their limits.
• Hyperliquid docs: Info endpoint, perpetuals. clearinghouseState and liquidationPx.
• Hyperliquid docs: WebSocket subscriptions. userEvents, the FillLiquidation and WsLiquidation types.
• Hyperliquid docs: Historical data. node_fills_by_block in the S3 archive.
• Ironflow docs: List liquidations. Parameters and fields of /v1/liquidations.
• Ironflow docs: Stream liquidations. Filters, event format and reconnects of /v1/liquidations/stream.
• Ironflow docs: Liquidation levels. Parameters of /v1/analytics/liquidation-levels.