Get liquidations
- Hyperliquid
- HIP-3
- Lighter
- Lighter on Robinhood Chain
/v1/hyperliquid/liquidations/{symbol}. Volume buckets: /v1/hyperliquid/liquidations/{symbol}/volume.Request parameters
The
/volume routes add interval with 1m, 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.
Example response
A liquidation event returns:/v1/hyperliquid/liquidations/{symbol} are served from 2025-12-22 00:00 UTC; symbols listed later start on their own coverage_by_type.liquidations date. A few symbols, BTC and ETH among them, hold isolated rows from 2025-07-27 that are not served, and a request that ends before 2025-12-22 returns range_before_coverage. Confirm the window per symbol on Venue coverage and in the Endpoint Reference before widening a job, and check it with Data quality before liquidations feed a model. 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 Lighter’s own schema, including fields such as liquidation_type, usd_amount, ask_account, bid_account, ask_order_id, and bid_order_id.
Raw events or volume buckets
Use raw liquidation event routes (/v1/hyperliquid/liquidations/{symbol}, /v1/hyperliquid/hip3/liquidations/{symbol}, or /v1/lighter/liquidations/{symbol}) when you need row-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. Each bucket returns volume and count fields for the selected venue family.
Budget a job by what it reads. A dashboard refresh, a repeated backtest scan, or a broad loop over symbols that only needs aggregate exposure should start with /v1/hyperliquid/liquidations/{symbol}/volume?interval=1h or the matching HIP-3 /volume route, then pull raw events only for the symbols and windows that need audit-level detail.
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 operation references.
When a liquidation route returns 429
Stop widening the job. Log the failed path and itsmeta.request_id or x-request-id, honor Retry-After when present, and otherwise use capped exponential backoff with jitter and lower concurrency. Then retry with a narrower window, or switch to the /volume route when buckets answer the question. Don’t retry unchanged after auth, access, malformed-request, or unsupported-symbol errors; fix the request or key first.
Choose the next call from the job 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.
Access
Each venue’s start date, WebSocket channels, and page limit come fromGET /v1/capabilities, followed by the SDK, CLI, and MCP names for the same data. The start date is the first served row on that venue; exact starts vary by market, so check /v1/symbols for a single symbol. Send 0xArchive-Version: 2026-10-01 for the current response contract; see API conventions.
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.