Liquidation Map API

Liquidation Map API показывает, где относительно цены находятся уровни принудительного закрытия позиций с кредитным плечом на бессрочных фьючерсах: сколько долларов США в длинных позициях будет ликвидировано, если цена опустится до каждого уровня, и сколько долларов в коротких позициях — если поднимется до него. Одна карта в день для BTC, ETH, SOL и HYPE.

Два источника всегда возвращаются по отдельности, и подписывать их тоже нужно по отдельности:

`source`	Подпись	Что это	Монеты	История
`hyperliquid`	Hyperliquid — фактические позиции	Факты: позиции и их цены ликвидации, считанные по каждому держателю.	BTC, ETH, SOL, HYPE	с 2025-07-29
`binance_model`	Binance — модель	Оценка: Binance не раскрывает позиции, поэтому уровни моделируются по публичному открытому интересу и часовым свечам.	BTC, ETH, SOL, HYPE	с 2023-01-01; HYPE с 2025-06-06

Как строятся карты, что такое бакет и что показала проверка на реальных данных: Методология карты ликвидаций.

Не торговый сигнал

Карта ликвидаций — описательный инструмент, а не ценовая цель и не торговый сигнал.

Эндпоинты

Метод	Путь	Описание
`GET`	`/v1/liqmap/meta`	Источники, монеты, покрытие истории, пропуски, последний снимок
`GET`	`/v1/liqmap/map`	Уровни за один день (по умолчанию — последняя карта)
`GET`	`/v1/liqmap/heatmap`	Матрица «день × цена» для тепловой карты

Базовый URL: https://api.blocklens.co. Все ответы — JSON: {"success": true, "data": {…}}.

Аутентификация

Все запросы требуют API-ключа:

Authorization: Bearer YOUR_API_KEY

Об API-ключах см. Аутентификация, а о том, какие тарифы включают доступ к API, и о лимитах запросов — Лимиты запросов и тарифы.

Тарифы и история

Окно истории ограничивается самим API, а не только интерфейсом Lab:

Тариф	Текущая карта	История (`/map?date=`, `/heatmap`)
Free	да	последние 30 дней
Pro, Enterprise	да	вся (Hyperliquid с 2025-07-29, модель Binance с 2023-01-01)

Каждый ответ содержит блок access:

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

history_from — первый день, доступный вызывающей стороне (null при полной истории).
clipped — true, если в /heatmap были запрошены дни раньше history_from и они были отсечены.
/map за день раньше history_from возвращает 403 (см. Ошибки). /heatmap по этой причине никогда не возвращает 403: он отдаёт разрешённую часть и выставляет clipped.

Дни и время снимка

snapshot_ts — момент, который описывает карта (UTC, ISO 8601); day — его дата по UTC.
У Hyperliquid три вида снимков:
- kind = "scan" — наше ежедневное сканирование всех держателей (примерно 02:00–03:40 UTC, с покрытием относительно открытого интереса биржи);
- kind = "archive" — архивное полное состояние биржи (история; публикуется с задержкой около двух дней, время суток различается — всегда смотрите snapshot_ts);
- kind = "reconstructed" — оценка для дня без архивного снимка (2025-08-01 и 2025-10-25 … 2025-12-14). Позиции восстанавливаются по сделкам биржи и переводам между счетами в интервале между соседними архивными снимками, на 00:05 UTC дня day: размеры и цены входа точные, цены ликвидации оценочные. Для HYPE точность снижена. Реконструированная строка никогда не заменяет реальную.
Какой вид снимка возвращается за день: /map — scan, иначе archive, иначе reconstructed; строка /heatmap — archive, иначе scan, иначе reconstructed. Текущая карта — последнее сканирование.
Модель Binance: kind = "model", состояние на 00:00 UTC дня day, построенное по 180-дневному окну. Для монеты, листинг которой пришёлся на это окно (HYPE, листинг 2025-05-30), первые месяцы — частичный прогрев: см. warmup_complete_from в /meta, quality.warmup_complete в /map и warmup в /heatmap.

GET /v1/liqmap/meta

Параметров нет. Возвращает все источники и монеты, по которым есть данные.

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

Поле	Значение
`first_day`, `last_day`, `days`	Дни, за которые есть карта (все виды вместе)
`gaps`, `gaps_detail`	Диапазоны дней без какой-либо карты; `cause`: `source` — у источника нет данных и ничего не реконструировано, постоянно; `pipeline` — пропущено на нашей стороне, можно перестроить. Реконструированные дни пропусками не являются
`reconstructed`	Диапазоны дней, покрытые только `kind = "reconstructed"` (оценки): `from`, `to`, `days`, `cause` (`source`), фиксированный `reason`, `warning` — `null` или `"reduced_accuracy"` (HYPE). `[]`, если таких нет. Hyperliquid: 2025-08-01 и 2025-10-25 … 2025-12-14
`heatmap_bin`	Ценовой бин `/heatmap` для этой монеты
`warmup_complete_from`	Первый день с полным 180-дневным окном модели (совпадает с `first_day`, если листинг монеты не пришёлся на период истории)
`latest`	Последняя карта: `day`, `kind`, `snapshot_ts`, `mark`, `coverage` (сканирования Hyperliquid)
`model`	Параметры модели Binance: окно, плечи с весами, разделение по сторонам, поддерживающая маржа по монетам

GET /v1/liqmap/map

Параметр	По умолчанию	Описание
`source`	обязательный	`hyperliquid` или `binance_model`
`coin`	`BTC`	`BTC`, `ETH`, `SOL`, `HYPE`
`variant`	`all`	`ex_top20` — без 20 крупнейших позиций на каждой стороне (только Hyperliquid)
`date`	последняя	`YYYY-MM-DD`; проверяется по окну тарифа
`kind`	`scan`, иначе `archive`, иначе `reconstructed`	Только Hyperliquid: `scan`, `archive` или `reconstructed`. При указании `kind` возвращаемый день проверяется по окну тарифа
`price_min`, `price_max`	±50% от цены	Обрезают `levels`; накопленные суммы по-прежнему считаются по полной карте

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

Поле	Значение
`levels`	Бакеты одинаковой ширины `[low, high)` по возрастанию цены, шириной около 0,25% от цены (`step`). `long_usd` — лонги, ликвидируемые, если цена опустится в бакет (только ниже `mark`); `short_usd` — шорты, ликвидируемые, если цена поднимется в него (только выше `mark`). USD = \|размер\| × цена ликвидации
`n_long`, `n_short`	Число позиций в бакете (Hyperliquid; `0` для модели)
`long_cum`, `short_cum`	Накопленная сумма в USD от `mark` вниз (лонги) или вверх (шорты) до этого бакета
`peaks`	До 5 крупнейших бакетов на каждой стороне, отстоящих друг от друга не менее чем на 3% цены; `dist` = цена / mark − 1
`summary`	Итоги в пределах ±50% от цены, объём за пределами этого диапазона (`beyond_span_`), позиции, уже оказавшиеся за ценой во время сканирования (`past_mark`), 20 крупнейших позиций на каждой стороне (`top20_*_usd`)
`coverage`	Только для сканирований Hyperliquid: найденный объём лонгов/шортов ÷ половина открытого интереса биржи; `ok` = оба ≥ 0,99. `null` для архивов, реконструированных дней и модели
`quality`	Диагностика (длительность сканирования, адреса, окно и параметры модели, `warmup_days` / `warmup_complete`, пропущенные часы); для показа при наведении, а не для логики. Для реконструированного дня см. Реконструированные дни

Реконструированные дни

Для kind = "reconstructed" поле coverage равно null, а quality описывает оценку:

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

Поле	Значение
`method`	Версия метода реконструкции
`anchor_prev`, `anchor_next`	Соседние дни с архивным снимком
`days_to_anchor`	Расстояние до ближайшего якоря в днях — главный фактор точности
`share_prev`, `share_next`, `share_assumed`	Доли номинала, обеспечение которых взято из предыдущего якоря, следующего якоря или из допущения (счета, появившиеся в промежутке)
`positions`, `ledger_accounts`	Позиции в карте и счета, по которым воспроизведены переводы
`coin_warning`	`"reduced_accuracy"` для HYPE, иначе `null`

Проверено на реальных снимках (51 день): в среднем 56% топ-5 кластеров на каждой стороне попадают в пределы ±1% от реальных — 68% при удалении от якоря на 1–3 дня, 46% — на 22–26 дней. Помечайте такие дни как оценки.

GET /v1/liqmap/heatmap

Параметр	По умолчанию	Описание
`source`, `coin`, `variant`	как в `/map`
`from_date`	первый разрешённый день	Раньше окна тарифа → отсекается, `access.clipped = true`
`to_date`	последний день
`price_min`, `price_max`	0,5 × минимальная … 1,5 × максимальная цена возвращаемых дней	Выравниваются по сетке бинов

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

Строка j в long_usd / short_usd — карта дня days[j]; столбец i — ценовой бин [price_lo + i·bin, price_lo + (i+1)·bin). Значения — целые доллары USD. Лонги ненулевые только ниже цены этого дня, шорты — только выше.
Бины: BTC $500, ETH $20, SOL $0.5, HYPE $0.25 — одна и та же сетка для обоих источников.
Дни без карты отсутствуют в days (пустых строк нет).
marks[j] — цена на момент snapshot_ts[j]; close[j] — дневное закрытие по UTC дня days[j] (BTC, ETH, SOL; null для HYPE и для ещё не закрытого дня).
kinds[j] — вид строки; "reconstructed" обозначает оценку (заштрихуйте или приглушите её).
warmup[j] — true, если окно модели в этот день — частичный прогрев.
scale.p99 — 99-й перцентиль ненулевых ячеек; ограничивайте им цветовую шкалу.

Лимиты и объём ответа

Запрос тепловой карты может охватывать не более 2 000 000 ячеек (дни × бины); более крупные запросы возвращают 400.
Самый крупный запрос по умолчанию — полная история модели Binance для SOL (с 2023-01-01 по сегодня, бины $0.5) — это около 1 390 × 777 ячеек на сторону, около 6 МБ несжатого JSON. При передаче ответы сжимаются gzip.
Для первого отображения передавайте from_date (например, последние 90 дней) и/или price_min / price_max вокруг текущей цены; полную историю загружайте по запросу.
Лимиты запросов на API-ключ: Лимиты запросов и тарифы.

Обновления и кэширование

Карты строятся раз в день (модель Binance — около 01:30 UTC, сканирование Hyperliquid — с 02:00 UTC) и публикуются примерно к 05:30 UTC. До этого последним остаётся предыдущий день.
Ответы кэшируются на сервере до следующего ежедневного обновления.
Один и тот же URL возвращает разную историю для разных тарифов, поэтому ответы отправляются с Cache-Control: private, max-age=3600 и Vary: Authorization — общие кэши их никогда не сохраняют.

Ошибки

Статус	Когда	Тело
400	Неизвестный `source` / `coin` / `variant`, `ex_top20` для модели Binance, некорректная дата, `price_min` / `price_max` не конечны, отрицательны или `price_min >= price_max`, тепловая карта больше 2 000 000 ячеек	`{"error": "Invalid parameter", "message": "…"}`
401	API-ключ отсутствует или недействителен
403	`/map` за день раньше `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	Нет карты для запрошенного источника, монеты или дня	`{"error": "Not found", "message": "…"}`
429	Превышен лимит запросов	См. Лимиты запросов и тарифы

Эндпоинты​

Аутентификация​

Тарифы и история​

Дни и время снимка​

GET /v1/liqmap/meta​

GET /v1/liqmap/map​

Реконструированные дни​

GET /v1/liqmap/heatmap​

Лимиты и объём ответа​

Обновления и кэширование​

Ошибки​