Projected liquidation levels

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. The generated operation pages linked below provide the route-specific request and response schemas.

Routes

Dataset	Route	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 at or before that instant. The response’s snapshot_ts identifies the UTC snapshot that the levels reflect. Snapshots are computed roughly every 5 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	Routes	Type	Required	Behavior
`symbol`	Snapshot and history	string	Yes	Plain core symbol such as `BTC`, or a case-sensitive HIP-3 builder symbol such as `xyz:TSLA`
`range_pct`	Snapshot and history	number	No	Percentage range around the snapshot mark price. Clamped from 1 to 50; default 10
`buckets`	Snapshot and history	integer	No	Number of price buckets. Clamped from 10 to 200; default 50
`side`	Snapshot and history	string	No	`bid`, `buy`, or `B` keeps long exposure. `ask`, `sell`, or `A` keeps short exposure. The other side is zeroed
`at`	Snapshot only	integer (ms)	No	Return the newest snapshot at or before this Unix epoch-millisecond instant. Omit for latest
`start`	History only	integer (ms)	No	Inclusive window start. Defaults to 24 hours before the resolved `end` value
`end`	History only	integer (ms)	No	Inclusive window end. Defaults to the current time
`limit`	History only	integer	No	Snapshots per page. Default 24; clamped from 1 to 100
`cursor`	History only	string (epoch ms)	No	Exclusive `snapshot_ts` value returned in `meta.next_cursor`; pass it unchanged to read the next page
`summary`	History only	boolean	No	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	Type	Meaning
`mid_price`	number	Mark price at the snapshot and the center of the requested range
`snapshot_ts`	string	UTC snapshot time the levels reflect
`block_number`	integer	Hyperliquid block height reflected by the snapshot
`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.

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. 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 generated history 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.

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	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. Open the generated Hyperliquid trigger-level history and HIP-3 trigger-level history pages for those contracts.

Use Liquidations for observed event rows and volume buckets, Open interest for positioning context, or Venue coverage before widening a symbol window.

Start

API

Exports

Data types

Venues

Data rights

Projected liquidation levels

Routes

Get projected levels

Request parameters

Example response

Response fields

Read retained history

Summary history response

Interpret the response

Stream it live

Export in bulk

Keep liquidation data grains separate

Next

​Routes

​Get projected levels

​Request parameters

​Example response

​Response fields

​Read retained history

​Summary history response

​Interpret the response

​Stream it live

​Export in bulk

​Keep liquidation data grains separate

​Next

Routes

Get projected levels

Request parameters

Example response

Response fields

Read retained history

Summary history response

Interpret the response

Stream it live

Export in bulk

Keep liquidation data grains separate

Next