Liquidation Map API

La Liquidation Map API indica dove si collocano, rispetto al prezzo, le chiusure forzate delle posizioni con leva sui futures perpetui: quanti dollari USA di posizioni long verrebbero liquidati se il prezzo scendesse a ciascun livello e quanti dollari di posizioni short se salisse a ciascun livello. Una mappa al giorno, per BTC, ETH, SOL e HYPE.

Le due fonti vengono sempre restituite separatamente e vanno etichettate in modo distinto:

`source`	Etichetta	Che cosa è	Coin	Storico
`hyperliquid`	Hyperliquid — posizioni effettive	Dati effettivi: le posizioni e i relativi prezzi di liquidazione, rilevati per ciascun detentore.	BTC, ETH, SOL, HYPE	dal 2025-07-29
`binance_model`	Binance — modello	Una stima: Binance non divulga le posizioni, quindi i livelli sono modellati a partire dall'open interest pubblico e dalle candele orarie.	BTC, ETH, SOL, HYPE	dal 2023-01-01; HYPE dal 2025-06-06

Come vengono costruite le mappe, che cosa rappresenta un bucket e che cosa mostrano i dati: Metodologia della mappa di liquidazione.

Non è un segnale di trading

La mappa di liquidazione è uno strumento descrittivo, non un target di prezzo né un segnale di trading.

Endpoint

Metodo	Percorso	Descrizione
`GET`	`/v1/liqmap/meta`	Fonti, coin, copertura dello storico, lacune, ultimo snapshot
`GET`	`/v1/liqmap/map`	Livelli di un giorno (predefinito: l'ultima mappa)
`GET`	`/v1/liqmap/heatmap`	Matrice giorno × prezzo per una heatmap

URL di base: https://api.blocklens.co. Tutte le risposte sono in JSON: {"success": true, "data": {…}}.

Autenticazione

Ogni richiesta deve includere una chiave API:

Authorization: Bearer YOUR_API_KEY

Consultare Autenticazione per le chiavi API e Limiti di frequenza e piani per sapere quali piani includono l'accesso API e quali sono i limiti di richiesta.

Piani e storico

La finestra dello storico è imposta dall'API stessa, non solo dall'interfaccia del Lab:

Piano	Mappa corrente	Storico (`/map?date=`, `/heatmap`)
Free	sì	gli ultimi 30 giorni
Pro, Enterprise	sì	tutto (Hyperliquid dal 2025-07-29, modello Binance dal 2023-01-01)

Ogni risposta contiene un blocco access:

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

history_from — il primo giorno visibile al chiamante (null per lo storico completo).
clipped — true quando a /heatmap sono stati richiesti giorni precedenti a history_from e questi sono stati esclusi.
/map per un giorno precedente a history_from restituisce 403 (vedere Errori). /heatmap non restituisce mai 403 per questo motivo: restituisce la parte consentita e imposta clipped.

Giorni e orario dello snapshot

snapshot_ts — l'istante descritto dalla mappa (UTC, ISO 8601); day — la relativa data UTC.
Hyperliquid ha tre tipi di snapshot:
- kind = "scan" — la nostra scansione giornaliera di ogni detentore (circa tra le 02:00 e le 03:40 UTC, con copertura rispetto all'open interest dell'exchange);
- kind = "archive" — uno stato completo dell'exchange archiviato (storico; pubblicato con circa due giorni di ritardo, l'orario varia — leggere sempre snapshot_ts);
- kind = "reconstructed" — una stima per un giorno privo di snapshot archiviato (2025-08-01 e 2025-10-25 … 2025-12-14). Le posizioni vengono ricostruite a partire dai trade dell'exchange e dai trasferimenti tra account compresi tra gli snapshot archiviati adiacenti, alle 00:05 UTC di day: dimensioni e prezzi di ingresso sono esatti, i prezzi di liquidazione sono stimati. Per HYPE l'accuratezza è ridotta. Una riga ricostruita non sostituisce mai una reale.
Tipo restituito per ciascun giorno: /map — scan, altrimenti archive, altrimenti reconstructed; una riga di /heatmap — archive, altrimenti scan, altrimenti reconstructed. La mappa corrente è l'ultima scansione.
Modello Binance: kind = "model", lo stato alle 00:00 UTC di day, costruito su una finestra di 180 giorni. Per una coin quotata all'interno di tale finestra (HYPE, quotata il 2025-05-30) i primi mesi sono un warm-up parziale: vedere warmup_complete_from in /meta, quality.warmup_complete in /map e warmup in /heatmap.

GET /v1/liqmap/meta

Nessun parametro. Elenca ogni fonte e coin con dati disponibili.

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

Campo	Significato
`first_day`, `last_day`, `days`	Giorni con una mappa (tutti i tipi insieme)
`gaps`, `gaps_detail`	Intervalli di giorni senza alcuna mappa; `cause`: `source` — nessun dato a monte e nulla di ricostruito, permanente; `pipeline` — non elaborato da noi, recuperabile. I giorni ricostruiti non sono lacune
`reconstructed`	Intervalli di giorni serviti solo da `kind = "reconstructed"` (stime): `from`, `to`, `days`, `cause` (`source`), un `reason` fisso, `warning` — `null` oppure `"reduced_accuracy"` (HYPE). `[]` se non ce ne sono. Hyperliquid: 2025-08-01 e 2025-10-25 … 2025-12-14
`heatmap_bin`	Intervallo di prezzo (bin) di `/heatmap` per questa coin
`warmup_complete_from`	Primo giorno con una finestra del modello completa di 180 giorni (coincide con `first_day`, a meno che la coin non sia stata quotata all'interno dello storico)
`latest`	L'ultima mappa: `day`, `kind`, `snapshot_ts`, `mark`, `coverage` (scansioni Hyperliquid)
`model`	Parametri del modello Binance: finestra, leve con pesi, ripartizione tra i lati, margine di mantenimento per coin

GET /v1/liqmap/map

Parametro	Predefinito	Descrizione
`source`	obbligatorio	`hyperliquid` oppure `binance_model`
`coin`	`BTC`	`BTC`, `ETH`, `SOL`, `HYPE`
`variant`	`all`	`ex_top20` — senza le 20 posizioni più grandi per lato (solo Hyperliquid)
`date`	più recente	`YYYY-MM-DD`; verificato rispetto alla finestra del piano
`kind`	`scan`, altrimenti `archive`, altrimenti `reconstructed`	Solo Hyperliquid: `scan`, `archive` oppure `reconstructed`. Con `kind` il giorno restituito viene verificato rispetto alla finestra del piano
`price_min`, `price_max`	±50% del prezzo	Restringono `levels`; le somme cumulative sono comunque calcolate sulla mappa completa

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

Campo	Significato
`levels`	Bucket di uguale ampiezza `[low, high)` in ordine crescente di prezzo, larghi circa lo 0,25% del prezzo (`step`). `long_usd` — long liquidati se il prezzo scende nel bucket (solo sotto `mark`); `short_usd` — short liquidati se il prezzo sale nel bucket (solo sopra `mark`). USD = \|dimensione\| × prezzo di liquidazione
`n_long`, `n_short`	Numero di posizioni nel bucket (Hyperliquid; `0` per il modello)
`long_cum`, `short_cum`	USD cumulativi da `mark` verso il basso (long) o verso l'alto (short) fino a questo bucket
`peaks`	Fino a 5 bucket più grandi per lato, distanti tra loro almeno il 3% del prezzo; `dist` = prezzo / mark − 1
`summary`	Totali entro ±50% del prezzo, volume oltre tale intervallo (`beyond_span_`), posizioni già oltre il prezzo durante una scansione (`past_mark`), le 20 posizioni più grandi per lato (`top20_*_usd`)
`coverage`	Solo scansioni Hyperliquid: dimensione long/short rilevata ÷ metà dell'open interest dell'exchange; `ok` = entrambe ≥ 0,99. `null` per archivi, giorni ricostruiti e modello
`quality`	Diagnostica (durata della scansione, indirizzi, finestra e parametri del modello, `warmup_days` / `warmup_complete`, ore mancanti); da mostrare al passaggio del mouse, non da usare nella logica. Per un giorno ricostruito vedere Giorni ricostruiti

Giorni ricostruiti

Per kind = "reconstructed" il campo coverage è null e quality descrive la stima:

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

Campo	Significato
`method`	Versione del metodo di ricostruzione
`anchor_prev`, `anchor_next`	I giorni adiacenti con uno snapshot archiviato
`days_to_anchor`	Distanza in giorni dall'ancora più vicina — il fattore che incide di più sull'accuratezza
`share_prev`, `share_next`, `share_assumed`	Quote del nozionale il cui collaterale proviene dall'ancora precedente, da quella successiva o da un'ipotesi (account nuovi nell'intervallo)
`positions`, `ledger_accounts`	Posizioni nella mappa e account di cui sono stati rielaborati i trasferimenti
`coin_warning`	`"reduced_accuracy"` per HYPE, altrimenti `null`

Validazione rispetto a snapshot reali (51 giorni): in media il 56% dei primi 5 cluster per lato cade entro ±1% di quelli reali — il 68% a 1–3 giorni da un'ancora, il 46% a 22–26 giorni. Etichettare questi giorni come stime.

GET /v1/liqmap/heatmap

Parametro	Predefinito	Descrizione
`source`, `coin`, `variant`	come in `/map`
`from_date`	primo giorno consentito	Se anteriore alla finestra del piano → escluso, `access.clipped = true`
`to_date`	ultimo giorno
`price_min`, `price_max`	0,5 × prezzo minimo … 1,5 × prezzo massimo dei giorni restituiti	Allineati alla griglia dei bin

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 riga j di long_usd / short_usd è la mappa di days[j]; la colonna i è il bin di prezzo [price_lo + i·bin, price_lo + (i+1)·bin). I valori sono in USD interi. I long sono diversi da zero solo sotto il prezzo di quel giorno, gli short solo sopra.
Bin: BTC $500, ETH $20, SOL $0.5, HYPE $0.25 — la stessa griglia per entrambe le fonti.
I giorni senza mappa non compaiono in days (nessuna riga vuota).
marks[j] — il prezzo a snapshot_ts[j]; close[j] — la chiusura giornaliera UTC di days[j] (BTC, ETH, SOL; null per HYPE e per un giorno non ancora chiuso).
kinds[j] — il tipo della riga; "reconstructed" indica una stima (da tratteggiare o attenuare).
warmup[j] — true quando la finestra del modello di quel giorno è un warm-up parziale.
scale.p99 — il 99° percentile delle celle diverse da zero; usarlo come limite superiore della scala di colori.

Limiti e dimensione del payload

Una richiesta di heatmap può coprire al massimo 2.000.000 di celle (giorni × bin); le richieste più grandi restituiscono 400.
La richiesta predefinita più grande — lo storico completo del modello Binance per SOL (dal 2023-01-01 a oggi, bin da $0.5) — è di circa 1.390 × 777 celle per lato, circa 6 MB di JSON non compresso. Le risposte vengono inviate compresse con gzip.
Per una prima visualizzazione passare from_date (ad esempio gli ultimi 90 giorni) e/o price_min / price_max attorno al prezzo corrente; caricare lo storico completo su richiesta.
Limiti di richiesta per chiave API: Limiti di frequenza e piani.

Aggiornamenti e caching

Le mappe vengono costruite una volta al giorno (modello Binance intorno alle 01:30 UTC, scansione Hyperliquid dalle 02:00 UTC) e pubblicate entro le 05:30 UTC circa. Fino ad allora, il giorno più recente disponibile è quello precedente.
Le risposte sono memorizzate nella cache del server fino al successivo aggiornamento giornaliero.
Lo stesso URL restituisce uno storico diverso a seconda del piano, quindi le risposte vengono inviate con Cache-Control: private, max-age=3600 e Vary: Authorization — non vengono mai memorizzate da cache condivise.

Errori

Stato	Quando	Corpo
400	`source` / `coin` / `variant` sconosciuti, `ex_top20` per il modello Binance, una data non valida, `price_min` / `price_max` non finiti, negativi o `price_min >= price_max`, una heatmap oltre 2.000.000 di celle	`{"error": "Invalid parameter", "message": "…"}`
401	Chiave API mancante o non valida
403	`/map` per un giorno precedente a `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	Nessuna mappa per la fonte, la coin o il giorno richiesti	`{"error": "Not found", "message": "…"}`
429	Limite di frequenza superato	Vedere Limiti di frequenza e piani

Endpoint​

Autenticazione​

Piani e storico​

Giorni e orario dello snapshot​

GET /v1/liqmap/meta​

GET /v1/liqmap/map​

Giorni ricostruiti​

GET /v1/liqmap/heatmap​

Limiti e dimensione del payload​

Aggiornamenti e caching​

Errori​