Liquidation Map API

Die Liquidation Map API zeigt, auf welchen Preisniveaus gehebelte Perpetual-Futures-Positionen zwangsweise geschlossen würden: wie viele US-Dollar an Long-Positionen liquidiert würden, wenn der Preis auf das jeweilige Niveau fiele, und wie viele Dollar an Short-Positionen, wenn er bis dorthin stiege. Eine Karte pro Tag, für BTC, ETH, SOL und HYPE.

Die beiden Quellen werden immer getrennt ausgeliefert und müssen auch getrennt gekennzeichnet werden:

`source`	Bezeichnung	Was es ist	Coins	Historie
`hyperliquid`	Hyperliquid — tatsächliche Positionen	Fakten: Positionen samt Liquidationspreisen, für jeden Holder einzeln ausgelesen.	BTC, ETH, SOL, HYPE	ab 2025-07-29
`binance_model`	Binance — Modell	Eine Schätzung: Binance legt keine Positionen offen, daher werden die Niveaus aus dem öffentlichen Open Interest und stündlichen Kerzen modelliert.	BTC, ETH, SOL, HYPE	ab 2023-01-01; HYPE ab 2025-06-06

Wie die Karten entstehen, was ein Bucket bedeutet und was die empirischen Befunde über sie aussagen: Methodik der Liquidationskarte.

Kein Handelssignal

Die Liquidationskarte ist ein deskriptives Werkzeug, kein Kursziel und kein Handelssignal.

Endpoints

Methode	Pfad	Beschreibung
`GET`	`/v1/liqmap/meta`	Quellen, Coins, Abdeckung der Historie, Lücken, neuester Snapshot
`GET`	`/v1/liqmap/map`	Niveaus eines Tages (Standard: die neueste Karte)
`GET`	`/v1/liqmap/heatmap`	Matrix Tag × Preis für eine Heatmap

Basis-URL: https://api.blocklens.co. Alle Antworten sind JSON: {"success": true, "data": {…}}.

Authentifizierung

Alle Anfragen erfordern einen API-Schlüssel:

Authorization: Bearer YOUR_API_KEY

Siehe Authentifizierung zu API-Schlüsseln und Rate Limits & Tarife dazu, welche Tarife API-Zugriff enthalten und welche Anfragelimits gelten.

Tarife und Historie

Das Historienfenster erzwingt die API selbst, nicht erst die Lab-Oberfläche:

Tarif	Aktuelle Karte	Historie (`/map?date=`, `/heatmap`)
Free	ja	die letzten 30 Tage
Pro, Enterprise	ja	alles (Hyperliquid seit 2025-07-29, Binance-Modell seit 2023-01-01)

Jede Antwort enthält einen access-Block:

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

history_from — der erste Tag, den der Aufrufer sehen darf (null bei voller Historie).
clipped — true, wenn bei /heatmap Tage vor history_from angefragt und abgeschnitten wurden.
/map für einen Tag vor history_from liefert 403 (siehe Fehler). /heatmap liefert aus diesem Grund nie 403, sondern gibt den erlaubten Teil zurück und setzt clipped.

Tage und Snapshot-Zeitpunkt

snapshot_ts — der Zeitpunkt, den die Karte beschreibt (UTC, ISO 8601); day — dessen UTC-Datum.
Hyperliquid kennt drei Arten von Snapshots:
- kind = "scan" — unser täglicher Scan aller Holder (etwa 02:00–03:40 UTC; die Abdeckung wird am Open Interest der Börse gemessen);
- kind = "archive" — ein archivierter Gesamtzustand der Börse (Historie; mit etwa zwei Tagen Verzögerung veröffentlicht, die Tageszeit variiert — lesen Sie immer snapshot_ts);
- kind = "reconstructed" — eine Schätzung für einen Tag ohne archivierten Snapshot (2025-08-01 und 2025-10-25 … 2025-12-14). Die Positionen werden aus den Trades und Kontotransfers der Börse zwischen den benachbarten archivierten Snapshots rekonstruiert, Stichzeitpunkt ist 00:05 UTC an day: Größen und Einstiegspreise sind exakt, Liquidationspreise sind geschätzt. Für HYPE ist die Genauigkeit reduziert. Eine rekonstruierte Zeile ersetzt nie eine echte.
Welche Art für einen Tag geliefert wird: /map — scan, sonst archive, sonst reconstructed; eine /heatmap-Zeile — archive, sonst scan, sonst reconstructed. Die aktuelle Karte ist der neueste Scan.
Binance-Modell: kind = "model", der Zustand um 00:00 UTC an day, berechnet aus einem 180-Tage-Fenster. Für einen Coin, der innerhalb dieses Fensters gelistet wurde (HYPE, gelistet am 2025-05-30), gelten die ersten Monate als unvollständige Aufwärmphase: siehe warmup_complete_from in /meta, quality.warmup_complete in /map und warmup in /heatmap.

GET /v1/liqmap/meta

Keine Parameter. Listet alle Quellen und alle Coins auf, für die Daten vorliegen.

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}
  }
}

Feld	Bedeutung
`first_day`, `last_day`, `days`	Tage mit einer Karte (alle Arten zusammen)
`gaps`, `gaps_detail`	Tagesbereiche ohne jede Karte; `cause`: `source` — keine Daten bei der Quelle und nichts rekonstruiert, dauerhaft; `pipeline` — Ausfall auf unserer Seite, kann nachträglich erzeugt werden. Rekonstruierte Tage sind keine Lücken
`reconstructed`	Tagesbereiche, die nur durch `kind = "reconstructed"` (Schätzungen) abgedeckt sind: `from`, `to`, `days`, `cause` (`source`), ein fester `reason`, `warning` — `null` oder `"reduced_accuracy"` (HYPE). `[]`, falls keine vorhanden. Hyperliquid: 2025-08-01 und 2025-10-25 … 2025-12-14
`heatmap_bin`	Preis-Bin von `/heatmap` für diesen Coin
`warmup_complete_from`	Erster Tag mit vollständigem 180-Tage-Modellfenster (gleich `first_day`, es sei denn, der Coin wurde erst innerhalb des Historienzeitraums gelistet)
`latest`	Die neueste Karte: `day`, `kind`, `snapshot_ts`, `mark`, `coverage` (Hyperliquid-Scans)
`model`	Parameter des Binance-Modells: Fenster, gewichtete Hebelstufen, Aufteilung auf Long/Short, Maintenance Margin je Coin

GET /v1/liqmap/map

Parameter	Standard	Beschreibung
`source`	erforderlich	`hyperliquid` oder `binance_model`
`coin`	`BTC`	`BTC`, `ETH`, `SOL`, `HYPE`
`variant`	`all`	`ex_top20` — ohne die 20 größten Positionen je Seite (nur Hyperliquid)
`date`	neueste	`YYYY-MM-DD`; wird gegen das Tariffenster geprüft
`kind`	`scan`, sonst `archive`, sonst `reconstructed`	Nur Hyperliquid: `scan`, `archive` oder `reconstructed`. Mit `kind` wird der zurückgegebene Tag gegen das Tariffenster geprüft
`price_min`, `price_max`	±50 % des Preises	Begrenzen `levels`; kumulierte Summen werden trotzdem aus der vollständigen Karte berechnet

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}
  }
}

Feld	Bedeutung
`levels`	Gleich breite Buckets `[low, high)`, aufsteigend nach Preis, etwa 0,25 % des Preises breit (`step`). `long_usd` — Longs, die liquidiert werden, wenn der Preis in den Bucket fällt (nur unterhalb von `mark`); `short_usd` — Shorts, die liquidiert werden, wenn er in den Bucket steigt (nur oberhalb von `mark`). USD = \|size\| × Liquidationspreis
`n_long`, `n_short`	Anzahl der Positionen im Bucket (Hyperliquid; `0` beim Modell)
`long_cum`, `short_cum`	Kumulierte USD von `mark` abwärts (Longs) bzw. aufwärts (Shorts) bis zu diesem Bucket
`peaks`	Bis zu 5 größte Buckets je Seite, mindestens 3 % des Preises voneinander entfernt; `dist` = Preis / Mark − 1
`summary`	Summen innerhalb von ±50 % des Preises, Volumen außerhalb dieses Bereichs (`beyond_span_`), Positionen, die den Preis während eines Scans bereits überschritten hatten (`past_mark`), die 20 größten Positionen je Seite (`top20_*_usd`)
`coverage`	Nur Hyperliquid-Scans: erfasstes Long- bzw. Short-Volumen ÷ halbes Open Interest der Börse; `ok` = beide ≥ 0,99. `null` bei Archiven, rekonstruierten Tagen und dem Modell
`quality`	Diagnosedaten (Scandauer, Adressen, Modellfenster und -parameter, `warmup_days` / `warmup_complete`, fehlende Stunden); für Hover-Anzeigen gedacht, nicht für Programmlogik. Für einen rekonstruierten Tag siehe Rekonstruierte Tage

Rekonstruierte Tage

Bei kind = "reconstructed" ist coverage gleich null, und quality beschreibt die Schätzung:

"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}

Feld	Bedeutung
`method`	Version der Rekonstruktionsmethode
`anchor_prev`, `anchor_next`	Die benachbarten Tage mit archiviertem Snapshot
`days_to_anchor`	Abstand zum nächstgelegenen Anker in Tagen — der wichtigste Faktor für die Genauigkeit
`share_prev`, `share_next`, `share_assumed`	Nominalanteile, deren Collateral aus dem vorherigen Anker, dem nächsten Anker oder einer Annahme stammt (Konten, die erst innerhalb der Lücke hinzukamen)
`positions`, `ledger_accounts`	Positionen in der Karte bzw. Konten, deren Transfers nachvollzogen wurden
`coin_warning`	`"reduced_accuracy"` für HYPE, sonst `null`

Abgeglichen mit echten Snapshots (51 Tage): Im Schnitt liegen 56 % der Top-5-Cluster je Seite innerhalb von ±1 % der tatsächlichen — 68 % bei 1–3 Tagen Abstand zu einem Anker, 46 % bei 22–26 Tagen. Kennzeichnen Sie diese Tage als Schätzungen.

GET /v1/liqmap/heatmap

Parameter	Standard	Beschreibung
`source`, `coin`, `variant`	wie bei `/map`
`from_date`	erster erlaubter Tag	Früher als das Tariffenster → abgeschnitten, `access.clipped = true`
`to_date`	neuester Tag
`price_min`, `price_max`	0,5 × niedrigster … 1,5 × höchster Preis der zurückgegebenen Tage	Auf das Bin-Raster ausgerichtet

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}
  }
}

Zeile j von long_usd / short_usd ist die Karte von days[j]; Spalte i ist das Preis-Bin [price_lo + i·bin, price_lo + (i+1)·bin). Die Werte sind ganzzahlige USD-Beträge. Longs sind nur unterhalb des Tagespreises ungleich null, Shorts nur oberhalb.
Bins: BTC $500, ETH $20, SOL $0.5, HYPE $0.25 — dasselbe Raster für beide Quellen.
Tage ohne Karte fehlen in days (keine leeren Zeilen).
marks[j] — der Preis zum Zeitpunkt snapshot_ts[j]; close[j] — der UTC-Tagesschlusskurs von days[j] (BTC, ETH, SOL; null für HYPE und für einen noch nicht abgeschlossenen Tag).
kinds[j] — die Art der Zeile; "reconstructed" kennzeichnet eine Schätzung (schraffiert oder abgeschwächt darstellen).
warmup[j] — true, wenn das Modellfenster dieses Tages noch in der unvollständigen Aufwärmphase liegt.
scale.p99 — das 99. Perzentil der von null verschiedenen Zellen; kappen Sie die Farbskala bei diesem Wert.

Limits und Antwortgröße

Eine Heatmap-Anfrage darf höchstens 2.000.000 Zellen (Tage × Bins) umfassen; größere Anfragen liefern 400.
Die größte Standardanfrage — die vollständige Binance-Modell-Historie von SOL (2023-01-01 bis heute, $0.5-Bins) — umfasst etwa 1.390 × 777 Zellen je Seite, etwa 6 MB unkomprimiertes JSON. Antworten werden bei der Übertragung gzip-komprimiert.
Übergeben Sie für die erste Ansicht from_date (zum Beispiel die letzten 90 Tage) und/oder price_min / price_max um den aktuellen Preis; die vollständige Historie laden Sie erst bei Bedarf nach.
Anfragelimits pro API-Schlüssel: Rate Limits & Tarife.

Aktualisierungen und Caching

Die Karten werden einmal täglich erstellt (Binance-Modell gegen 01:30 UTC, Hyperliquid-Scan ab 02:00 UTC) und bis etwa 05:30 UTC veröffentlicht. Bis dahin ist die Karte des Vortags die neueste.
Antworten werden serverseitig bis zur nächsten täglichen Aktualisierung gecacht.
Dieselbe URL liefert für verschiedene Tarife unterschiedliche Historien, daher werden Antworten mit Cache-Control: private, max-age=3600 und Vary: Authorization gesendet — geteilte Caches speichern sie also nie.

Fehler

Status	Wann	Body
400	Unbekannte `source` / `coin` / `variant`, `ex_top20` für das Binance-Modell, ein ungültiges Datum, `price_min` / `price_max` nicht endlich, negativ oder `price_min >= price_max`, eine Heatmap mit mehr als 2.000.000 Zellen	`{"error": "Invalid parameter", "message": "…"}`
401	Fehlender oder ungültiger API-Schlüssel
403	`/map` für einen Tag vor `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	Keine Karte für die angefragte Quelle, den Coin oder den Tag	`{"error": "Not found", "message": "…"}`
429	Rate Limit überschritten	Siehe Rate Limits & Tarife

Endpoints​

Authentifizierung​

Tarife und Historie​

Tage und Snapshot-Zeitpunkt​

GET /v1/liqmap/meta​

GET /v1/liqmap/map​

Rekonstruierte Tage​

GET /v1/liqmap/heatmap​

Limits und Antwortgröße​

Aktualisierungen und Caching​

Fehler​