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

> Liquidation events, open trigger-order level buckets, and volume buckets on Hyperliquid core, HIP-3, and Lighter, with wallets, size, and retry guidance.

A liquidation carries the market, price, size, side context, and venue-specific counterparty fields. Liquidation routes are available for Hyperliquid core, HIP-3, and Lighter; Spot and HIP-4 do not serve liquidation routes. Check [Venue coverage](/venue-coverage) before assuming a window per symbol.

For a focused Hyperliquid landing page with history, volume, and route context, open [Hyperliquid Liquidations Data API](/hyperliquid-liquidations-data-api).

## 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`. Liquidation levels (open trigger-order buckets): `/v1/hyperliquid/liquidations/{symbol}/levels`.
  </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` and `/levels`. 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>
</Tabs>

## Request parameters

| Parameter | In    | Type         | Required | Description                                                            |
| --------- | ----- | ------------ | -------- | ---------------------------------------------------------------------- |
| `symbol`  | path  | string       | Yes      | Trading symbol for the selected venue family, e.g. `BTC` or `km:US500` |
| `start`   | query | integer (ms) | No       | Start time, Unix ms. Defaults to 24h ago                               |
| `end`     | query | integer (ms) | No       | End time, Unix ms. Defaults to now                                     |
| `limit`   | query | integer      | No       | Max results. Default 100, max 1000                                     |
| `cursor`  | query | string       | No       | Pagination cursor (format `timestamp_tradeId`)                         |

A liquidation event returns:

```json theme={"theme":"github-dark"}
{
  "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](/venue-coverage) and Endpoint Reference before widening a job.

## Response fields

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

| Field             | Type    | Description                                               |
| ----------------- | ------- | --------------------------------------------------------- |
| `symbol`          | string  | Trading pair symbol (`coin` is a deprecated alias)        |
| `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)                           |
| `direction`       | string  | Label such as `Close Long`, `Close Short`                 |
| `trade_id`        | integer | Trade ID for this liquidation                             |
| `tx_hash`         | string  | Blockchain transaction hash                               |

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 when the workflow needs a map of currently open stop-loss and take-profit trigger orders bucketed around the mid price. These buckets are resting trigger orders, not projected forced-liquidation prices instead of an event tape. Endpoint Reference documents the exact level fields and filters.

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.

| 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                                                |
| Trigger-order cluster context                 | Hyperliquid core or HIP-3 `/levels` route                                                                                      |
| 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.

## 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 (`$8/GB`, `$25 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

Use [Trades](/rest-api/trades) for the full fill tape, [Open interest](/rest-api/open-interest) for positioning context, or [Data quality](/data-quality) before liquidations feed a model.