Get liquidations
- Hyperliquid
- HIP-3
- Lighter
/v1/hyperliquid/liquidations/{symbol}. Volume buckets: /v1/hyperliquid/liquidations/{symbol}/volume.Request parameters
The
/volume routes add interval with 5m, 15m, 30m, 1h, 4h, or 1d. Lighter and HIP-3 volume routes default to 1h; the core route does not publish an interval default, so pass it explicitly. Core and Lighter volume routes default to a limit of 100 (maximum 1000); HIP-3 volume defaults to a limit of 1000 (maximum 1000), and requires start. Volume cursors are route-specific strings; pass the returned value unchanged.
A liquidation event returns:
/v1/hyperliquid/liquidations/{symbol}; other symbols have their own coverage_by_type.liquidations start. Confirm the window per symbol on Venue coverage and Endpoint Reference before widening a job. Use Projected liquidation levels for the separate forced-liquidation estimate family.
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 the canonical
symbol plus the deprecated coin alias, 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 those fields conditionally across Hyperliquid core and HIP-3. Spot and HIP-4 do not publish a liquidation route; Lighter uses the separate schema below.
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.
For projected forced-liquidation levels, snapshot cadence, snapshot_ts, history pagination, and the distinction from voluntary trigger orders, use Projected liquidation levels. That page links the core and HIP-3 generated operation references.
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 ($4/GB, $12.50 minimum), delivered as Parquet with ZSTD compression. Build a selection in the Data catalog; columns and coverage keys are on Export schemas.