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

# Projected liquidation levels

> Projected forced-liquidation price levels for Hyperliquid core and HIP-3, with snapshot reads and cursor-paginated history.

Projected liquidation levels estimate where open positions may be forced to liquidate. The `/levels` family computes these estimates from clearinghouse positions and margin state, then groups them into price buckets around the snapshot mark price.

This is a separate data grain from completed liquidation events, liquidation-volume buckets, and voluntary trigger orders. The projected-level routes currently cover Hyperliquid core and HIP-3. There is no Lighter projected-level route in the OpenAPI contract.

For completed liquidation events and volume, use [Liquidations](/rest-api/liquidations). For the exact request and response contracts, use the generated operation pages below.

## Routes

| Dataset                   | Route                                                       | Endpoint Reference                                                                                                                |
| ------------------------- | ----------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
| Hyperliquid core snapshot | `/v1/hyperliquid/liquidations/{symbol}/levels`              | [Get Hyperliquid liquidation levels](/api-reference/hyperliquid--liquidations/get-hyperliquid-liquidation-levels)                 |
| Hyperliquid core history  | `/v1/hyperliquid/liquidations/{symbol}/levels/history`      | [Get Hyperliquid liquidation levels history](/api-reference/hyperliquid--liquidations/get-hyperliquid-liquidation-levels-history) |
| HIP-3 snapshot            | `/v1/hyperliquid/hip3/liquidations/{symbol}/levels`         | [Get HIP-3 liquidation levels](/api-reference/hip-3--liquidations/get-hip-3-liquidation-levels)                                   |
| HIP-3 history             | `/v1/hyperliquid/hip3/liquidations/{symbol}/levels/history` | [Get HIP-3 liquidation levels history](/api-reference/hip-3--liquidations/get-hip-3-liquidation-levels-history)                   |

## Read a snapshot

Omit `at` to receive the latest retained snapshot for a symbol. Pass `at` as epoch milliseconds to receive the newest snapshot at or before that instant. The response's `snapshot_ts` identifies the UTC snapshot that the levels reflect.

Snapshots are computed roughly every 45 minutes. That cadence describes the retained snapshot source, not a real-time liquidation-price calculation for one account or position.

<Tabs>
  <Tab title="Hyperliquid">
    ```bash theme={"theme":"github-dark"}
    curl "https://api.0xarchive.io/v1/hyperliquid/liquidations/BTC/levels?range_pct=10&buckets=50" \
      -H "X-API-Key: $OXARC...KEY"
    ```

    Use a plain perp symbol such as `BTC`.
  </Tab>

  <Tab title="HIP-3">
    ```bash theme={"theme":"github-dark"}
    curl "https://api.0xarchive.io/v1/hyperliquid/hip3/liquidations/km:US500/levels?range_pct=10&buckets=50" \
      -H "X-API-Key: $OXARC...KEY"
    ```

    Preserve the builder prefix and symbol case, for example `km:US500`.
  </Tab>
</Tabs>

## Read retained history

Use the `/history` variant to enumerate snapshots in ascending `snapshot_ts` order. The route accepts `start`, `end`, `limit`, and `cursor`. Pass `meta.next_cursor` from one response as `cursor` for the next page.

```bash theme={"theme":"github-dark"}
curl "https://api.0xarchive.io/v1/hyperliquid/liquidations/BTC/levels/history?limit=24&summary=true" \
  -H "X-API-Key: $OXARC...KEY"
```

History is retained from 2026-07-27. Set `summary=true` when you only need the snapshot timestamp, mark price, and total notional. Summary items omit the `levels` histogram, so this is the lower-payload way to discover snapshots before fetching selected histograms.

When `summary` is false or omitted, each history item includes its bucketed `levels` array. Use `range_pct`, `buckets`, and `side` to control the returned view. The generated history pages document the complete parameter and response contracts:

* [Hyperliquid liquidation levels history](/api-reference/hyperliquid--liquidations/get-hyperliquid-liquidation-levels-history)
* [HIP-3 liquidation levels history](/api-reference/hip-3--liquidations/get-hip-3-liquidation-levels-history)

## Interpret the response

The snapshot response contains the following fields:

| Field                                                | Meaning                                                                                                                                                         |
| ---------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `snapshot_ts`                                        | UTC snapshot time the levels reflect.                                                                                                                           |
| `mid_price`                                          | Mark price at the snapshot and the center of the requested range.                                                                                               |
| `block_number`                                       | Hyperliquid block height reflected by the snapshot.                                                                                                             |
| `total_long`                                         | Total long notional at risk across the whole book, not only the returned window.                                                                                |
| `total_short`                                        | Total short notional at risk across the whole book.                                                                                                             |
| `flagged_notional`                                   | Notional included in totals but computed approximately or not placed in buckets. For HIP-3, cross-margined exposure is reported here and excluded from buckets. |
| `levels[].price`                                     | Center price of one bucket.                                                                                                                                     |
| `levels[].long_notional` / `levels[].short_notional` | USD notional of long or short positions projected to liquidate in that bucket.                                                                                  |
| `levels[].long_count` / `levels[].short_count`       | Number of long or short positions in that bucket.                                                                                                               |

These projected forced-liquidation levels are aggregate bucketed estimates of forced-liquidation exposure. They are not completed liquidation events and they are not an account, wallet, or position liquidation-price endpoint.

## Shape the bucket view

The snapshot and history routes accept the same bucket controls:

| Parameter   | Behavior                                                                                                                      |
| ----------- | ----------------------------------------------------------------------------------------------------------------------------- |
| `range_pct` | Percentage range around the snapshot mark price. The contract clamps it from 1 to 50, with a default of 10.                   |
| `buckets`   | Number of price buckets. The contract clamps it from 10 to 200, with a default of 50.                                         |
| `side`      | `bid`, `buy`, or `B` keeps the long or bid side. `ask`, `sell`, or `A` keeps the short or ask side and zeroes the other side. |
| `at`        | Snapshot-only point-in-time read in epoch milliseconds. The history route does not use `at`.                                  |

Use the generated [snapshot operation page](/api-reference/hyperliquid--liquidations/get-hyperliquid-liquidation-levels) or [HIP-3 snapshot operation page](/api-reference/hip-3--liquidations/get-hip-3-liquidation-levels) for the schema, examples, and validation details.

## Keep liquidation data grains separate

| If you need                            | Use                                                                                                                                                                               | Grain                                                                |
| -------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------- |
| Completed forced executions            | [Liquidation event routes](/rest-api/liquidations)                                                                                                                                | One observed liquidation-related event row                           |
| Aggregated liquidation activity        | [Liquidation volume routes](/rest-api/liquidations)                                                                                                                               | One time bucket with volume and counts                               |
| Projected forced-liquidation exposure  | The snapshot or history routes on this page                                                                                                                                       | One retained position-and-margin snapshot with price buckets         |
| Voluntary trigger-order concentrations | [Hyperliquid trigger levels](/api-reference/hyperliquid--orders/get-hyperliquid-trigger-levels) and [HIP-3 trigger levels](/api-reference/hip-3--orders/get-hip-3-trigger-levels) | Pending stop-loss and take-profit orders grouped near the mark price |

Trigger levels are voluntary orders, not projected forced liquidations. Their history uses a separate route family and cadence. See [Order flow](/rest-api/order-flow) for the surrounding order-event routes, or open the generated [Hyperliquid trigger-level history](/api-reference/hyperliquid--orders/get-hyperliquid-trigger-levels-history) and [HIP-3 trigger-level history](/api-reference/hip-3--orders/get-hip-3-trigger-levels-history) pages.

## Next

Use [Liquidations](/rest-api/liquidations) for observed event rows and volume buckets, [Open interest](/rest-api/open-interest) for positioning context, or [Venue coverage](/venue-coverage) before widening a symbol window.