Projected liquidation levels

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. 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. The operation pages linked below carry each route’s request and response schema, and 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
Hyperliquid core history	`/v1/hyperliquid/liquidations/{symbol}/levels/history`: Get Hyperliquid liquidation levels history
HIP-3 snapshot	`/v1/hyperliquid/hip3/liquidations/{symbol}/levels`: Get HIP-3 liquidation levels
HIP-3 history	`/v1/hyperliquid/hip3/liquidations/{symbol}/levels/history`: 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.

Hyperliquid
HIP-3

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.

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.

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.

{
  "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
`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.

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.

{
  "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. 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:

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.

Access

Each venue’s start date, WebSocket channels, and page limit come from GET /v1/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.

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

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: one observed liquidation-related event row
Aggregated liquidation activity	Liquidation volume routes: 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 and 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 and HIP-3 trigger-level history pages document those contracts.

Next step

For observed liquidation events and volume buckets, continue to Liquidations.

Endpoint reference

Requests and responses

Datasets

Venues

OpenAPI and schemas

Guides

Projected liquidation levels

Routes

Get projected levels

Request parameters

Example response

Response fields

Timing and provenance

Read retained history

Summary history response

Interpret the response

Access

Stream it live

Export in bulk

Keep liquidation data grains separate

Next step

​Routes

​Get projected levels

​Request parameters

​Example response

​Response fields

​Timing and provenance

​Read retained history

​Summary history response

​Interpret the response

​Access

​Stream it live

​Export in bulk

​Keep liquidation data grains separate

​Next step

Routes

Get projected levels

Request parameters

Example response

Response fields

Timing and provenance

Read retained history

Summary history response

Interpret the response

Access

Stream it live

Export in bulk

Keep liquidation data grains separate

Next step