Hyperliquid liquidation fills API | HL fill tape vs aggregate totals

What Agents Can Do With Per-Event Fills

The live product path is https://cryptodataapi.com/liquidations. The archive path for the same Hyperliquid fill tape is https://cryptodataapi.com/backtest-data.

This post is about Hyperliquid liquidation fills. The search angle is a Hyperliquid liquidation fills API. The dataset name is hl_liquidations. The query path is GET /api/v1/backtesting/hl-liquidations. The live aggregate companion is GET /api/v1/market-intelligence/liquidations and MCP tool get_liquidations.

I am Sam Deering. I built this so an agent can read forced flow fill by fill. Agents read. They do not trade. We are not a broker.

A Hyperliquid liquidation is an exact fill. It is not a guessed open-interest drop.

Each event on the tape carries the fields OpenAPI names on BacktestHLLiquidationEvent: time, tid, coin, symbol, side, px, sz, usd, method, mark_px, liquidated_user, hash.

Product copy on the liquidations page and the backtest archive names the same surface as price, size, side, and market vs backstop. The exact JSON keys for those four are px, sz, side, and method. OpenAPI describes each row as one exact Hyperliquid liquidation fill (market or backstop).

With that tape an agent can:

Detect a one-sided cascade from real fills, not from a rolled 24h total.
Wait until the cascade bucket closes, then fade. Do not invent a fill inside the bucket.
Backtest fill-by-fill against /api/v1/backtesting/hl-liquidations joined to klines.
Size risk off real forced notional (usd, sz) instead of a venue heatmap tile.
Split market vs backstop using method, so backstop clears are not treated like book prints.

That is the value. Forced flow is mechanical. It overshoots. The fill tape makes the overshoot testable.

What Aggregate 24h Totals Cannot Do

The live board at https://cryptodataapi.com/liquidations also shows cross-exchange long/short totals. Those totals answer how much was force-closed in a window. They do not answer which fill, at which price, on which method.

Aggregate totals cannot:

Give you px and sz for a single forced print.
Tell market from backstop.
Let you join one fill to the next bar after the cascade bucket closes.
Support fill-by-fill replay for a Hyperliquid-only strategy.

Heatmaps and clustered levels are useful context. They are a different dataset. liquidation_map and liquidation_levels are not the lead of this post.

Where to See It

Human page: https://cryptodataapi.com/liquidations.

That page leads with live long/short totals and a top-coin heatmap. Scroll to the backtest block. It names hl_liquidations as every exact Hyperliquid liquidation fill — price, size, side, market vs backstop — since 23 Jul 2026.

Archive catalogue: https://cryptodataapi.com/backtest-data. Same hl_liquidations row. Daily Parquet. Full perp universe. Columns documented as time, tid, coin, symbol, side, px, sz, usd, method, mark_px, liquidated_user, hash.

Live aggregate REST:

curl -H "X-API-Key: cdk_live_your_key" \
  -H "User-Agent: cryptodataapi-python/1.0" \
  "https://cryptodataapi.com/api/v1/market-intelligence/liquidations?exchange=all"

Per-event Hyperliquid tape REST:

curl -H "X-API-Key: cdk_live_your_key" \
  -H "User-Agent: cryptodataapi-python/1.0" \
  "https://cryptodataapi.com/api/v1/backtesting/hl-liquidations?coin=BTC&start=2026-07-23&limit=5000"

Bulk archive (Pro Plus):

curl -H "X-API-Key: cdk_live_your_key" \
  -H "User-Agent: cryptodataapi-python/1.0" \
  "https://cryptodataapi.com/api/v1/backtesting/archives/download?data_type=hl_liquidations&start=2026-07-23"

How to Read Market vs Backstop

Read method on each fill.

OpenAPI and the product pages describe the tape as market plus backstop fills. Marketing language says market vs backstop. The field name is method. Do not invent a second key named market_vs_backstop.

Read order on one event:

Confirm coin / symbol.
Read side — which side was liquidated.
Read px and sz (and usd for notional).
Read method — market or backstop path.
Read time / tid so you can order fills and join after the bucket closes.
Keep mark_px as context, not as the fill price.

A market fill hits the book. A backstop fill is a different clear path. Mixing them into one average price lies to a backtest.

Pagination gotcha: the endpoint's own docs are explicit about this because it breaks the fill-by-fill backtest this post recommends. Rows are ordered by the full (time, tid) key, and next_cursor resumes exactly there. One liquidation order that sweeps N book levels lands as N rows at the same time. Naively paging by setting start to the last row's time silently drops the sibling rows from that same sweep that fell past your page boundary — they share the exact timestamp you just moved past. Use next_cursor to page, never a manually advanced start.

What It Is Not

This is not a Coinglass war page. This is not a competitor comparison SEO page. Venue aggregate totals are named only to show what they cannot do. We are not ranking dashboards.

This is not a candles-first tutorial. Bars cannot invent forced-flow fills.

This is not a Discord pitch.

This is not the liquidation_map gamma lead. Liquidation density heatmaps and GEX / gamma_profile are sibling products, mentioned once here for orientation, not the lead. The gamma-profile piece is a draft sibling, no live URL yet. Product page for GEX: https://cryptodataapi.com/quant-gamma.

This is not the merged multi-venue bar series alone. /api/v1/backtesting/liquidations is rolling venue-merged totals. The per-event HL tape is /api/v1/backtesting/hl-liquidations.

Free Key and Pro Cliff

Free path: POST /api/v1/auth/keys with a real email, or sign in at https://cryptodataapi.com. Confirm the email. Confirming lifts the same key from 100 to 1,000 requests a day and switches Pro on for 24 hours.

MCP docs say get_liquidations returns BTC on Free and the full coin universe on Pro.

OpenAPI and llms-full say GET /api/v1/backtesting/hl-liquidations is Pro (Pro Plus included) since 2026-09-07. The daily hl_liquidations archive stays Pro Plus.

The query endpoint serves a local retention window of about 30 days. Full history is the daily Parquet archive from 23 Jul 2026 — plus one earlier pocket: the archive additionally holds a pilot backfill from 2026-04-24 to 2026-05-05, ahead of the main live-capture start. A window that starts before local retention returns an empty result with a coverage hint rather than silently.

Live rates from llms.txt: Free 10 req/min; Pro 30; Pro Plus 120. Current dollar prices live at https://cryptodataapi.com/pricing — read that page, do not hard-code plan dollars here.

For Agents: MCP, Tool Order, Example Prompt

Verified on https://cryptodataapi.com/ai-agents/mcp-server and https://cryptodataapi.com/llms.txt:

Live aggregates: MCP tool get_liquidations → GET /api/v1/market-intelligence/liquidations.
Per-event HL tape: REST GET /api/v1/backtesting/hl-liquidations. The MCP server deliberately leaves heavy /backtesting/* bulk tools off the curated set. Use REST for the fill tape. Do not invent an MCP tool named hl_liquidations or get_hl_liquidations.

Tool order:

list_capabilities — no key. See what exists and what each tier unlocks.
create_free_api_key — only if you lack a key. Real email.
Confirm that email for the 24h Pro window and the higher free daily budget.
get_daily_snapshot — optional orientation.
get_liquidations — live long/short window totals. Useful for “who is getting squeezed now.”
REST GET /api/v1/backtesting/hl-liquidations?coin=BTC&start=... — the fill tape. Pro.
Join to klines only after you have fills. Charge taker fees both sides. Assume you fill after the cascade bucket closes.

Example agent prompt:

Read live liquidation totals with get_liquidations. Then pull the Hyperliquid per-event tape from GET /api/v1/backtesting/hl-liquidations?coin=BTC&start=2026-07-23&limit=5000. Report px, sz, side, method, usd, and time for the largest one-sided 5-minute bucket. Define the cascade relative to that coin's own flow. Do not invent fills inside the bucket. Do not invent JSON keys. If the call returns 401, 402, or 403, leave the status as-is and read the body.

Python's built-in urllib needs a named User-Agent or the CDN returns HTML 403 before the API sees the call.

REST Summary

Need	Path	Tier (docs)
Live long/short window totals	`GET /api/v1/market-intelligence/liquidations`	Free BTC-scoped; full universe Pro and Pro Plus
Per-event HL fills (~30d query)	`GET /api/v1/backtesting/hl-liquidations`	Pro since 2026-09-07
Full HL fill archive	`GET /api/v1/backtesting/archives/download?data_type=hl_liquidations`	Pro Plus
Venue-merged historical bars	`GET /api/v1/backtesting/liquidations`	Pro Plus

Response shape for the fill tape (OpenAPI): { "coin", "count", "data": [ BacktestHLLiquidationEvent, ... ] }.

One Concrete Example From This Session

I fetched the human liquidations page and the no-key REST paths on 11 Sep 2026 morning Brisbane time (AEST, UTC+10).

Page figures on https://cryptodataapi.com/liquidations (page sample; a later refresh will differ):

Total liquidated · 24h: $133.7M
Longs (forced sells): $115.0M (86.0%)
Shorts (forced buys): $18.8M (14.0%)
Last 1h / 4h / 12h / 24h: $14.5M / $26.3M / $117.9M / $133.7M
Top coin tile: BTC $43.6M
Page note: 404 coins tracked; full-universe per-coin coverage on the API is Pro; historical series on Pro Plus

Those numbers are aggregate totals. They are the board an agent sees before it opens the fill tape. They are not fills.

No-key REST in this session:

GET /api/v1/market-intelligence/liquidations?exchange=all&limit=3 → HTTP 402. Body error: payment_required (x402). Message offered a free-key path via POST /api/v1/auth/keys and email confirm for 24h Pro. I did not invent a liquidation row from that body.
GET /api/v1/backtesting/hl-liquidations?coin=BTC&start=2026-07-23&limit=3 → HTTP 401. Body error: api_key_required. Message pointed at POST /api/v1/auth/keys.
GET /api/v1/backtesting/archives/download?data_type=hl_liquidations&start=2026-07-23&end=2026-07-24 → HTTP 401. Same api_key_required shape.

Leave 401, 402, and 403 as the server returns them. Read the body. Do not retry a gate into a fake fill sample.

Documented field list for when a Pro key returns data: time, tid, coin, symbol, side, px, sz, usd, method, mark_px, liquidated_user, hash. Coverage start for hl_liquidations: 23 Jul 2026.