API نقشهٔ لیکوئیدیشن

API نقشهٔ لیکوئیدیشن نشان می‌دهد بسته‌شدن اجباری موقعیت‌های اهرمی در قراردادهای آتی دائمی (perpetual) در چه سطوحی نسبت به قیمت فعلی قرار دارد: اگر قیمت تا هر سطح پایین بیاید، چند دلار آمریکا از موقعیت‌های لانگ لیکویید می‌شود و اگر تا هر سطح بالا برود، چند دلار از موقعیت‌های شورت. روزانه یک نقشه برای BTC، ETH، SOL و HYPE منتشر می‌شود.

داده‌های دو منبع همیشه جدا از هم برگردانده می‌شوند و باید جدا از هم برچسب بخورند:

`source`	برچسب	چیست	کوین‌ها	تاریخچه
`hyperliquid`	Hyperliquid — موقعیت‌های واقعی	داده‌های واقعی: موقعیت‌ها و قیمت لیکوئیدیشن آن‌ها، که برای تک‌تک دارندگان خوانده می‌شود.	BTC، ETH، SOL، HYPE	از 2025-07-29
`binance_model`	Binance — مدل	تخمینی: Binance موقعیت‌ها را منتشر نمی‌کند، بنابراین سطوح بر اساس موقعیت‌های باز (open interest) عمومی و کندل‌های ساعتی مدل‌سازی می‌شوند.	BTC، ETH، SOL، HYPE	از 2023-01-01؛ HYPE از 2025-06-06

نقشه‌ها چگونه ساخته می‌شوند، هر باکت چه معنایی دارد و شواهد دربارهٔ آن‌ها چه می‌گویند: روش‌شناسی نقشهٔ لیکوئیدیشن.

سیگنال معاملاتی نیست

نقشهٔ لیکوئیدیشن ابزاری توصیفی است، نه هدف قیمتی یا سیگنال معاملاتی.

اندپوینت‌ها

متد	مسیر	توضیح
`GET`	`/v1/liqmap/meta`	منابع، کوین‌ها، پوشش تاریخچه، شکاف‌ها، آخرین اسنپ‌شات
`GET`	`/v1/liqmap/map`	سطوح یک روز (پیش‌فرض: آخرین نقشه)
`GET`	`/v1/liqmap/heatmap`	ماتریس روز × قیمت برای نقشهٔ حرارتی

آدرس پایه: 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 است.
/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)، ماه‌های نخست دورهٔ گرم‌شدن (warm-up) ناقص است: نگاه کنید به 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`	اندازهٔ بازهٔ قیمتی (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` = price / mark − 1
`summary`	مجموع‌ها در بازهٔ ±50% قیمت، حجم بیرون از این بازه (`beyond_span_`)، موقعیت‌هایی که قیمت هنگام اسکن از آن‌ها گذشته بود (`past_mark`) و 20 موقعیت بزرگ هر سمت (`top20_*_usd`)
`coverage`	فقط اسکن‌های Hyperliquid: حجم لانگ/شورت یافت‌شده ÷ نصف موقعیت‌های باز صرافی؛ `ok` = هر دو ≥ 0.99. برای آرشیوها، روزهای بازسازی‌شده و مدل برابر `null`
`quality`	اطلاعات عیب‌یابی (مدت اسکن، آدرس‌ها، پنجره و پارامترهای مدل، `warmup_days` / `warmup_complete`، ساعت‌های ازدست‌رفته)؛ برای نمایش در tooltip، نه برای منطق برنامه. برای روزهای بازسازی‌شده نگاه کنید به روزهای بازسازی‌شده

روزهای بازسازی‌شده

برای 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`	تعداد موقعیت‌های نقشه و حساب‌هایی که انتقال‌هایشان بازاجرا (replay) شده است
`coin_warning`	برای HYPE `"reduced_accuracy"`، در غیر این صورت `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 × بیشترین قیمت روزهای برگردانده‌شده	با شبکهٔ 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}
  }
}

ردیف j در long_usd / short_usd نقشهٔ روز days[j] است و ستون i بازهٔ قیمتی [price_lo + i·bin, price_lo + (i+1)·bin). مقادیر عدد صحیح و بر حسب USD هستند. لانگ‌ها فقط زیر قیمت همان روز مقدار غیرصفر دارند و شورت‌ها فقط بالای آن.
binها: BTC $500، ETH $20، SOL $0.5، HYPE $0.25 — شبکهٔ یکسان برای هر دو منبع.
روزهای بدون نقشه در days نمی‌آیند (ردیف خالی نداریم).
marks[j] — قیمت در snapshot_ts[j]؛ close[j] — قیمت بسته‌شدن روزانه (UTC) در days[j] (BTC، ETH، SOL؛ برای HYPE و روزی که هنوز تمام نشده null).
kinds[j] — نوع ردیف؛ "reconstructed" یعنی تخمین (آن را هاشورخورده یا کم‌رنگ نمایش دهید).
warmup[j] — اگر پنجرهٔ مدل در آن روز هنوز در دورهٔ گرم‌شدن (ناقص) باشد، true است.
scale.p99 — صدک 99 سلول‌های غیرصفر؛ سقف مقیاس رنگ را روی این مقدار بگذارید.

محدودیت‌ها و حجم پاسخ

هر درخواست نقشهٔ حرارتی حداکثر 2,000,000 سلول (روزها × binها) را پوشش می‌دهد؛ درخواست‌های بزرگ‌تر خطای 400 می‌گیرند.
بزرگ‌ترین درخواست پیش‌فرض — تاریخچهٔ کامل مدل Binance برای SOL (از 2023-01-01 تا امروز، binهای $0.5) — حدود 1,390 × 777 سلول در هر سمت است، یعنی حدود 6 MB 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​

محدودیت‌ها و حجم پاسخ​

به‌روزرسانی‌ها و کش​

خطاها​