API del mapa de liquidaciones

La API del mapa de liquidaciones muestra en qué niveles de precio se liquidarían las posiciones apalancadas en futuros perpetuos: cuántos dólares estadounidenses de posiciones largas se liquidarían si el precio cayera a cada nivel, y cuántos dólares de posiciones cortas si subiera a cada nivel. Un mapa por día, para BTC, ETH, SOL y HYPE.

Siempre se devuelven dos fuentes por separado, y deben etiquetarse por separado:

`source`	Etiqueta	Qué es	Monedas	Historial
`hyperliquid`	Hyperliquid — posiciones reales	Hechos: posiciones y sus precios de liquidación, leídos cuenta por cuenta.	BTC, ETH, SOL, HYPE	desde 2025-07-29
`binance_model`	Binance — modelo	Una estimación: Binance no publica las posiciones, por lo que los niveles se modelan a partir del interés abierto público y de las velas horarias.	BTC, ETH, SOL, HYPE	desde 2023-01-01; HYPE desde 2025-06-06

Cómo se construyen los mapas, qué significa un bucket y qué dice la evidencia sobre ellos: Metodología del mapa de liquidaciones.

No es una señal de trading

El mapa de liquidaciones es una herramienta descriptiva, no un objetivo de precio ni una señal de trading.

Endpoints

Método	Ruta	Descripción
`GET`	`/v1/liqmap/meta`	Fuentes, monedas, cobertura del historial, huecos, último snapshot
`GET`	`/v1/liqmap/map`	Niveles de un día (por defecto: el último mapa)
`GET`	`/v1/liqmap/heatmap`	Matriz día × precio para un mapa de calor

URL base: https://api.blocklens.co. Todas las respuestas son JSON: {"success": true, "data": {…}}.

Autenticación

Todas las solicitudes requieren una clave de API:

Authorization: Bearer YOUR_API_KEY

Consulte Autenticación para las claves de API y Límites de tasa y planes para saber qué planes incluyen acceso a la API y cuáles son los límites de solicitudes.

Planes e historial

La ventana de historial la aplica la propia API, no solo la interfaz de Lab:

Plan	Mapa actual	Historial (`/map?date=`, `/heatmap`)
Free	sí	los últimos 30 días
Pro, Enterprise	sí	todo (Hyperliquid desde 2025-07-29, modelo de Binance desde 2023-01-01)

Cada respuesta incluye un bloque access:

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

history_from — el primer día que el solicitante puede ver (null para el historial completo).
clipped — true cuando se solicitaron a /heatmap días anteriores a history_from y se recortaron.
/map para un día anterior a history_from devuelve 403 (consulte Errores). /heatmap nunca devuelve 403 por este motivo: devuelve la parte permitida y establece clipped.

Días y hora del snapshot

snapshot_ts — el momento que describe el mapa (UTC, ISO 8601); day — su fecha UTC.
Hyperliquid tiene tres tipos de snapshots:
- kind = "scan" — nuestro escaneo diario de todas las cuentas (aproximadamente entre las 02:00 y las 03:40 UTC, con la cobertura medida frente al interés abierto del exchange);
- kind = "archive" — un estado completo archivado del exchange (historial; se publica con unos dos días de retraso y su hora del día varía — lea siempre snapshot_ts);
- kind = "reconstructed" — una estimación para un día sin snapshot archivado (2025-08-01 y 2025-10-25 … 2025-12-14). Las posiciones se reconstruyen a partir de las operaciones del exchange y las transferencias entre cuentas entre los snapshots archivados vecinos, a las 00:05 UTC de day: los tamaños y los precios de entrada son exactos, los precios de liquidación son estimados. HYPE tiene una precisión reducida. Una fila reconstruida nunca sustituye a una real.
Tipo que se devuelve para cada día: /map — scan, si no archive, si no reconstructed; una fila de /heatmap — archive, si no scan, si no reconstructed. El mapa actual es el último escaneo.
Modelo de Binance: kind = "model", el estado a las 00:00 UTC de day, construido a partir de una ventana de 180 días. Para una moneda listada dentro de esa ventana (HYPE, listada el 2025-05-30) los primeros meses son un calentamiento parcial: consulte warmup_complete_from en /meta, quality.warmup_complete en /map y warmup en /heatmap.

GET /v1/liqmap/meta

Sin parámetros. Enumera cada fuente y moneda con datos.

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	Significado
`first_day`, `last_day`, `days`	Días con mapa (todos los tipos en conjunto)
`gaps`, `gaps_detail`	Rangos de días sin ningún mapa; `cause`: `source` — sin datos en origen y nada reconstruido, permanente; `pipeline` — perdido por nuestra parte, reconstruible. Los días reconstruidos no son huecos
`reconstructed`	Rangos de días servidos solo por `kind = "reconstructed"` (estimaciones): `from`, `to`, `days`, `cause` (`source`), un `reason` fijo, `warning` — `null` o `"reduced_accuracy"` (HYPE). `[]` cuando no hay ninguno. Hyperliquid: 2025-08-01 y 2025-10-25 … 2025-12-14
`heatmap_bin`	Intervalo de precio de `/heatmap` para esta moneda
`warmup_complete_from`	Primer día con una ventana completa del modelo de 180 días (igual a `first_day` salvo que la moneda se listara dentro del historial)
`latest`	El último mapa: `day`, `kind`, `snapshot_ts`, `mark`, `coverage` (escaneos de Hyperliquid)
`model`	Parámetros del modelo de Binance: ventana, apalancamientos con sus pesos, reparto entre lados, margen de mantenimiento por moneda

GET /v1/liqmap/map

Parámetro	Por defecto	Descripción
`source`	obligatorio	`hyperliquid` o `binance_model`
`coin`	`BTC`	`BTC`, `ETH`, `SOL`, `HYPE`
`variant`	`all`	`ex_top20` — sin las 20 mayores posiciones por lado (solo Hyperliquid)
`date`	el último	`YYYY-MM-DD`; se verifica frente a la ventana del plan
`kind`	`scan`, si no `archive`, si no `reconstructed`	Solo Hyperliquid: `scan`, `archive` o `reconstructed`. Con `kind`, el día devuelto se verifica frente a la ventana del plan
`price_min`, `price_max`	±50% del precio	Recortan `levels`; las sumas acumuladas se siguen calculando a partir del mapa completo

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	Significado
`levels`	Buckets de igual anchura `[low, high)` en orden ascendente de precio, de aproximadamente el 0,25% del precio de ancho (`step`). `long_usd` — largos liquidados si el precio cae dentro del bucket (solo por debajo de `mark`); `short_usd` — cortos liquidados si sube hasta él (solo por encima de `mark`). USD = \|tamaño\| × precio de liquidación
`n_long`, `n_short`	Número de posiciones en el bucket (Hyperliquid; `0` para el modelo)
`long_cum`, `short_cum`	USD acumulados desde `mark` hacia abajo (largos) o hacia arriba (cortos) hasta este bucket
`peaks`	Los buckets más grandes por lado (hasta 5), separados al menos un 3% del precio; `dist` = precio / mark − 1
`summary`	Totales dentro de ±50% del precio, volumen más allá de ese rango (`beyond_span_`), posiciones que ya habían rebasado el precio durante un escaneo (`past_mark`), las 20 mayores posiciones por lado (`top20_*_usd`)
`coverage`	Solo escaneos de Hyperliquid: tamaño largo/corto encontrado ÷ la mitad del interés abierto del exchange; `ok` = ambos ≥ 0,99. `null` para archivos, días reconstruidos y el modelo
`quality`	Diagnósticos (duración del escaneo, direcciones, ventana y parámetros del modelo, `warmup_days` / `warmup_complete`, horas faltantes); pensados para mostrarse al pasar el cursor, no para usarlos en la lógica. Para un día reconstruido, consulte Días reconstruidos

Días reconstruidos

Para kind = "reconstructed", coverage es null y quality describe la estimación:

"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	Significado
`method`	Versión del método de reconstrucción
`anchor_prev`, `anchor_next`	Los días vecinos con snapshot archivado
`days_to_anchor`	Distancia en días al ancla más cercana — el principal factor de precisión
`share_prev`, `share_next`, `share_assumed`	Proporciones del nocional cuyo colateral procede del ancla anterior, del ancla siguiente o de una suposición (cuentas nuevas en el hueco)
`positions`, `ledger_accounts`	Posiciones en el mapa y cuentas cuyas transferencias se han reproducido
`coin_warning`	`"reduced_accuracy"` para HYPE; en otro caso, `null`

Validado frente a snapshots reales (51 días): en promedio, el 56% de los 5 principales clústeres por lado cae dentro de ±1% de los reales — el 68% a 1–3 días de un ancla, el 46% a 22–26 días. Etiquete estos días como estimaciones.

GET /v1/liqmap/heatmap

Parámetro	Por defecto	Descripción
`source`, `coin`, `variant`	como en `/map`
`from_date`	primer día permitido	Anterior a la ventana del plan → se recorta, `access.clipped = true`
`to_date`	último día
`price_min`, `price_max`	0,5 × el precio mínimo … 1,5 × el precio máximo de los días devueltos	Se ajustan a la cuadrícula de intervalos

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 fila j de long_usd / short_usd es el mapa de days[j]; la columna i es el intervalo de precio [price_lo + i·bin, price_lo + (i+1)·bin). Los valores son USD enteros. Los largos solo son distintos de cero por debajo del precio de ese día, y los cortos solo por encima.
Intervalos: BTC $500, ETH $20, SOL $0.5, HYPE $0.25 — la misma cuadrícula para ambas fuentes.
Los días sin mapa no aparecen en days (no hay filas vacías).
marks[j] — el precio en snapshot_ts[j]; close[j] — el cierre diario UTC de days[j] (BTC, ETH, SOL; null para HYPE y para un día que aún no ha cerrado).
kinds[j] — el tipo de la fila; "reconstructed" marca una estimación (sombréela con tramado o atenúela).
warmup[j] — true cuando la ventana del modelo de ese día es un calentamiento parcial.
scale.p99 — el percentil 99 de las celdas distintas de cero; limite la escala de colores a ese valor.

Límites y tamaño de la respuesta

Una solicitud de mapa de calor puede abarcar como máximo 2.000.000 de celdas (días × intervalos); las solicitudes mayores devuelven 400.
La mayor solicitud por defecto — el historial completo del modelo de Binance para SOL (de 2023-01-01 a hoy, intervalos de $0.5) — tiene unas 1.390 × 777 celdas por lado, unos 6 MB de JSON sin comprimir. Las respuestas se envían comprimidas con gzip.
Para una primera vista, pase from_date (por ejemplo, los últimos 90 días) y/o price_min / price_max en torno al precio actual; cargue el historial completo bajo demanda.
Límites de solicitudes por clave de API: Límites de tasa y planes.

Actualizaciones y caché

Los mapas se construyen una vez al día (modelo de Binance hacia las 01:30 UTC, escaneo de Hyperliquid a partir de las 02:00 UTC) y se publican hacia las 05:30 UTC. Hasta entonces, el día anterior es el más reciente.
Las respuestas se almacenan en caché en el servidor hasta la siguiente actualización diaria.
La misma URL devuelve un historial distinto según el plan, por lo que las respuestas se envían con Cache-Control: private, max-age=3600 y Vary: Authorization — nunca se almacenan en cachés compartidas.

Errores

Estado	Cuándo	Cuerpo
400	`source` / `coin` / `variant` desconocido, `ex_top20` para el modelo de Binance, una fecha no válida, `price_min` / `price_max` no finito, negativo o `price_min >= price_max`, un mapa de calor de más de 2.000.000 de celdas	`{"error": "Invalid parameter", "message": "…"}`
401	Clave de API ausente o no válida
403	`/map` para un día anterior 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	No hay mapa para la fuente, moneda o día solicitados	`{"error": "Not found", "message": "…"}`
429	Límite de tasa superado	Consulte Límites de tasa y planes

Endpoints​

Autenticación​

Planes e historial​

Días y hora del snapshot​

GET /v1/liqmap/meta​

GET /v1/liqmap/map​

Días reconstruidos​

GET /v1/liqmap/heatmap​

Límites y tamaño de la respuesta​

Actualizaciones y caché​

Errores​