Skip to main content
A liquidation carries both wallets, the price and size, and the realized PnL. Liquidation routes are Hyperliquid core and HIP-3 today; Spot, HIP-4, and Lighter do not serve liquidations the same way. Check Venue Coverage before assuming a window per symbol.

​
Get liquidations

curl "https://api.0xarchive.io/v1/hyperliquid/liquidations/BTC?limit=1" \
  -H "X-API-Key: $OXARCHIVE_API_KEY"
Events: /v1/hyperliquid/liquidations/{symbol}. Volume buckets: /v1/hyperliquid/liquidations/{symbol}/volume.

​
Request parameters

ParameterInTypeRequiredDescription
symbolpathstringYesTrading pair symbol, e.g. BTC
startqueryinteger (ms)NoStart time, Unix ms. Defaults to 24h ago
endqueryinteger (ms)NoEnd time, Unix ms. Defaults to now
limitqueryintegerNoMax results. Default 100, max 1000
cursorquerystringNoPagination cursor (format timestamp_tradeId)
A liquidation event returns: 
{
  "success": true,
  "data": [
    {
      "coin": "BTC",
      "timestamp": "2026-06-04T14:00:02.429Z",
      "liquidated_user": "0x32fe14732b5b54dc08c6eee46b9ba319ca38e9f4",
      "liquidator_user": "0xd4bb18ef8d1bc1bfadfcc034ca69628b58b42a4c",
      "side": "A",
      "price": "64234",
      "size": "0.03929",
      "mark_price": "64215",
      "closed_pnl": "15.719929",
      "direction": "Close Long",
      "trade_id": 77865977922623,
      "tx_hash": "0x0bf847b31c71cf920d72043d23653902065a0098b774ee64afc0f305db75a97c"
    }
  ],
  "meta": { "count": 1, "next_cursor": "1780581602429_228090607300425", "request_id": "req_9f1c0a7e5b2d4480" }
}
Hyperliquid liquidation history starts December 2025; confirm the window per symbol on Venue Coverage.

​
Response fields

Each item in the data array:
FieldTypeDescription
symbolstringTrading pair symbol (coin is a deprecated alias)
timestampstringLiquidation time (UTC)
liquidated_userstringWallet that was liquidated
liquidator_userstringLiquidator (counterparty) wallet
pricestringPrice the liquidation executed at
sizestringSize of the liquidated position
sidestringVenue side code (A/B); use direction for close/open
mark_pricestringMark price at liquidation
closed_pnlstringRealized PnL (usually negative)
directionstringLabel such as Close Long, Close Short
trade_idintegerTrade ID for this liquidation
tx_hashstringBlockchain transaction hash

​
Raw events vs volume

Use raw liquidation event routes (/v1/hyperliquid/liquidations/{symbol} or /v1/hyperliquid/hip3/liquidations/{symbol}) when you need event-level records for audit, replay, or model input. They are heavier and may need pagination, tighter windows, and lower concurrency. Use /volume (/v1/hyperliquid/liquidations/{symbol}/volume?interval=1h) when you need aggregate liquidation-volume buckets for dashboards or backtests that don’t inspect every event. Each bucket returns total_usd, long_usd, short_usd, count, long_count, and short_count. For high-volume dashboards and repeated backtests, start with /volume and keep raw event pulls as a narrower drill-down. For liquidation routes that return 429, honor Retry-After when present; if it is absent, use capped exponential backoff with jitter, reduce concurrency, and keep meta.request_id or x-request-id for the failed attempts. Don’t retry unchanged after auth, access, malformed-request, or unsupported-symbol errors. Fix the request or key first.

​
Next call after a 429

When a raw liquidation route rate-limits, choose the next call from the workflow instead of replaying the same request.
WorkflowSafer next call
Dashboard, scan, or repeated backtest summary/v1/hyperliquid/liquidations/{symbol}/volume?interval=1h or the matching HIP-3 /volume route
Event-level audit or model inputSame raw route with a smaller window, lower concurrency, and request-ID logging
Unclear venue familyCheck Venue Coverage before switching between core and HIP-3
Keep the failed path, the Retry-After value when present, meta.request_id or x-request-id, and the chosen next call in the job log so the retry decision is reviewable later.

​
Stream it live

Liquidations stream on Hyperliquid core (liquidations) and HIP-3 (hip3_liquidations) only, matching the REST coverage. Spot, HIP-4, and Lighter do not serve a liquidation stream. 
ws.send(JSON.stringify({ op: "subscribe", channel: "liquidations", symbol: "BTC" }));
Connection and reconnect handling live in the WebSocket tab; see WebSocket Channels for the family matrix.

​
Export in bulk

For event-level liquidation history as files, use the liquidations export schema ($8/GB, $25 minimum), delivered as Parquet with ZSTD compression. Build a selection in the Data Catalog; columns and coverage keys are on Export Schemas.

​
Next

Use Trades for the full fill tape, Open interest for positioning context, or Data Quality before liquidations feed a model.
Last modified on June 8, 2026