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

# Hyperliquid Liquidations Data API

> Hyperliquid liquidation history and real-time liquidation events by symbol over REST and WebSocket, with funding, open interest, and order book context.

0xArchive serves completed Hyperliquid liquidation events by symbol on `/v1/hyperliquid/liquidations/{symbol}`, served from 2025-12-22 00:00 UTC; symbols listed later have their own `coverage_by_type.liquidations` start. These rows are real forced executions, not estimates. Projected forced-liquidation price-level endpoints and pending TP/SL trigger concentrations are separate routes described below.

For a practical liquidation workflow, use the [Hyperliquid liquidations guide](https://0xarchive.io/resources/market-data-guides/hyperliquid-liquidations-data), then return here for the exact route contract.

```bash theme={"theme":"github-dark"}
curl "https://api.0xarchive.io/v1/hyperliquid/liquidations/BTC?start=1767225600000&end=1767312000000" \
  -H "X-API-Key: $OXARCHIVE_API_KEY"
```

```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" }
}
```

<CardGroup cols={2}>
  <Card title="Liquidations route" icon="triangle-exclamation" href="/rest-api/liquidations">
    Liquidation route family.
  </Card>

  <Card title="Hyperliquid REST" icon="chart-candlestick" href="/rest-api/hyperliquid">
    Core perp routes.
  </Card>
</CardGroup>

## What Each Row Carries

Every liquidation is a real forced execution, not an estimate, and each row names both sides of it:

| Field | What it tells you |
| - | - |
| `liquidated_user` | The wallet whose position was closed |
| `liquidator_user` | The wallet or vault on the other side of the forced fill |
| `side` | `B` (buy) or `A` (sell), the direction of the forced execution |
| `price` and `size` | Execution price and size, decimal strings |
| `mark_price` | The mark at the moment the event fired |
| `closed_pnl` | Realized PnL on the closed position |
| `direction` | Position effect, such as `Close Long` |
| `trade_id` and `tx_hash` | Join keys back to the trade tape and the chain transaction |

This route uses the `{success, data, meta}` market-data envelope, with cursor pagination through `meta.next_cursor`; preserve `meta.request_id` when the response exposes it.

## Routes And Windows

| Liquidation question | Route |
| - | - |
| Events for one symbol and window | `/v1/hyperliquid/liquidations/{symbol}` |
| Long and short volume in time buckets | `/v1/hyperliquid/liquidations/{symbol}/volume` |
| Projected forced-liquidation price-level endpoints computed from positions and margin state (snapshots about every 5 minutes) | `/v1/hyperliquid/liquidations/{symbol}/levels` |
| Pending stop-loss and take-profit trigger orders bucketed around price | `/v1/hyperliquid/orders/{symbol}/trigger-levels` |
| Everything one wallet liquidated or was liquidated for | `/v1/hyperliquid/liquidations/user/{user}` |
| HIP-3 builder markets | `/v1/hyperliquid/hip3/liquidations/{symbol}` |

Completed liquidation history is served from 2025-12-22 00:00 UTC, and symbols listed later have their own `coverage_by_type.liquidations` start. A few symbols, BTC and ETH among them, hold isolated rows from 2025-07-27 that are not served; a request that ends before 2025-12-22 returns `range_before_coverage`. For longer context, pair completed events with order-book, trade, funding, and open-interest history for the same markets, checking each data type's coverage window; the fill tape behind each event lives on [Hyperliquid Fills Data API](/hyperliquid-fills-data-api) and the book it executed against on [Hyperliquid Order Book Data API](/hyperliquid-order-book-data-api).

## Stream Liquidations Live

The `liquidations` WebSocket channel streams forced executions as they happen, with the same row shape as the REST route, so an alerting client and a historical study share one parser. Connection handling lives in the [WebSocket](/websocket) tab.

## Implementation Pattern

Pull one symbol and one UTC window of liquidations, then add order book or trade context for the same window. Liquidation routes can return valid empty pages when no events match the symbol and window; an empty page in a quiet hour is data, not an error. Check [Data quality](/data-quality) and request IDs before the output feeds a model, alert, or report, and confirm the per-symbol window on [Venue coverage](/venue-coverage) before a backtest assumes one.

## Next Step

Open [Liquidations route](/rest-api/liquidations) for the full route contract, then pair it with [Hyperliquid REST](/rest-api/hyperliquid) and [Data quality](/data-quality).


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