Hyperliquid historical liquidations API

Hyperliquid's info API has no liquidations request. Liquidations are marked on fills, and the API returns fills one wallet at a time. Ironflow's GET /v1/liquidations returns every liquidation on every perp market since 25 May 2025, with no key for the last 24 hours.

API

GET https://api.ironflow.sh/v1/liquidations?market=BTC-PERP no key

MCP

get_liquidations on https://mcp.ironflow.sh/mcp

FILE

huggingface.co/datasets/ironflow/hyperliquid-liquidations free

The short version#

• Hyperliquid: no liquidations request. Per wallet only, through fills, capped at the 10,000 most recent.
• Every wallet, any window: /v1/liquidations over REST, hl.liquidations in SQL, get_liquidations over MCP.
• Everything at once: a free Parquet file per month, 25 May 2025 to 31 October 2026.

The numbers#

From our own nodes and Hyperliquid's fills archive. Each row is a fill Hyperliquid marked as a liquidation, counted once per liquidated position. Live totals are on the liquidations page.

What Hyperliquid's API has#

• No request: none of the requests on its info endpoint pages returns liquidations. On testnet, {"type": "liquidations"} answers HTTP 422, Failed to deserialize the JSON body into the target type.
• On fills: a liquidation fill has a liquidation field with liquidatedUser, markPx and method (WsFill). userFills and userFillsByTime return them for one wallet, at most its 10,000 most recent fills.
• Live: the userEvents WebSocket pushes liquidations for wallets you subscribe to, one wallet per subscription.
• Archive: node_fills_by_block in the requester-pays S3 bucket has every fill (historical data). You download, decompress and filter it yourself.

Every liquidation over REST#

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

{
  "data": [
    { "market": "BTC-PERP", "timestamp": 1794432775060, "block_number": 1217802798,
      "address": "0xa615...7fd9", "side": "buy", "price": "74712", "size": "0.00043",
      "realized_pnl": "-0.36249", "detection_method": "native", ... },
    ...
  ],
  "pagination": { "next_cursor": "MTc5NDQzMjgwNTAxMy0yMTQ=", "has_more": true },
  "poll_cursor": "MTc5NDQzMjgwNTAxMy0yMTQ=",
  "complete_until": 1794518415314
}

Rows come oldest first. Page with cursor, or poll for new rows with after=poll_cursor. This pulls a window and adds up the dollars:

import os
import time

import pandas as pd
import requests

KEY = os.environ.get("IRONFLOW_KEY")  # optional
headers = {"Authorization": f"Bearer {KEY}"} if KEY else {}
params = {"market": "BTC-PERP", "from": "-24h", "limit": 1000}  # "-14d" with a free key

rows = []
while True:
    r = requests.get("https://api.ironflow.sh/v1/liquidations", params=params, headers=headers, timeout=30)
    if r.status_code == 429:
        time.sleep(int(r.headers.get("Retry-After", 5)))
        continue
    r.raise_for_status()
    body = r.json()
    rows += body["data"]
    if not body["pagination"]["has_more"]:
        break
    params["cursor"] = body["pagination"]["next_cursor"]

df = pd.DataFrame(rows)
df["usd"] = df["price"].astype(float) * df["size"].astype(float)
print(len(df), "BTC liquidation fills,", round(df["usd"].sum() / 1e6, 1), "million USD")

Keyless on 12 November 2026 it printed 8070 BTC liquidation fills, 117.6 million USD.

• market takes one market or up to 50 (BTC-PERP,ETH-PERP). Leave it out for every market. address filters one wallet.
• Without a key, rows run 60 seconds behind live. A free key reads them live.
• Endpoint reference: list liquidations.

Full history as a download#

One Parquet file per month on Hugging Face, no key. events has one row per liquidated position, fills one per fill. About 115 MB for all of events:

import pandas as pd

URL = "https://huggingface.co/datasets/ironflow/hyperliquid-liquidations/resolve/main/data/events/{}.parquet"
months = pd.period_range("2025-05", "2026-10", freq="M").strftime("%Y-%m")
events = pd.concat(pd.read_parquet(URL.format(m)) for m in months)

print(len(events), "liquidations,", round(events.notional_usd.sum() / 1e9, 1), "billion USD")
print(events.nlargest(5, "notional_usd")[["timestamp", "market", "position_side", "notional_usd"]])

2849452 liquidations, 58.7 billion USD
                           timestamp    market position_side  notional_usd
151899 2026-01-31 18:43:52.514+00:00  ETH-PERP          long  2.191728e+08
101307 2025-10-10 21:17:06.037+00:00  ETH-PERP          long  2.046711e+08
109987 2025-10-10 21:17:47.450+00:00  BTC-PERP          long  1.971612e+08
1551   2025-05-27 01:23:43.322+00:00  BTC-PERP          long  1.548190e+08
101447 2025-10-10 21:17:06.037+00:00  SOL-PERP          long  1.254634e+08

SQL#

Read-only ClickHouse SQL over hl.liquidations, the same rows. No key covers the last day:

curl -X POST https://api.ironflow.sh/v1/query \
  -H "Content-Type: application/json" \
  -d '{"sql": "SELECT market, count() AS fills, round(sum(notional)) AS usd FROM hl.liquidations WHERE ts > now() - INTERVAL 1 DAY GROUP BY market ORDER BY usd DESC LIMIT 3"}'

On 12 November 2026 BTC-PERP led with $116.7 million, then the xyz:NVDA-PERP stock perp with $36.0 million. More queries are in the SQL guide.

How far back by plan#

Questions#

Related guides#

• Hyperliquid liquidation data: history, live feed, levels and API
• How to read the Hyperliquid liquidation map, and how it's built
• Hyperliquid userFills limit: get more than 10,000 fills
• Hyperliquid data sources compared

References#

• Hyperliquid docs: Info endpoint. Every request type, and the userFills limits.
• Hyperliquid docs: WebSocket subscriptions. WsFill and its liquidation field.
• Hyperliquid docs: Historical data. The S3 buckets and node_fills_by_block.
• Hugging Face: ironflow/hyperliquid-liquidations. The free monthly files.