Liquidation Map API

The Liquidation Map API returns where forced closing of leveraged perpetual-futures positions sits relative to the price: how many US dollars of long positions would be liquidated if the price fell to each level, and how many dollars of short positions if it rose to each level. One map per day, for BTC, ETH, SOL and HYPE.

Two sources are always returned separately and must be labelled separately:

`source`	Label	What it is	Coins	History
`hyperliquid`	Hyperliquid — actual positions	Facts: positions and their liquidation prices, read for every holder.	BTC, ETH, SOL, HYPE	from 2025-07-29
`binance_model`	Binance — model	An estimate: Binance does not disclose positions, so levels are modelled from public open interest and hourly candles.	BTC, ETH, SOL, HYPE	from 2023-01-01; HYPE from 2025-06-06

How the maps are built, what a bucket means and what the evidence says about them: Liquidation Map Methodology.

Not a trading signal

The liquidation map is a descriptive tool, not a price target or a trading signal.

Endpoints

Method	Path	Description
`GET`	`/v1/liqmap/meta`	Sources, coins, history coverage, gaps, latest snapshot
`GET`	`/v1/liqmap/map`	Levels of one day (default: the latest map)
`GET`	`/v1/liqmap/heatmap`	Day × price matrix for a heatmap

Base URL: https://api.blocklens.co. All responses are JSON: {"success": true, "data": {…}}.

Authentication

All requests require an API key:

Authorization: Bearer YOUR_API_KEY

See Authentication for API keys and Rate Limits & Tiers for which plans include API access and the request limits.

Tiers and history

The history window is enforced by the API itself, not only by the Lab interface:

Tier	Current map	History (`/map?date=`, `/heatmap`)
Free	yes	the last 30 days
Pro, Enterprise	yes	everything (Hyperliquid since 2025-07-29, Binance model since 2023-01-01)

Every response carries an access block:

"access": {"tier": "free", "grade": 0, "full_history": false, "history_from": "2026-09-21", "clipped": false}

history_from — the first day the caller may see (null for the full history).
clipped — true when /heatmap was asked for days before history_from and they were cut off.
/map for a day before history_from returns 403 (see Errors). /heatmap never returns 403 for this reason: it returns the allowed part and sets clipped.

Days and snapshot time

snapshot_ts — the moment the map describes (UTC, ISO 8601); day — its UTC date.
Hyperliquid has three kinds of snapshots:
- kind = "scan" — our daily scan of every holder (around 02:00–03:40 UTC, with coverage against the exchange open interest);
- kind = "archive" — an archived full exchange state (history; published with about two days of delay, its time of day varies — always read snapshot_ts);
- kind = "reconstructed" — an estimate for a day without an archived snapshot (2025-08-01 and 2025-10-25 … 2025-12-14). Positions are rebuilt from the exchange's trades and account transfers between the neighbouring archived snapshots, at 00:05 UTC of day: sizes and entry prices are exact, liquidation prices are estimated. HYPE has reduced accuracy. A reconstructed row never replaces a real one.
Which kind is returned for a day: /map — scan, else archive, else reconstructed; a /heatmap row — archive, else scan, else reconstructed. The current map is the latest scan.
Binance model: kind = "model", the state at 00:00 UTC of day, built from a 180-day window. For a coin listed inside that window (HYPE, listed 2025-05-30) the first months are a partial warm-up: see warmup_complete_from in /meta, quality.warmup_complete in /map and warmup in /heatmap.

GET /v1/liqmap/meta

No parameters. Lists every source and coin with data.

curl -H "Authorization: Bearer YOUR_API_KEY" https://api.blocklens.co/v1/liqmap/meta

{
  "success": true,
  "data": {
    "sources": [
      {
        "id": "binance_model", "label": "Binance — model", "kinds": ["model"], "variants": ["all"],
        "model": {"window_days": 180, "leverage": [[3, 1], [4, 1], [5, 3], [10, 3], [20, 1], [25, 1], [50, 1], [100, 1]],
                  "split": "taker", "mmr": {"BTC": 0.004, "ETH": 0.005, "SOL": 0.005, "HYPE": 0.01}},
        "coins": {
          "HYPE": {
            "first_day": "2025-06-06", "last_day": "2026-10-21", "days": 503,
            "gaps": [], "gaps_detail": [], "reconstructed": [], "heatmap_bin": 0.25,
            "warmup_complete_from": "2025-11-28",
            "latest": {"day": "2026-10-21", "kind": "model", "snapshot_ts": "2026-10-21T00:00:00Z",
                       "mark": 80.388, "coverage": null}
          }
        }
      }
    ],
    "access": {"tier": "pro", "grade": 1, "full_history": true, "history_from": null, "clipped": false}
  }
}

Field	Meaning
`first_day`, `last_day`, `days`	Days with a map (all kinds together)
`gaps`, `gaps_detail`	Day ranges without any map; `cause`: `source` — no data upstream and nothing reconstructed, permanent; `pipeline` — missed on our side, rebuildable. Reconstructed days are not gaps
`reconstructed`	Day ranges served only by `kind = "reconstructed"` (estimates): `from`, `to`, `days`, `cause` (`source`), a fixed `reason`, `warning` — `null` or `"reduced_accuracy"` (HYPE). `[]` when there are none. Hyperliquid: 2025-08-01 and 2025-10-25 … 2025-12-14
`heatmap_bin`	Price bin of `/heatmap` for this coin
`warmup_complete_from`	First day with a full 180-day model window (equals `first_day` unless the coin was listed inside the history)
`latest`	The latest map: `day`, `kind`, `snapshot_ts`, `mark`, `coverage` (Hyperliquid scans)
`model`	Binance model parameters: window, leverages with weights, side split, maintenance margin per coin

GET /v1/liqmap/map

Parameter	Default	Description
`source`	required	`hyperliquid` or `binance_model`
`coin`	`BTC`	`BTC`, `ETH`, `SOL`, `HYPE`
`variant`	`all`	`ex_top20` — without the 20 largest positions per side (Hyperliquid only)
`date`	latest	`YYYY-MM-DD`; checked against the tier window
`kind`	`scan`, else `archive`, else `reconstructed`	Hyperliquid only: `scan`, `archive` or `reconstructed`. With `kind` the returned day is checked against the tier window
`price_min`, `price_max`	±50% of the price	Trim `levels`; cumulative sums are still computed from the full map

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://api.blocklens.co/v1/liqmap/map?source=hyperliquid&coin=BTC"

{
  "success": true,
  "data": {
    "source": "hyperliquid", "coin": "BTC", "variant": "all", "kind": "scan",
    "day": "2026-10-21", "snapshot_ts": "2026-10-21T04:24:01Z", "mark": 82786.0, "step": 250.0,
    "levels": [
      {"low": 81000.0, "high": 81250.0, "long_usd": 8921855.42, "short_usd": 0.0, "n_long": 192, "n_short": 0,
       "long_cum": 8921855.42, "short_cum": 0.0}
    ],
    "peaks": {
      "long": [{"price": 69125.0, "usd": 103298708.19, "dist": -0.165, "cum_usd": 591527132.58}],
      "short": [{"price": 99375.0, "usd": 86587194.39, "dist": 0.2004, "cum_usd": 493868353.82}]
    },
    "summary": {"long_usd": 1099674044.33, "short_usd": 883645628.86,
                "beyond_span_long_usd": 44627725.29, "beyond_span_short_usd": 2016401356.54,
                "top20_long_usd": 498000000.0, "top20_short_usd": 371000000.0},
    "coverage": {"long_share": 0.9998, "short_share": 0.9999, "ok": true},
    "quality": {"addresses_source": "archive", "addresses_scanned": 41526, "failed": 0, "duration_min": 83.1},
    "access": {"tier": "pro", "grade": 1, "full_history": true, "history_from": null, "clipped": false}
  }
}

Field	Meaning
`levels`	Equal-width buckets `[low, high)` ascending by price, about 0.25% of the price wide (`step`). `long_usd` — longs liquidated if the price falls into the bucket (only below `mark`); `short_usd` — shorts liquidated if it rises into it (only above `mark`). USD = \|size\| × liquidation price
`n_long`, `n_short`	Number of positions in the bucket (Hyperliquid; `0` for the model)
`long_cum`, `short_cum`	Cumulative USD from `mark` down (longs) or up (shorts) to this bucket
`peaks`	Up to 5 largest buckets per side, at least 3% of the price apart; `dist` = price / mark − 1
`summary`	Totals within ±50% of the price, volume beyond that range (`beyond_span_`), positions already past the price during a scan (`past_mark`), the 20 largest positions per side (`top20_*_usd`)
`coverage`	Hyperliquid scans only: found long/short size ÷ half of the exchange open interest; `ok` = both ≥ 0.99. `null` for archives, reconstructed days and the model
`quality`	Diagnostics (scan duration, addresses, model window and parameters, `warmup_days` / `warmup_complete`, missing hours); for display on hover, not for logic. For a reconstructed day see Reconstructed days

Reconstructed days

For kind = "reconstructed" the coverage is null and quality describes the estimate:

"quality": {"method": "fills_replay_v1", "anchor_prev": "2025-10-24", "anchor_next": "2025-12-15",
            "days_to_anchor": 7.0, "share_prev": 0.81, "share_next": 0.12, "share_assumed": 0.07,
            "positions": 17012, "ledger_accounts": 2318, "coin_warning": null}

Field	Meaning
`method`	Reconstruction method version
`anchor_prev`, `anchor_next`	The neighbouring days with an archived snapshot
`days_to_anchor`	Distance to the nearer anchor in days — the main accuracy driver
`share_prev`, `share_next`, `share_assumed`	Notional shares whose collateral came from the previous anchor, the next anchor, or an assumption (accounts new in the gap)
`positions`, `ledger_accounts`	Positions in the map and accounts with transfers replayed
`coin_warning`	`"reduced_accuracy"` for HYPE, otherwise `null`

Validated against real snapshots (51 days): on average 56% of the top-5 clusters per side fall within ±1% of the real ones — 68% at 1–3 days from an anchor, 46% at 22–26 days. Label these days as estimates.

GET /v1/liqmap/heatmap

Parameter	Default	Description
`source`, `coin`, `variant`	as in `/map`
`from_date`	first allowed day	Earlier than the tier window → cut off, `access.clipped = true`
`to_date`	latest day
`price_min`, `price_max`	0.5 × lowest … 1.5 × highest price of the returned days	Snapped to the bin grid

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://api.blocklens.co/v1/liqmap/heatmap?source=binance_model&coin=BTC&from_date=2026-09-01"

{
  "success": true,
  "data": {
    "source": "binance_model", "coin": "BTC", "variant": "all",
    "bin": 500.0, "price_lo": 41000.0, "n_bins": 4,
    "days": ["2026-10-20", "2026-10-21"], "kinds": ["model", "model"],
    "snapshot_ts": ["2026-10-20T00:00:00Z", "2026-10-21T00:00:00Z"],
    "marks": [81903.3, 82410.2], "close": [82410.2, null], "warmup": [false, false],
    "long_usd": [[1484528, 0, 930688, 0], [1210000, 5000, 0, 0]],
    "short_usd": [[0, 0, 0, 0], [0, 0, 0, 0]],
    "scale": {"p99": 61000000, "max": 103298708},
    "access": {"tier": "pro", "grade": 1, "full_history": true, "history_from": null, "clipped": false}
  }
}

Row j of long_usd / short_usd is the map of days[j]; column i is the price bin [price_lo + i·bin, price_lo + (i+1)·bin). Values are whole USD. Longs are non-zero only below that day's price, shorts only above.
Bins: BTC $500, ETH $20, SOL $0.5, HYPE $0.25 — the same grid for both sources.
Days without a map are absent from days (no empty rows).
marks[j] — the price at snapshot_ts[j]; close[j] — the UTC daily close of days[j] (BTC, ETH, SOL; null for HYPE and for a day that has not closed yet).
kinds[j] — the kind of the row; "reconstructed" marks an estimate (hatch or dim it).
warmup[j] — true when the model window of that day is a partial warm-up.
scale.p99 — the 99th percentile of non-zero cells; cap a colour scale at it.

Limits and payload size

A heatmap request may cover at most 2,000,000 cells (days × bins); larger requests return 400.
The largest default request — the full Binance model history of SOL (2023-01-01 to today, $0.5 bins) — is about 1,390 × 777 cells per side, about 6 MB of uncompressed JSON. Responses are gzip-compressed on the wire.
For a first view pass from_date (for example the last 90 days) and/or price_min / price_max around the current price; load the full history on demand.
Request limits per API key: Rate Limits & Tiers.

Updates and caching

Maps are built once a day (Binance model around 01:30 UTC, Hyperliquid scan from 02:00 UTC) and published by about 05:30 UTC. Until then the previous day is the latest.
Responses are cached on the server until the next daily update.
The same URL returns different history for different tiers, so responses are sent with Cache-Control: private, max-age=3600 and Vary: Authorization — they are never stored by shared caches.

Errors

Status	When	Body
400	Unknown `source` / `coin` / `variant`, `ex_top20` for the Binance model, a bad date, `price_min` / `price_max` not finite, negative or `price_min >= price_max`, a heatmap above 2,000,000 cells	`{"error": "Invalid parameter", "message": "…"}`
401	Missing or invalid API key
403	`/map` for a day before `history_from`	`{"error": "Insufficient tier", "message": "History older than 30 days requires Pro", "required_grade": 1, "current_tier": "free", "current_grade": 0, "history_from": "2026-09-21", "upgrade_url": "https://blocklens.co/pricing"}`
404	No map for the requested source, coin or day	`{"error": "Not found", "message": "…"}`
429	Rate limit exceeded	See Rate Limits & Tiers

Endpoints​

Authentication​

Tiers and history​

Days and snapshot time​

GET /v1/liqmap/meta​

GET /v1/liqmap/map​

Reconstructed days​

GET /v1/liqmap/heatmap​

Limits and payload size​

Updates and caching​

Errors​