Crypto liquidation data API: history, totals and levels

Four endpoints of the Blockmetric API cover liquidation data: /liquidations for single liquidations, /liquidations/summary for totals, /liqmap/{coin} for the liquidation levels right now and /heatmap/{coin} for those levels over time. This guide shows which one answers which question, how to authenticate, how to page through history and where the data stops.

Which endpoint answers which question

Liquidation data comes in two kinds. Past liquidations are events: a position was force-closed at a time, a price and a size. Liquidation levels are a map of what is open now: the prices at which open positions would be closed if the market got there. The API keeps the two apart.

The side field always means the side of the liquidated position. A long row is a long that was closed because the price fell.

The full parameter lists, error codes and real example responses are in the API reference. This guide covers the parts that matter for liquidation work.

Authentication and the first request

Every request goes to the base URL https://api.blockmetric.io/v1 with a key in a header. Keys start with bm_live_ and are created on the API keys page of your account. The key goes in Authorization: Bearer or in x-api-key, never in the URL: a key in a query parameter is refused, because URLs end up in logs.

export BLOCKMETRIC_API_KEY="bm_live_..."
curl -s -H "Authorization: Bearer $BLOCKMETRIC_API_KEY" \
  "https://api.blockmetric.io/v1/liquidations?coin=BTC&sinceMinutes=60&limit=50"

For a first look without an account, the API also answers keyless requests that send the header X-Blockmetric-Access: public. Keyless access sees the last 24 hours only, is rate-limited per address and is for non-commercial use. A request without a key and without that header gets a 401.

Every successful answer has the same shape: data with the result and meta with the plan, the newest timestamp (meta.updatedAt), the sources, the licence of the response and, for lists, the cursor of the next page. Times are ISO timestamps in UTC and amounts are USD.

Liquidation history with /liquidations

The list is newest first. The window is sinceMinutes (default 60) or from and to as ISO times, and the filters are coin, venue, side and minUsd. A page holds limit rows (default 100, at most 1,000).¹ How far back you can read depends on the plan; the API pricing page lists the history per plan.

There are two ways to walk through it, and they solve different problems.

Paging back (research, exports). Pass meta.nextCursor of one response as cursor in the next request, with the other parameters unchanged, until it is null. The cursor is signed, so an edited cursor answers 400.

curl -s -H "Authorization: Bearer $BLOCKMETRIC_API_KEY" \
  "https://api.blockmetric.io/v1/liquidations?coin=ETH&side=long&minUsd=100000&from=2026-11-01T00:00:00Z&to=2026-11-02T00:00:00Z"

Polling forward (bots, dashboards). Pass after with the id of the last row you have seen. The answer then comes oldest first and carries meta.nextAfter for the next poll, so nothing is read twice and nothing is skipped between polls. after and cursor cannot be combined.

curl -s -H "Authorization: Bearer $BLOCKMETRIC_API_KEY" \
  "https://api.blockmetric.io/v1/liquidations?after=240641&minUsd=50000"

Two storage rules decide what an old window contains. Every single liquidation is kept for 120 days; liquidations of $10,000 or more are kept for three years. A window older than 120 days therefore lists only the large ones, while the totals of /liquidations/summary still count every liquidation.¹

A complete bot that polls forward and posts large liquidations to a chat is one of the API recipes, in JavaScript and Python.

Totals with /liquidations/summary

For charts and reports, single rows are the wrong unit. /liquidations/summary returns the totals of the last hours (default 24): long and short USD and counts, byVenue, byCoin for the coins with the most liquidated, largest and an hourly series. Add coin to get the same for one market.

curl -s -H "Authorization: Bearer $BLOCKMETRIC_API_KEY" \
  "https://api.blockmetric.io/v1/liquidations/summary?coin=BTC&hours=168"

The field coveredSince says from when every venue was collected, and the series starts at the first covered hour. When a window reaches back before that, meta.warnings names the cut. Compare periods only where the coverage is the same.

Liquidation levels with /liqmap and /heatmap

/liqmap/{coin} is the current map from the tracked Hyperliquid positions: mark, bucketSize, a list of buckets with px, longUsd, shortUsd and positions, and totals. Each position contributes at its own liquidation price, as Hyperliquid reports it; no leverage is assumed. This is the data behind "liquidation levels now" on the coin pages.

/heatmap/{coin} is the same map over time. Always pass tf (the column interval: 1m, 5m, 15m, 1h, 4h, 12h or 1d) and optionally hours and end to move the window back. The answer holds times, prices, the cells per column and price (longCells and shortCells split by side) and the mark per column.

curl -s -H "Authorization: Bearer $BLOCKMETRIC_API_KEY" \
  "https://api.blockmetric.io/v1/heatmap/BTC?tf=1h&hours=168&clusters=3"

A few parameters save work:

• clusters=N adds the largest price buckets above and below the mark of the newest column, with their signed distance. An alert bot can read that instead of scanning every cell.
• columns=live keeps only the columns of the live collection. Live columns start on 2026-11-03 14:15 UTC; before that, and in gaps, a column shows the daily snapshot of every open Hyperliquid position, and data.dataSource marks which is which.
• tf=1d uses that daily snapshot of all positions for the days it covers, so its columns show more USD than the intraday ones, which come from tracked wallets.

How the map is built, step by step, is on the methodology page. Which intervals and how much heatmap history each plan reads is on the pricing page. A backtest that tests how often the price reached the largest cluster, from heatmap history and candles, is another of the recipes.

For events as they happen, API Pro adds /stream, a Server-Sent Events connection with every radar event (for example liq_cascade) and a resume after reconnects via Last-Event-ID.

Limits of the data

• Reported totals are a lower bound. Exchanges publish only part of their liquidations on their public streams, so exchange totals undercount. Live Hyperliquid liquidations are those of tracked wallets, confirmed by Hyperliquid's own liquidation fills; hours imported from Hyperliquid's hourly archive cover every wallet, and historical data lists which hours those are.
• Licence review. While the review of their terms is pending, single rows of Binance and Bybit are not served through the API. Asking for such a venue answers 403 source_restricted, and meta.restricted lists the withheld venues. Totals over all venues stay in /liquidations/summary.
• Levels are tracked positions. The liquidation map covers the Hyperliquid wallets we track, minutes old, not every account. Exchanges do not publish positions, so their levels are not in it.
• History starts when collection started. Plan limits are caps, not a promise of data that far back. What is stored and since when is listed per dataset on historical data.

Errors follow one format with a code, a message and a request_id. A 429 carries Retry-After, and every authenticated answer reports X-RateLimit-Remaining, so a client can slow down before it hits the limit.