Get liquidations
- Hyperliquid
- HIP-3
- Lighter
/v1/hyperliquid/liquidations/{symbol}. Volume buckets: /v1/hyperliquid/liquidations/{symbol}/volume. Projected liquidation levels: /v1/hyperliquid/liquidations/{symbol}/levels (plus /levels/history).Request parameters
A liquidation event returns:
/v1/hyperliquid/liquidations/{symbol}; other symbols have their own coverage_by_type.liquidations start. Use /v1/hyperliquid/liquidations/{symbol}/levels for projected forced-liquidation price-level endpoints derived from positions and margin state, not completed events. Use /v1/hyperliquid/orders/{symbol}/trigger-levels for pending TP/SL trigger-order concentrations. These are separate route families. Confirm the window per symbol on Venue coverage and Endpoint Reference before widening a job.
Response fields
Hyperliquid core and HIP-3 items in thedata array:
The example above is a Hyperliquid core event. HIP-3 events return the same shape minus the enrichment: rows carry
coin, timestamp, liquidated_user, liquidator_user, price, size, side, mark_price, direction, and trade_id, while closed_pnl and tx_hash are omitted when null, which on HIP-3 is the common case. Model both as conditional fields on every venue family.
Lighter liquidation events use the Lighter-generated schema, including fields such as liquidation_type, usd_amount, ask_account, bid_account, ask_order_id, and bid_order_id.
Raw events vs volume
Use raw liquidation event routes (/v1/hyperliquid/liquidations/{symbol}, /v1/hyperliquid/hip3/liquidations/{symbol}, or /v1/lighter/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, the matching HIP-3 route, or /v1/lighter/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 volume and count fields for the selected venue family. For high-volume dashboards and repeated backtests, start with /volume and keep raw event pulls as a narrower drill-down.
Use /levels on Hyperliquid core or HIP-3 for the projected price-level endpoint family: aggregate estimates of where open positions may liquidate, computed from clearinghouse positions and margin state and bucketed around the snapshot mark price. These projected forced-liquidation levels are aggregate bucketed estimates, not an account, wallet, or position liquidation-price endpoint. They are distinct from voluntary trigger orders. Snapshots refresh roughly every 45 minutes; the response’s snapshot_ts identifies the snapshot served, and ?at= (epoch ms) serves a point-in-time read. /levels/history pages through retained snapshots with cursor pagination (summary=true lists snapshots without histograms). History is retained from 2026-07-27. Endpoint Reference documents the exact level fields and filters.
Before 2026-07-27 the /levels path served a map of pending stop-loss and take-profit trigger orders. That map now lives at /v1/hyperliquid/orders/{symbol}/trigger-levels (and the HIP-3 equivalent) with its own /history route; see Order flow and Endpoint Reference. Trigger orders are voluntary orders, not projected forced liquidations; the two families are separate endpoints.
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.
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). Lighter liquidations are documented as REST routes; Spot and HIP-4 do not serve liquidation routes.
Export in bulk
For event-level liquidation history as files, use theliquidations 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.