> ## Documentation Index
> Fetch the complete documentation index at: https://docs.0xarchive.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Liquidations

> Completed liquidation events and volume buckets on Hyperliquid core, HIP-3, and Lighter, with wallets, size, and retry guidance.

Pull completed liquidation events, or liquidation volume in time buckets, on Hyperliquid core, HIP-3, Lighter, and Lighter on Robinhood Chain. Each event carries the market, price, size, side context, and venue-specific counterparty fields. Spot and HIP-4 have no liquidation routes.

Start dates differ by symbol, so check [Venue coverage](/venue-coverage) for the window you need. [Liquidation events by symbol](/hyperliquid-liquidations-data-api) covers Hyperliquid event history in more depth, and [Projected liquidation levels](/rest-api/liquidation-levels) covers forced-liquidation price estimates, a separate dataset. For positioning context, pair liquidations with [Open interest](/rest-api/open-interest).

## Get liquidations

<Tabs>
  <Tab title="Hyperliquid">
    ```bash theme={"theme":"github-dark"}
    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`.
  </Tab>

  <Tab title="HIP-3">
    ```bash theme={"theme":"github-dark"}
    curl "https://api.0xarchive.io/v1/hyperliquid/hip3/liquidations/km:US500?limit=1" \
      -H "X-API-Key: $OXARCHIVE_API_KEY"
    ```

    Events: `/v1/hyperliquid/hip3/liquidations/{symbol}` plus `/volume`. Namespaced builder symbols, case-sensitive (for example `km:US500`).
  </Tab>

  <Tab title="Lighter">
    ```bash theme={"theme":"github-dark"}
    curl "https://api.0xarchive.io/v1/lighter/liquidations/BTC?limit=1" \
      -H "X-API-Key: $OXARCHIVE_API_KEY"
    ```

    Events: `/v1/lighter/liquidations/{symbol}`. Volume buckets: `/v1/lighter/liquidations/{symbol}/volume`.
  </Tab>

  <Tab title="Lighter on Robinhood Chain">
    ```bash theme={"theme":"github-dark"}
    curl "https://api.0xarchive.io/v1/rh-lighter/liquidations/BTC?limit=1" \
      -H "X-API-Key: $OXARCHIVE_API_KEY"
    ```

    Events: `/v1/rh-lighter/liquidations/{symbol}`. Volume buckets: `/v1/rh-lighter/liquidations/{symbol}/volume`. History from 2026-06-26 20:10:26 UTC. Rows from before live capture began on 2026-08-22 were backfilled from the venue's finalized export and carry `source: "bucket"` and an empty `raw_json`; live-captured rows carry `source: "ws"` and the venue's raw JSON.
  </Tab>
</Tabs>

## Request parameters

| Parameter | Description |
| - | - |
| `symbol` | Path, required, string. Trading symbol for the selected venue family, e.g. `BTC` or `km:US500` |
| `start` | Query, optional, integer (ms) or string. Start time, Unix ms or RFC 3339. Defaults are route-specific; see the operation page. |
| `end` | Query, optional, integer (ms) or string. End time, Unix ms or RFC 3339. Defaults to now where documented; see the operation page. |
| `limit` | Query, optional, integer. Max results. Core and Lighter event routes default to 100; HIP-3 event routes default to 1000. Maximum 1000 for all event routes. |
| `cursor` | Query, optional, string. Pagination cursor. Hyperliquid cursors use the `timestamp_tradeId` form; pass the returned value unchanged. |

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:

```json theme={"theme":"github-dark"}
{
  "success": true,
  "data": [
    {
      "symbol": "BTC",
      "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": "ffffffff-ffff-4fff-8fff-ffffffffffff" }
}
```

Hyperliquid liquidation events on `/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](/venue-coverage) and in the Endpoint Reference before widening a job, and check it with [Data quality](/data-quality) before liquidations feed a model. Use [Projected liquidation levels](/rest-api/liquidation-levels) for the separate forced-liquidation estimate family.

## Response fields

Hyperliquid core and HIP-3 items in the `data` array:

| Field | Description |
| - | - |
| `symbol` | String. Canonical market symbol for the liquidation; use it for routing and storage |
| `coin` | String. Deprecated market-symbol alias returned alongside `symbol` |
| `timestamp` | String. Liquidation time (UTC) |
| `liquidated_user` | String. Wallet that was liquidated |
| `liquidator_user` | String. Liquidator (counterparty) wallet |
| `price` | String. Price the liquidation executed at |
| `size` | String. Size of the liquidated position |
| `side` | String. Venue side code (`A`/`B`); use `direction` for close/open |
| `mark_price` | String. Mark price at liquidation |
| `closed_pnl` | String. Realized PnL (usually negative); conditional, omitted when null |
| `direction` | String. Label such as `Close Long`, `Close Short` |
| `trade_id` | Integer. Trade ID for this liquidation |
| `tx_hash` | String. Blockchain transaction hash; conditional, omitted when null |

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](/rest-api/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 its `meta.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:

| Workflow | Safer next call |
| - | - |
| Dashboard, scan, or repeated backtest summary | `/v1/hyperliquid/liquidations/{symbol}/volume?interval=1h`, the matching HIP-3 `/volume` route, or the Lighter `/volume` route |
| Event-level audit or model input | Same raw route with a smaller window, lower concurrency, and request-ID logging |
| Projected liquidation-level context | [Projected liquidation levels](/rest-api/liquidation-levels) |
| Trigger-order cluster context | `/v1/hyperliquid/orders/{symbol}/trigger-levels` or the HIP-3 equivalent |
| Unclear venue family | Check [Venue coverage](/venue-coverage) before switching between core, HIP-3, and Lighter |

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 from [`GET /v1/capabilities`](/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](/conventions).

| Venue and data type | Availability |
| - | - |
| Hyperliquid: Liquidations | From 2025-12-22<br />WebSocket `liquidations`: live and replay<br />Up to 1,000 rows a page<br />Older rows exist but are not served; available\_from is a policy floor. |
| Hyperliquid: Liquidations by user | From 2025-12-22<br />REST only, no WebSocket channel<br />Up to 1,000 rows a page<br />Older rows exist but are not served; available\_from is a policy floor. |
| HIP-3: Liquidations | From 2025-12-22<br />WebSocket `hip3_liquidations`: live and replay<br />Up to 1,000 rows a page |
| Lighter: Liquidations | From 2026-06-10<br />REST only, no WebSocket channel<br />Up to 1,000 rows a page<br />Older rows exist but are not served; available\_from is a policy floor. |
| Lighter on Robinhood Chain: Liquidations | From 2026-06-26 20:10 UTC<br />REST only, no WebSocket channel<br />Up to 1,000 rows a page |

| Surface | Names |
| - | - |
| Python SDK | `client.hyperliquid.liquidations.history(symbol, ...)`, `.volume(...)`, `.by_user(user, ...)` |
| TypeScript SDK | `client.hyperliquid.liquidations.history(symbol, ...)`, `.volume(...)`, `.byUser(user, ...)` |
| Rust SDK | `client.hyperliquid.liquidations.history`, `.volume`, `.by_user` |
| CLI | `oxa liquidations history`, `oxa liquidations volume`, `oxa liquidations user` |
| MCP tools | `get_liquidations`, `get_liquidation_volume`, `get_liquidations_by_user`, `get_hip3_liquidations`, `get_hip3_liquidation_volume`, `get_lighter_liquidations`, `get_lighter_liquidation_volume`, `get_rh_lighter_liquidations`, `get_rh_lighter_liquidation_volume` |

## 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.

```javascript theme={"theme":"github-dark"}
ws.send(JSON.stringify({ op: "subscribe", channel: "liquidations", symbol: "BTC" }));
```

Connection and reconnect handling live in the [WebSocket](/websocket) tab; see [WebSocket channels](/websocket/channels) for the family matrix.

## Export in bulk

For event-level liquidation history as files, use the `liquidations` export schema (`$4/GB`, `$12.50 minimum`), delivered as Parquet with ZSTD compression. Build a selection in the [Data Catalog](/data-catalog); columns and coverage keys are on [Export schemas](/export-schemas).

## Next step

For the full fill tape around these events, continue to [Trades](/rest-api/trades).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.