청산 맵 API
청산 맵 API는 레버리지를 사용한 무기한 선물 포지션이 현재 가격 대비 어느 가격대에서 강제 청산되는지를 반환합니다. 가격이 각 레벨까지 하락하면 청산될 롱 포지션이 몇 달러인지, 각 레벨까지 상승하면 청산될 숏 포지션이 몇 달러인지를 나타냅니다. 맵은 BTC, ETH, SOL, HYPE별로 하루에 하나씩 제공됩니다.
두 소스는 항상 따로 반환되며, 화면에 표시할 때도 반드시 구분해야 합니다.
source | 표시 이름 | 설명 | 코인 | 히스토리 |
|---|---|---|---|---|
hyperliquid | Hyperliquid — 실제 포지션 | 사실 데이터: 모든 보유자의 포지션과 청산 가격을 직접 읽어 온 값. | BTC, ETH, SOL, HYPE | 2025-07-29부터 |
binance_model | Binance — 모델 | 추정치: Binance는 포지션을 공개하지 않으므로, 공개된 미결제약정과 1시간봉 캔들을 바탕으로 레벨을 모델링합니다. | 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. 모든 응답은 {"success": true, "data": {…}} 형태의 JSON입니다.
인증
모든 요청에는 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에는 세 종류의 스냅샷이 있습니다.
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 가격 구간(bin) |
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 | 구간(bin) 격자에 맞춰 조정됨 |
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 정수입니다. 롱은 해당 날짜의 가격 아래에서만, 숏은 가격 위에서만 0이 아닌 값을 가집니다.- 구간(bin): 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— 0이 아닌 셀의 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 | 속도 제한 초과 | 속도 제한 및 등급 참고 |