清算マップ API

清算マップ API は、レバレッジをかけた無期限先物ポジションの強制決済が、現在価格に対してどの水準で発生するかを返します。具体的には、価格が各水準まで下落した場合に清算される ロング ポジションの米ドル建て金額と、各水準まで上昇した場合に清算される ショート ポジションの金額を示します。マップは BTC、ETH、SOL、HYPE について 1 日 1 回提供されます。

2 つのソースは常に個別に返されます。表示する際も、それぞれ別のラベルを付けてください。

`source`	ラベル	内容	コイン	履歴
`hyperliquid`	Hyperliquid — 実ポジション	事実データ：すべての保有者について読み取ったポジションとその清算価格です。	BTC, ETH, SOL, HYPE	2025-07-29 から
`binance_model`	Binance — モデル	推定値：Binance はポジションを開示していないため、公開されている建玉（open interest）と 1 時間足からレベルをモデル化しています。	BTC, ETH, SOL, HYPE	2023-01-01 から。HYPE は 2025-06-06 から

マップの構築方法、バケットの意味、およびその裏付けとなる検証結果については、清算マップの方法論をご覧ください。

取引シグナルではありません

清算マップは記述的なツールであり、目標価格や取引シグナルではありません。

エンドポイント

メソッド	パス	説明
`GET`	`/v1/liqmap/meta`	ソース、コイン、履歴のカバレッジ、欠損期間、最新スナップショット
`GET`	`/v1/liqmap/map`	1 日分のレベル（デフォルト：最新のマップ）
`GET`	`/v1/liqmap/heatmap`	ヒートマップ用の日 × 価格マトリクス

ベース URL：https://api.blocklens.co。すべてのレスポンスは JSON です：{"success": true, "data": {…}}。

認証

すべてのリクエストに API キーが必要です。

Authorization: Bearer YOUR_API_KEY

API キーについては認証を、API アクセスを含むプランとリクエスト制限についてはレート制限とプランをご覧ください。

プランと履歴

履歴の期間制限は Lab の画面上だけでなく、API 側でも適用されます。

プラン	現在のマップ	履歴（`/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 には 3 種類のスナップショットがあります。
- kind = "scan" — 当社による全保有者の日次スキャン（おおよそ 02:00–03:40 UTC。取引所の建玉に対するカバレッジ付き）。
- kind = "archive" — アーカイブされた取引所全体の状態（履歴。約 2 日遅れで公開され、時刻は日によって異なります — 必ず 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 = \|サイズ\| × 清算価格
`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 パーセンタイル。カラースケールの上限としてこの値を使用してください。

制限とペイロードサイズ

1 回のヒートマップリクエストでカバーできるのは最大 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 キーごとのリクエスト制限：レート制限とプラン。

更新とキャッシュ

マップは 1 日 1 回構築され（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	レート制限を超過	レート制限とプランを参照

エンドポイント​

認証​

プランと履歴​

日付とスナップショット時刻​

GET /v1/liqmap/meta​

GET /v1/liqmap/map​

再構築された日​

GET /v1/liqmap/heatmap​

制限とペイロードサイズ​

更新とキャッシュ​

エラー​