清算地图 API
清算地图 API 返回杠杆永续合约持仓的强平价位相对于当前价格的分布：价格跌至各个价位时，将有多少美元的多头持仓被清算；价格涨至各个价位时，又将有多少美元的空头持仓被清算。BTC、ETH、SOL 和 HYPE 每天各有一张地图。
两个数据源始终分开返回，且必须分别标注：
source | 标签 | 说明 | 币种 | 历史 |
|---|---|---|---|---|
hyperliquid | Hyperliquid——实际持仓 | 实际数据：逐一读取每个持有者的持仓及其清算价格。 | BTC, ETH, SOL, HYPE | 自 2025-07-29 起 |
binance_model | Binance——模型 | 估算数据：Binance 不公开持仓，因此价位基于公开的未平仓合约和小时 K 线建模得出。 | BTC, ETH, SOL, HYPE | 自 2023-01-01 起；HYPE 自 2025-06-06 起 |
地图如何构建、区间（bucket）代表什么以及验证结论如何，请参阅清算地图方法论。
非交易信号
清算地图是一种描述性工具，而非价格目标或交易信号。
端点
| 方法 | 路径 | 描述 |
|---|---|---|
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——当/heatmap请求了history_from之前的日期且这些日期被截除时为true。- 对
history_from之前的日期请求/map将返回 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）的估算。持仓基于相邻两次归档快照之间的交易所成交和账户划转重建，时间点为day的 00:05 UTC：持仓规模和开仓价格是精确的，清算价格是估算的。HYPE 的精度较低。重建数据行不会取代真实数据行。
同一天有多种快照时的选取顺序：
/map——优先scan，其次archive，再次reconstructed；/heatmap的数据行——优先archive，其次scan，再次reconstructed。当前地图为最新一次扫描。 -
Binance 模型：
kind = "model"，即day的 00:00 UTC 状态，基于 180 天窗口构建。对于在该窗口内上市的币种（HYPE，上市于 2025-05-30），最初几个月为部分预热期：参见/meta中的warmup_complete_from、/map中的quality.warmup_complete以及/heatmap中的warmup。
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 = |size| × 清算价格 |
n_long, n_short | 区间内的持仓数量（Hyperliquid；模型为 0） |
long_cum, short_cum | 从 mark 向下（多头）或向上（空头）至该区间的累计 USD |
peaks | 每个方向最多 5 个最大区间，彼此间隔至少为价格的 3%；dist = price / 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 | HYPE 为 "reduced_accuracy"，否则为 null |
基于真实快照（51 天）的验证结果：每个方向的前 5 个聚集区平均有 56% 落在真实值的 ±1% 以内——距锚点 1–3 天时为 68%，22–26 天时为 46%。请将这些日期标注为估算。
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}
}
}
long_usd/short_usd的第j行是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]——days[j]的 UTC 日收盘价（BTC、ETH、SOL；HYPE 以及尚未收盘的日期为null）。kinds[j]——该行的快照类型；"reconstructed"表示估算（以阴影线或淡化方式显示）。warmup[j]——当该日的模型窗口为部分预热期时为true。scale.p99——非零单元格的第 99 百分位数；可将色阶上限设为该值。
限制与负载大小
- 单次热力图请求最多可覆盖 2,000,000 个单元格（日期 × 分箱）；更大的请求将返回 400。
- 最大的默认请求——SOL 的完整 Binance 模型历史（2023-01-01 至今，$0.5 分箱）——每个方向约 1,390 × 777 个单元格，未压缩 JSON 约 6 MB。响应在传输时采用 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、对 Binance 模型使用 ex_top20、无效日期、price_min / price_max 非有限值、为负数或 price_min >= price_max、热力图超过 2,000,000 个单元格 | {"error": "Invalid parameter", "message": "…"} |
| 401 | API 密钥缺失或无效 | |
| 403 | 对 history_from 之前的日期请求 /map | {"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 | 超出速率限制 | 参见速率限制与订阅层级 |