Hyperliquid Liquidation Data: What the Candle Hides

OHLCV shows the wick. Completed liquidation data shows the forced flow behind it. 0xArchive serves completed Hyperliquid liquidation events by symbol, with the execution price, size, side context, mark price, direction, and counterparty fields needed to study a cascade.

Completed Hyperliquid liquidation-event history starts on July 27, 2025 for the earliest covered symbols. Other symbols have different liquidation-history start dates. Check the symbol before widening a window.

Pull completed events

curl "https://api.0xarchive.io/v1/hyperliquid/liquidations/BTC?limit=1" \
  -H "X-API-Key: $OXARCHIVE_API_KEY"

One response row is a completed forced execution, not an estimate. A representative envelope looks like this. Wallets, cursors, and request IDs are shortened here.

{
  "success": true,
  "data": [
    {
      "coin": "BTC",
      "timestamp": "2026-06-04T14:00:02.429Z",
      "liquidated_user": "0xREDACTED",
      "liquidator_user": "0xREDACTED",
      "side": "A",
      "price": "64234",
      "size": "0.03929",
      "mark_price": "64215",
      "closed_pnl": "15.719929",
      "direction": "Close Long",
      "trade_id": 77865977922623,
      "tx_hash": "0xREDACTED"
    }
  ],
  "meta": { "count": 1, "next_cursor": "cursor_redacted", "request_id": "req_redacted" }
}

Keep the three level concepts separate

Surface	Meaning	Route
Completed liquidation events	Real forced executions with execution price, size, and direction	/v1/hyperliquid/liquidations/{symbol}
Projected forced-liquidation price-level endpoints	Estimated price levels derived from positions and margin state at a snapshot	/v1/hyperliquid/liquidations/{symbol}/levels
Pending take-profit and stop-loss trigger-order concentrations	Voluntary TP/SL trigger-order size bucketed around price	/v1/hyperliquid/orders/{symbol}/trigger-levels
Heatmap visualization	A visual aggregation of completed events, separate from projected levels	Liquidation heatmap

/liquidations/{symbol}/levels is not a completed-event feed. /orders/{symbol}/trigger-levels is not a forced-liquidation estimate. Keep both outside a completed-event table.

Read the fields

• direction tells you which position effect occurred, such as Close Long or Close Short.
• price and size describe the forced execution. mark_price gives the reference mark beside the fill.
• liquidated_user and liquidator_user preserve the two sides of the forced fill.
• trade_id and tx_hash can join the event to the trade tape or chain record when present.
• meta.next_cursor and meta.request_id belong in the stored page manifest.

Analyze a bounded cascade

import collections
import os
import requests

BASE = "https://api.0xarchive.io"
URL = f"{BASE}/v1/hyperliquid/liquidations/BTC"
headers = {"X-API-Key": os.environ["OXARCHIVE_API_KEY"]}
params = {"limit": 100}
rows = []
seen = set()
request_ids = []

for _ in range(5):
    response = requests.get(URL, headers=headers, params=params, timeout=30)
    response.raise_for_status()
    page = response.json()
    rows.extend(page.get("data", []))
    request_id = (page.get("meta") or {}).get("request_id")
    if request_id:
        request_ids.append(request_id)
    cursor = (page.get("meta") or {}).get("next_cursor")
    if not cursor:
        break
    if cursor in seen:
        raise RuntimeError("cursor repeated")
    seen.add(cursor)
    params["cursor"] = cursor

by_direction = collections.Counter(row.get("direction") for row in rows)
notional = sum(float(row["price"]) * float(row["size"]) for row in rows if row.get("price") and row.get("size"))
mark_gaps = [
    float(row["price"]) - float(row["mark_price"])
    for row in rows
    if row.get("price") and row.get("mark_price")
]
print({
    "rows": len(rows),
    "request_ids": len(request_ids),
    "direction_counts": dict(by_direction),
    "forced_notional": notional,
    "fill_minus_mark_samples": len(mark_gaps),
})

Bucket the returned rows by UTC interval and price when you need a cascade view. Keep the raw event rows beside the aggregate so a cluster can be audited back to the fills that formed it.

Context for the move

Pair completed events with the order book, trades, funding, and open interest for the same symbol and UTC window. A liquidation event tells you what was forced. Depth shows the liquidity available to absorb it. Funding and open interest describe the positioning regime. None of those context series turns a projected level or pending trigger into a completed fill.

Use the Hyperliquid Liquidations Data API for the focused route overview and the Liquidations reference for event, volume, projected-level, and trigger-level contracts. The TP/SL reference explains trigger lifecycle rows. Check venue coverage before assuming a symbol window.

Related data

Use the Hyperliquid order-book guide for the depth that absorbed the event and the Hyperliquid data API for product scope. Check the data catalog, pricing, and status before a long pull. The heatmap example stays separate as a visualization of completed events.