> ## 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 on Hyperliquid core and HIP-3 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.

These levels are 0xArchive model estimates. Hyperliquid does not publish them. Each snapshot is computed close to real time from the data available at its `snapshot_ts`; see [Timing and provenance](#timing-and-provenance).

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). The operation pages linked below carry each route's request and response schema, and [Venue coverage](/venue-coverage) lists each symbol's window.

## Routes

| Dataset | Route and 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) |

## Get projected levels

Omit `at` to receive the latest retained snapshot for a symbol. Pass `at` as epoch milliseconds to receive the newest snapshot whose `snapshot_ts` is at or before that instant. `snapshot_ts` is when the snapshot was computed; `block_number` identifies the earlier exchange state it started from.

Since 2026-08-13, snapshots are computed roughly every 5 minutes; earlier history is about 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=1&buckets=10" \
      -H "X-API-Key: $OXARCHIVE_API_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/xyz:TSLA/levels?range_pct=1&buckets=10" \
      -H "X-API-Key: $OXARCHIVE_API_KEY"
    ```

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

## Request parameters

| Parameter | Behavior |
| - | - |
| `symbol` | Snapshot and history, required, string. Plain core symbol such as `BTC`, or a case-sensitive HIP-3 builder symbol such as `xyz:TSLA` |
| `range_pct` | Snapshot and history, optional, number. Percentage range around the snapshot mark price. Clamped from 1 to 50; default 10 |
| `buckets` | Snapshot and history, optional, integer. Number of price buckets. Clamped from 10 to 200; default 50 |
| `side` | Snapshot and history, optional, string. `bid`, `buy`, or `B` keeps long exposure. `ask`, `sell`, or `A` keeps short exposure. The other side is zeroed |
| `at` | Snapshot only, optional, integer (ms) or string. Return the newest snapshot at or before this Unix epoch-millisecond or RFC 3339 instant. Omit for latest |
| `start` | History only, optional, integer (ms) or string. Inclusive window start. Defaults to 24 hours before the resolved `end` value |
| `end` | History only, optional, integer (ms) or string. Inclusive window end. Defaults to the current time |
| `limit` | History only, optional, integer. Snapshots per page. Default 24; clamped from 1 to 100 |
| `cursor` | History only, optional, string (epoch ms). Exclusive `snapshot_ts` value returned in `meta.next_cursor`; pass it unchanged to read the next page |
| `summary` | History only, optional, boolean. When `true`, remove only the `levels` histogram. Snapshot time, block number, mark price, totals, and flagged notional remain |

An `at` value before retained history returns `404`. A history window with no matching snapshots returns `200` with an empty `data` array, whether the window is before retained coverage or simply contains no snapshot for that symbol. An empty page means no retained snapshot matched the request; it does not mean projected exposure was zero. Invalid side values, malformed cursors, and history windows where `start` is after `end` return validation errors.

## Example response

Representative, abridged Hyperliquid core snapshot for `range_pct=1&buckets=10` from the `source: "raw"` response form. The full response contains the requested ten buckets; eight are omitted below, and the request ID is synthetic.

```json theme={"theme":"github-dark"}
{
  "success": true,
  "data": {
    "mid_price": 64234.0,
    "snapshot_ts": "2026-08-06 13:20:14.000",
    "block_number": 1100170000,
    "total_long": 826442891.0,
    "total_short": 940536199.24,
    "flagged_notional": 121607711.81,
    "levels": [
      {
        "price": 63655.89,
        "long_notional": 7411401.14,
        "short_notional": 0.0,
        "long_count": 190,
        "short_count": 0
      },
      {
        "price": 64298.23,
        "long_notional": 0.0,
        "short_notional": 64234.0,
        "long_count": 0,
        "short_count": 1
      }
    ],
    "source": "raw"
  },
  "meta": {
    "count": 10,
    "request_id": "a1b2c3d4-e5f6-4789-8abc-def012345678"
  }
}
```

## Response fields

Responses use the `{ success, data, meta }` envelope. The projected-level fields are inside `data`.

| Field | Meaning |
| - | - |
| `mid_price` | Number. Mark price used for the snapshot and the center of the requested range |
| `snapshot_ts` | String. UTC time the snapshot was computed. See [Timing and provenance](#timing-and-provenance) |
| `block_number` | Integer. Hyperliquid block of the exchange-state snapshot the computation started from. Since 2026-08-13 it is typically 30 to 65 minutes older than `snapshot_ts` |
| `total_long` | Number. Total long notional at risk across the whole book, not only the returned range |
| `total_short` | Number. Total short notional at risk across the whole book |
| `flagged_notional` | Number. Notional included in totals but computed approximately or not assigned to a returned bucket. For HIP-3, cross-margined exposure is reported here and excluded from buckets |
| `levels[].price` | Number. Center price of one bucket |
| `levels[].long_notional` / `levels[].short_notional` | Number. USD notional of long or short positions projected to liquidate in that bucket |
| `levels[].long_count` / `levels[].short_count` | Integer. Number of long or short positions in that bucket |
| `source` | String. Snapshot responses only. `raw` means query-time bins over stored fine-grained levels; `histogram` means a retained base histogram re-binned to the request |
| `source_bin_width` | Number. Snapshot responses only, and present only when `source` is `histogram`; stored source-bin width in price units |
| `meta.count` | Integer. Number of buckets in a snapshot response, or snapshots in a history page |
| `meta.next_cursor` | String or null. Continuation cursor on history responses when another page may exist |
| `meta.request_id` | String. Request identifier to retain for support and retry diagnostics |

When `source` is `histogram`, requests narrower than `source_bin_width` do not create new source detail. Notional is redistributed proportionally across overlapping requested buckets, while position counts remain at the source resolution. History items do not emit either source field.

## Timing and provenance

Each snapshot is computed from a periodic exchange-state snapshot of every account's positions and margin, plus mark prices and, since 2026-08-13, fills. `snapshot_ts` and `block_number` describe different moments, and their relationship changed on 2026-08-13:

**Rows from 2026-07-27 to 2026-08-13 00:12 UTC**

* Cadence: about every 45 minutes.
* `block_number`: block of the exchange-state snapshot.
* `snapshot_ts`: when that exchange-state snapshot was written, within seconds of the block.
* Positions and marks: positions as of `block_number`, not rolled forward. Marks are samples from within a few minutes of `snapshot_ts`, in some rows slightly after it.

**Rows from 2026-08-13 00:49 UTC**

* Cadence: about every 5 minutes.
* `block_number`: block of the latest exchange-state snapshot available at compute time, typically 30 to 65 minutes before `snapshot_ts`.
* `snapshot_ts`: when the row was computed.
* Positions and marks: Hyperliquid core positions are rolled forward from `block_number` with fills up to `snapshot_ts`. HIP-3 positions come from the exchange-state snapshot without roll-forward. Marks are the latest samples before `snapshot_ts`: about every 60 seconds for core perps, every few seconds for HIP-3.

Between exchange-state snapshots, isolated-margin changes and funding are not applied, and an account whose first trade came after the snapshot is added at the next one.

Use `snapshot_ts` to order and align rows. `block_number` is not the block at `snapshot_ts`: consecutive rows often share it, and it does not always increase from one row to the next.

## Read retained history

Use the `/history` variant to enumerate snapshots in ascending `snapshot_ts` order. 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=1&summary=true" \
  -H "X-API-Key: $OXARCHIVE_API_KEY"
```

### Summary history response

Representative response to the `limit=1&summary=true` request above. The request ID is synthetic.

```json theme={"theme":"github-dark"}
{
  "success": true,
  "data": [
    {
      "snapshot_ts": "2026-08-05 14:03:07.000",
      "block_number": 1099000000,
      "mid_price": 64281.0,
      "total_long": 792122474.4,
      "total_short": 875697280.92,
      "flagged_notional": 137629962.54
    }
  ],
  "meta": {
    "count": 1,
    "next_cursor": "1785938587000",
    "request_id": "e5f6a7b8-c9d0-4123-8def-123456789abc"
  }
}
```

History is retained from 2026-07-27, at the cadences in [Timing and provenance](#timing-and-provenance). Set `summary=true` when you do not need the bucket histogram. Summary items retain `snapshot_ts`, `block_number`, `mid_price`, `total_long`, `total_short`, and `flagged_notional`, while omitting only `levels`. 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 history operation pages document the complete 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

Long exposure is projected below the snapshot mark price and short exposure above it. A bucket with more projected notional means more open-position exposure is estimated to be forced near that price. It does not predict that the market will trade there, and it is not completed liquidation volume.

`total_long` and `total_short` cover the whole book, while `levels` contains only the requested `range_pct` window. Do not expect the visible bucket sums to equal the whole-book totals. Keep `flagged_notional` beside those totals so approximate exposure or exposure not assigned to a returned bucket remains visible.

These projected forced-liquidation levels are aggregate bucketed estimates. They are not an account, wallet, or position liquidation-price endpoint. For positioning context, pair them with [Open interest](/rest-api/open-interest).

## 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 | Availability |
| - | - |
| Hyperliquid | No venue-wide start date; see `/v1/symbols` per symbol<br />REST only, no WebSocket channel<br />Up to 100 rows a page |
| HIP-3 | No venue-wide start date; see `/v1/symbols` per symbol<br />REST only, no WebSocket channel<br />Up to 100 rows a page |

| Surface | Names |
| - | - |
| Python SDK | No dedicated helper; call the Hyperliquid or HIP-3 REST route directly |
| TypeScript SDK | No dedicated helper; call the Hyperliquid or HIP-3 REST route directly |
| Rust SDK | No dedicated helper; call the Hyperliquid or HIP-3 REST route directly |
| CLI | `oxa liquidations levels`, `oxa liquidations levels-history` |
| MCP tools | `get_liquidation_levels`, `get_liquidation_levels_history`, `get_hip3_liquidation_levels`, `get_hip3_liquidation_levels_history` |

## Stream it live

There is no dedicated projected liquidation-level WebSocket channel. Poll the REST snapshot on a cadence that reflects the roughly 5-minute source update instead of treating it as a tick stream. For completed forced-liquidation events, use the Hyperliquid core `liquidations` or HIP-3 `hip3_liquidations` WebSocket channel documented on [WebSocket channels](/websocket/channels).

## Export in bulk

There is no standalone projected liquidation-level export schema. Use the cursor-paginated history route for retained projected snapshots. The Data Catalog `liquidations` export contains completed liquidation events, not projected forced-liquidation levels.

## Keep liquidation data grains separate

| If you need | Use, and its 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; the [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 document those contracts.

## Next step

For observed liquidation events and volume buckets, continue to [Liquidations](/rest-api/liquidations).


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