API do Mapa de Liquidações

A API do Mapa de Liquidações informa onde se concentra o fechamento forçado de posições alavancadas em futuros perpétuos em relação ao preço: quantos dólares americanos em posições long seriam liquidados se o preço caísse até cada nível, e quantos dólares em posições short se subisse até cada nível. Um mapa por dia, para BTC, ETH, SOL e HYPE.

As duas fontes são sempre retornadas em separado e devem ser identificadas cada uma com seu próprio rótulo:

`source`	Rótulo	O que é	Moedas	Histórico
`hyperliquid`	Hyperliquid — posições reais	Fatos: posições e seus preços de liquidação, obtidos conta por conta.	BTC, ETH, SOL, HYPE	desde 2025-07-29
`binance_model`	Binance — modelo	Uma estimativa: a Binance não divulga posições, então os níveis são modelados a partir dos contratos em aberto públicos e de candles horários.	BTC, ETH, SOL, HYPE	desde 2023-01-01; HYPE desde 2025-06-06

Como os mapas são construídos, o que significa um bucket e o que as evidências dizem sobre eles: Metodologia do Mapa de Liquidações.

Não é um sinal de trading

O mapa de liquidações é uma ferramenta descritiva, não um alvo de preço nem um sinal de trading.

Endpoints

Método	Caminho	Descrição
`GET`	`/v1/liqmap/meta`	Fontes, moedas, cobertura do histórico, lacunas, snapshot mais recente
`GET`	`/v1/liqmap/map`	Níveis de um dia (padrão: o mapa mais recente)
`GET`	`/v1/liqmap/heatmap`	Matriz dia × preço para um mapa de calor

URL base: https://api.blocklens.co. Todas as respostas são JSON: {"success": true, "data": {…}}.

Autenticação

Todas as requisições exigem uma chave de API:

Authorization: Bearer YOUR_API_KEY

Consulte Autenticação para chaves de API e Limites de requisições e planos para saber quais planos incluem acesso à API e quais são os limites de requisições.

Planos e histórico

A janela de histórico é aplicada pela própria API, não apenas pela interface do Lab:

Plano	Mapa atual	Histórico (`/map?date=`, `/heatmap`)
Free	sim	os últimos 30 dias
Pro, Enterprise	sim	tudo (Hyperliquid desde 2025-07-29, modelo da Binance desde 2023-01-01)

Toda resposta contém um bloco access:

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

history_from — o primeiro dia que o solicitante pode ver (null para o histórico completo).
clipped — true quando /heatmap foi solicitado para dias anteriores a history_from e eles foram cortados.
/map para um dia anterior a history_from retorna 403 (veja Erros). /heatmap nunca retorna 403 por esse motivo: retorna a parte permitida e define clipped.

Dias e horário do snapshot

snapshot_ts — o momento que o mapa descreve (UTC, ISO 8601); day — sua data em UTC.
A Hyperliquid tem três tipos de snapshots:
- kind = "scan" — nossa varredura diária de todos os detentores (por volta de 02:00–03:40 UTC, com cobertura medida em relação aos contratos em aberto da exchange);
- kind = "archive" — um estado completo arquivado da exchange (histórico; publicado com cerca de dois dias de atraso, o horário do dia varia — sempre leia snapshot_ts);
- kind = "reconstructed" — uma estimativa para um dia sem snapshot arquivado (2025-08-01 e 2025-10-25 … 2025-12-14). As posições são reconstruídas a partir das negociações e das transferências entre contas da exchange entre os snapshots arquivados vizinhos, às 00:05 UTC de day: tamanhos e preços de entrada são exatos, os preços de liquidação são estimados. HYPE tem precisão reduzida. Uma linha reconstruída nunca substitui uma real.
Qual tipo é retornado para um dia: /map — scan, senão archive, senão reconstructed; uma linha de /heatmap — archive, senão scan, senão reconstructed. O mapa atual é a varredura mais recente.
Modelo da Binance: kind = "model", o estado às 00:00 UTC de day, construído a partir de uma janela de 180 dias. Para uma moeda listada dentro dessa janela (HYPE, listada em 2025-05-30), os primeiros meses são um aquecimento parcial: veja warmup_complete_from em /meta, quality.warmup_complete em /map e warmup em /heatmap.

GET /v1/liqmap/meta

Sem parâmetros. Lista todas as fontes e moedas com dados.

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`	Dias com mapa (todos os tipos juntos)
`gaps`, `gaps_detail`	Intervalos de dias sem nenhum mapa; `cause`: `source` — sem dados na origem e nada reconstruído, permanente; `pipeline` — falha do nosso lado, reconstruível. Dias reconstruídos não são lacunas
`reconstructed`	Intervalos de dias atendidos apenas por `kind = "reconstructed"` (estimativas): `from`, `to`, `days`, `cause` (`source`), um `reason` fixo, `warning` — `null` ou `"reduced_accuracy"` (HYPE). `[]` quando não há nenhum. Hyperliquid: 2025-08-01 e 2025-10-25 … 2025-12-14
`heatmap_bin`	Faixa de preço (bin) de `/heatmap` para esta moeda
`warmup_complete_from`	Primeiro dia com uma janela completa de 180 dias do modelo (igual a `first_day`, a menos que a moeda tenha sido listada dentro do histórico)
`latest`	O mapa mais recente: `day`, `kind`, `snapshot_ts`, `mark`, `coverage` (varreduras da Hyperliquid)
`model`	Parâmetros do modelo da Binance: janela, alavancagens com pesos, divisão entre lados, margem de manutenção por moeda

GET /v1/liqmap/map

Parâmetro	Padrão	Descrição
`source`	obrigatório	`hyperliquid` ou `binance_model`
`coin`	`BTC`	`BTC`, `ETH`, `SOL`, `HYPE`
`variant`	`all`	`ex_top20` — sem as 20 maiores posições por lado (apenas Hyperliquid)
`date`	mais recente	`YYYY-MM-DD`; verificado em relação à janela do plano
`kind`	`scan`, senão `archive`, senão `reconstructed`	Apenas Hyperliquid: `scan`, `archive` ou `reconstructed`. Com `kind`, o dia retornado é verificado em relação à janela do plano
`price_min`, `price_max`	±50% do preço	Limitam o intervalo de `levels`; as somas cumulativas continuam sendo calculadas sobre o 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 mesma largura `[low, high)` em ordem crescente de preço, com cerca de 0,25% do preço de largura (`step`). `long_usd` — longs liquidados se o preço cair para dentro do bucket (apenas abaixo de `mark`); `short_usd` — shorts liquidados se o preço subir até ele (apenas acima de `mark`). USD = \|tamanho\| × preço de liquidação
`n_long`, `n_short`	Número de posições no bucket (Hyperliquid; `0` para o modelo)
`long_cum`, `short_cum`	USD cumulativo de `mark` para baixo (longs) ou para cima (shorts) até este bucket
`peaks`	Até 5 maiores buckets por lado, distantes entre si pelo menos 3% do preço; `dist` = preço / mark − 1
`summary`	Totais dentro de ±50% do preço, volume além desse intervalo (`beyond_span_`), posições que já ultrapassaram o preço durante uma varredura (`past_mark`), as 20 maiores posições por lado (`top20_*_usd`)
`coverage`	Apenas varreduras da Hyperliquid: tamanho long/short encontrado ÷ metade dos contratos em aberto da exchange; `ok` = ambos ≥ 0,99. `null` para arquivos, dias reconstruídos e o modelo
`quality`	Diagnósticos (duração da varredura, endereços, janela e parâmetros do modelo, `warmup_days` / `warmup_complete`, horas ausentes); para exibição ao passar o cursor, não para lógica. Para um dia reconstruído, veja Dias reconstruídos

Dias reconstruídos

Para kind = "reconstructed", coverage é null e quality descreve a estimativa:

"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`	Versão do método de reconstrução
`anchor_prev`, `anchor_next`	Os dias vizinhos com snapshot arquivado
`days_to_anchor`	Distância até a âncora mais próxima, em dias — o principal fator de precisão
`share_prev`, `share_next`, `share_assumed`	Parcelas do valor nocional cujo colateral veio da âncora anterior, da âncora seguinte ou de uma suposição (contas novas no intervalo)
`positions`, `ledger_accounts`	Posições no mapa e contas cujas transferências foram reprocessadas
`coin_warning`	`"reduced_accuracy"` para HYPE, caso contrário `null`

Validado contra snapshots reais (51 dias): em média, 56% dos 5 maiores clusters por lado ficam dentro de ±1% dos reais — 68% a 1–3 dias de uma âncora, 46% a 22–26 dias. Rotule esses dias como estimativas.

GET /v1/liqmap/heatmap

Parâmetro	Padrão	Descrição
`source`, `coin`, `variant`	como em `/map`
`from_date`	primeiro dia permitido	Anterior à janela do plano → cortado, `access.clipped = true`
`to_date`	dia mais recente
`price_min`, `price_max`	0,5 × o menor … 1,5 × o maior preço dos dias retornados	Ajustados à grade de bins

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

A linha j de long_usd / short_usd é o mapa de days[j]; a coluna i é o bin de preço [price_lo + i·bin, price_lo + (i+1)·bin). Os valores são USD inteiros. Longs são diferentes de zero apenas abaixo do preço daquele dia, shorts apenas acima.
Bins: BTC $500, ETH $20, SOL $0.5, HYPE $0.25 — a mesma grade para ambas as fontes.
Dias sem mapa estão ausentes de days (sem linhas vazias).
marks[j] — o preço em snapshot_ts[j]; close[j] — o fechamento diário em UTC de days[j] (BTC, ETH, SOL; null para HYPE e para um dia que ainda não fechou).
kinds[j] — o tipo da linha; "reconstructed" marca uma estimativa (exiba-a com hachura ou atenuada).
warmup[j] — true quando a janela do modelo daquele dia é um aquecimento parcial.
scale.p99 — o percentil 99 das células diferentes de zero; limite a escala de cores a esse valor.

Limites e tamanho da resposta

Uma requisição de mapa de calor pode cobrir no máximo 2.000.000 células (dias × bins); requisições maiores retornam 400.
A maior requisição padrão — o histórico completo do modelo da Binance para SOL (de 2023-01-01 até hoje, bins de $0.5) — tem cerca de 1.390 × 777 células por lado, cerca de 6 MB de JSON sem compressão. As respostas são transmitidas com compressão gzip.
Para uma primeira visualização, passe from_date (por exemplo, os últimos 90 dias) e/ou price_min / price_max em torno do preço atual; carregue o histórico completo sob demanda.
Limites de requisições por chave de API: Limites de requisições e planos.

Atualizações e cache

Os mapas são construídos uma vez por dia (modelo da Binance por volta de 01:30 UTC, varredura da Hyperliquid a partir de 02:00 UTC) e publicados até cerca de 05:30 UTC. Até lá, o dia anterior é o mais recente.
As respostas ficam em cache no servidor até a próxima atualização diária.
A mesma URL retorna históricos diferentes para planos diferentes, por isso as respostas são enviadas com Cache-Control: private, max-age=3600 e Vary: Authorization — elas nunca são armazenadas por caches compartilhados.

Erros

Status	Quando	Corpo
400	`source` / `coin` / `variant` desconhecido, `ex_top20` para o modelo da Binance, data inválida, `price_min` / `price_max` não finito, negativo ou `price_min >= price_max`, mapa de calor acima de 2.000.000 células	`{"error": "Invalid parameter", "message": "…"}`
401	Chave de API ausente ou inválida
403	`/map` para um dia 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	Nenhum mapa para a fonte, moeda ou dia solicitado	`{"error": "Not found", "message": "…"}`
429	Limite de requisições excedido	Veja Limites de requisições e planos

Endpoints​

Autenticação​

Planos e histórico​

Dias e horário do snapshot​

GET /v1/liqmap/meta​

GET /v1/liqmap/map​

Dias reconstruídos​

GET /v1/liqmap/heatmap​

Limites e tamanho da resposta​

Atualizações e cache​

Erros​