API de la carte des liquidations

L'API de la carte des liquidations indique à quels niveaux de prix se situent les clôtures forcées des positions à effet de levier sur les contrats perpétuels : combien de dollars américains de positions longues seraient liquidés si le prix descendait à chaque niveau, et combien de dollars de positions courtes s'il montait à chaque niveau. Une carte par jour, pour BTC, ETH, SOL et HYPE.

Deux sources sont toujours renvoyées séparément et doivent être étiquetées séparément :

`source`	Libellé	Nature	Actifs	Historique
`hyperliquid`	Hyperliquid — positions réelles	Des faits : les positions et leurs prix de liquidation, relevés pour chaque détenteur.	BTC, ETH, SOL, HYPE	depuis le 2025-07-29
`binance_model`	Binance — modèle	Une estimation : Binance ne publie pas les positions, les niveaux sont donc modélisés à partir de l'intérêt ouvert public et des bougies horaires.	BTC, ETH, SOL, HYPE	depuis le 2023-01-01 ; HYPE depuis le 2025-06-06

Construction des cartes, signification d'un intervalle et ce que montrent les données : Méthodologie de la carte des liquidations.

Pas un signal de trading

La carte des liquidations est un outil descriptif, pas un objectif de prix ni un signal de trading.

Endpoints

Méthode	Chemin	Description
`GET`	`/v1/liqmap/meta`	Sources, actifs, couverture de l'historique, lacunes, dernier instantané
`GET`	`/v1/liqmap/map`	Niveaux d'une journée (par défaut : la carte la plus récente)
`GET`	`/v1/liqmap/heatmap`	Matrice jour × prix pour une heatmap

URL de base : https://api.blocklens.co. Toutes les réponses sont au format JSON : {"success": true, "data": {…}}.

Authentification

Toutes les requêtes nécessitent une clé d'API :

Authorization: Bearer YOUR_API_KEY

Consultez Authentification pour les clés d'API et Limites de débit et formules pour savoir quelles formules incluent l'accès à l'API ainsi que les limites de requêtes.

Formules et historique

La fenêtre d'historique est appliquée par l'API elle-même, et pas uniquement par l'interface du Lab :

Formule	Carte actuelle	Historique (`/map?date=`, `/heatmap`)
Free	oui	les 30 derniers jours
Pro, Enterprise	oui	tout (Hyperliquid depuis le 2025-07-29, modèle Binance depuis le 2023-01-01)

Chaque réponse contient un bloc access :

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

history_from — le premier jour accessible à l'appelant (null pour l'historique complet).
clipped — true lorsque /heatmap a été interrogé pour des jours antérieurs à history_from et que ceux-ci ont été tronqués.
/map pour un jour antérieur à history_from renvoie 403 (voir Erreurs). /heatmap ne renvoie jamais 403 pour cette raison : il renvoie la partie autorisée et passe clipped à true.

Jours et horodatage des instantanés

snapshot_ts — l'instant décrit par la carte (UTC, ISO 8601) ; day — sa date UTC.
Hyperliquid propose trois types d'instantanés :
- kind = "scan" — notre balayage quotidien de tous les détenteurs (vers 02:00–03:40 UTC, avec une couverture mesurée par rapport à l'intérêt ouvert de la plateforme) ;
- kind = "archive" — un état complet archivé de la plateforme (historique ; publié avec environ deux jours de retard, son heure varie — lisez toujours snapshot_ts) ;
- kind = "reconstructed" — une estimation pour un jour sans instantané archivé (2025-08-01 et 2025-10-25 … 2025-12-14). Les positions sont reconstruites à partir des transactions de la plateforme et des transferts entre comptes survenus entre les instantanés archivés voisins, à 00:05 UTC de day : les tailles et les prix d'entrée sont exacts, les prix de liquidation sont estimés. La précision est réduite pour HYPE. Une ligne reconstruite ne remplace jamais une ligne réelle.
Type renvoyé pour un jour donné : /map — scan, sinon archive, sinon reconstructed ; une ligne de /heatmap — archive, sinon scan, sinon reconstructed. La carte actuelle correspond au balayage le plus récent.
Modèle Binance : kind = "model", l'état à 00:00 UTC de day, construit sur une fenêtre de 180 jours. Pour un actif listé à l'intérieur de cette fenêtre (HYPE, listé le 2025-05-30), les premiers mois constituent une période de préchauffage partielle : voir warmup_complete_from dans /meta, quality.warmup_complete dans /map et warmup dans /heatmap.

GET /v1/liqmap/meta

Aucun paramètre. Liste chaque source et chaque actif disposant de données.

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

Champ	Signification
`first_day`, `last_day`, `days`	Jours disposant d'une carte (tous types confondus)
`gaps`, `gaps_detail`	Plages de jours sans aucune carte ; `cause` : `source` — aucune donnée en amont et rien de reconstruit, définitif ; `pipeline` — manqué de notre côté, reconstructible. Les jours reconstruits ne sont pas des lacunes
`reconstructed`	Plages de jours servies uniquement par `kind = "reconstructed"` (estimations) : `from`, `to`, `days`, `cause` (`source`), une `reason` fixe, `warning` — `null` ou `"reduced_accuracy"` (HYPE). `[]` s'il n'y en a aucune. Hyperliquid : 2025-08-01 et 2025-10-25 … 2025-12-14
`heatmap_bin`	Intervalle de prix de `/heatmap` pour cet actif
`warmup_complete_from`	Premier jour disposant d'une fenêtre de modèle complète de 180 jours (égal à `first_day`, sauf si l'actif a été listé au cours de l'historique)
`latest`	La carte la plus récente : `day`, `kind`, `snapshot_ts`, `mark`, `coverage` (balayages Hyperliquid)
`model`	Paramètres du modèle Binance : fenêtre, effets de levier avec pondérations, répartition par côté, marge de maintenance par actif

GET /v1/liqmap/map

Paramètre	Valeur par défaut	Description
`source`	obligatoire	`hyperliquid` ou `binance_model`
`coin`	`BTC`	`BTC`, `ETH`, `SOL`, `HYPE`
`variant`	`all`	`ex_top20` — sans les 20 plus grandes positions par côté (Hyperliquid uniquement)
`date`	la plus récente	`YYYY-MM-DD` ; vérifiée par rapport à la fenêtre de la formule
`kind`	`scan`, sinon `archive`, sinon `reconstructed`	Hyperliquid uniquement : `scan`, `archive` ou `reconstructed`. Avec `kind`, le jour renvoyé est vérifié par rapport à la fenêtre de la formule
`price_min`, `price_max`	±50 % du prix	Restreignent `levels` ; les sommes cumulées restent calculées sur la carte complète

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

Champ	Signification
`levels`	Intervalles de largeur égale `[low, high)`, triés par prix croissant, d'une largeur d'environ 0,25 % du prix (`step`). `long_usd` — positions longues liquidées si le prix descend dans l'intervalle (uniquement sous `mark`) ; `short_usd` — positions courtes liquidées s'il monte dans l'intervalle (uniquement au-dessus de `mark`). USD = \|taille\| × prix de liquidation
`n_long`, `n_short`	Nombre de positions dans l'intervalle (Hyperliquid ; `0` pour le modèle)
`long_cum`, `short_cum`	USD cumulés depuis `mark` vers le bas (positions longues) ou vers le haut (positions courtes) jusqu'à cet intervalle
`peaks`	Jusqu'à 5 plus grands intervalles par côté, espacés d'au moins 3 % du prix ; `dist` = prix / mark − 1
`summary`	Totaux dans la plage de ±50 % du prix, volume au-delà de cette plage (`beyond_span_`), positions ayant déjà dépassé le prix pendant un balayage (`past_mark`), les 20 plus grandes positions par côté (`top20_*_usd`)
`coverage`	Balayages Hyperliquid uniquement : taille longue/courte trouvée ÷ la moitié de l'intérêt ouvert de la plateforme ; `ok` = les deux ≥ 0,99. `null` pour les archives, les jours reconstruits et le modèle
`quality`	Diagnostics (durée du balayage, adresses, fenêtre et paramètres du modèle, `warmup_days` / `warmup_complete`, heures manquantes) ; destinés à l'affichage au survol, pas à la logique applicative. Pour un jour reconstruit, voir Jours reconstruits

Jours reconstruits

Pour kind = "reconstructed", coverage vaut null et quality décrit l'estimation :

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

Champ	Signification
`method`	Version de la méthode de reconstruction
`anchor_prev`, `anchor_next`	Les jours voisins disposant d'un instantané archivé
`days_to_anchor`	Distance en jours jusqu'à l'ancre la plus proche — principal facteur de précision
`share_prev`, `share_next`, `share_assumed`	Parts du notionnel dont le collatéral provient de l'ancre précédente, de l'ancre suivante ou d'une hypothèse (comptes apparus pendant la lacune)
`positions`, `ledger_accounts`	Positions présentes dans la carte et comptes dont les transferts ont été rejoués
`coin_warning`	`"reduced_accuracy"` pour HYPE, sinon `null`

Validation par rapport à des instantanés réels (51 jours) : en moyenne, 56 % des 5 principaux clusters par côté se situent à ±1 % des clusters réels — 68 % à 1–3 jours d'une ancre, 46 % à 22–26 jours. Présentez ces jours comme des estimations.

GET /v1/liqmap/heatmap

Paramètre	Valeur par défaut	Description
`source`, `coin`, `variant`	comme pour `/map`
`from_date`	premier jour autorisé	Antérieure à la fenêtre de la formule → tronquée, `access.clipped = true`
`to_date`	dernier jour
`price_min`, `price_max`	0,5 × prix le plus bas … 1,5 × prix le plus haut des jours renvoyés	Alignés sur la grille des intervalles

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

La ligne j de long_usd / short_usd correspond à la carte de days[j] ; la colonne i correspond à l'intervalle de prix [price_lo + i·bin, price_lo + (i+1)·bin). Les valeurs sont des montants entiers en USD. Les positions longues n'apparaissent que sous le prix du jour, les positions courtes qu'au-dessus.
Intervalles : BTC $500, ETH $20, SOL $0.5, HYPE $0.25 — la même grille pour les deux sources.
Les jours sans carte sont absents de days (pas de lignes vides).
marks[j] — le prix à snapshot_ts[j] ; close[j] — la clôture quotidienne UTC de days[j] (BTC, ETH, SOL ; null pour HYPE et pour un jour pas encore clôturé).
kinds[j] — le type de la ligne ; "reconstructed" signale une estimation (à hachurer ou atténuer).
warmup[j] — true lorsque la fenêtre du modèle pour ce jour est en préchauffage partiel.
scale.p99 — le 99e centile des cellules non nulles ; plafonnez l'échelle de couleurs à cette valeur.

Limites et taille des réponses

Une requête de heatmap peut couvrir au maximum 2 000 000 de cellules (jours × intervalles) ; les requêtes plus volumineuses renvoient 400.
La plus grande requête par défaut — l'historique complet du modèle Binance pour SOL (du 2023-01-01 à aujourd'hui, intervalles de $0.5) — représente environ 1 390 × 777 cellules par côté, soit environ 6 Mo de JSON non compressé. Les réponses sont compressées en gzip lors de la transmission.
Pour un premier affichage, passez from_date (par exemple les 90 derniers jours) et/ou price_min / price_max autour du prix actuel ; chargez l'historique complet à la demande.
Limites de requêtes par clé d'API : Limites de débit et formules.

Mises à jour et mise en cache

Les cartes sont construites une fois par jour (modèle Binance vers 01:30 UTC, balayage Hyperliquid à partir de 02:00 UTC) et publiées vers 05:30 UTC. Avant cette heure, la carte la plus récente reste celle de la veille.
Les réponses sont mises en cache sur le serveur jusqu'à la prochaine mise à jour quotidienne.
La même URL renvoie un historique différent selon la formule ; les réponses sont donc envoyées avec Cache-Control: private, max-age=3600 et Vary: Authorization — elles ne sont jamais stockées par les caches partagés.

Erreurs

Statut	Cas	Corps
400	`source` / `coin` / `variant` inconnu, `ex_top20` pour le modèle Binance, date invalide, `price_min` / `price_max` non finis, négatifs ou `price_min >= price_max`, heatmap de plus de 2 000 000 de cellules	`{"error": "Invalid parameter", "message": "…"}`
401	Clé d'API absente ou invalide
403	`/map` pour un jour antérieur à `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	Aucune carte pour la source, l'actif ou le jour demandé	`{"error": "Not found", "message": "…"}`
429	Limite de débit dépassée	Voir Limites de débit et formules

Endpoints​

Authentification​

Formules et historique​

Jours et horodatage des instantanés​

GET /v1/liqmap/meta​

GET /v1/liqmap/map​

Jours reconstruits​

GET /v1/liqmap/heatmap​

Limites et taille des réponses​

Mises à jour et mise en cache​

Erreurs​