API של מפת הליקווידציות

ה-API של מפת הליקווידציות מראה באילו רמות מחיר, ביחס למחיר הנוכחי, ייסגרו בכפייה פוזיציות ממונפות בחוזים עתידיים צמיתים (perpetual futures): כמה דולרים של פוזיציות לונג יעברו ליקווידציה אם המחיר ירד לכל רמה, וכמה דולרים של פוזיציות שורט אם יעלה אליה. מפה אחת ליום, עבור 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

איך נבנות המפות, מה מייצג דלי (bucket) ומה הראיות מלמדות עליהן: מתודולוגיית מפת הליקווידציות.

לא איתות מסחר

מפת הליקווידציות היא כלי תיאורי — לא יעד מחיר ולא איתות מסחר.

נקודות קצה

מתודה	נתיב	תיאור
`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 — 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, כולל מדד כיסוי ביחס ל-Open Interest של הבורסה);
- 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`	תא המחיר (bin) של `/heatmap` עבור מטבע זה
`warmup_complete_from`	היום הראשון עם חלון מודל מלא של 180 יום (שווה ל-`first_day` אלא אם המטבע נכנס למסחר בתוך תקופת ההיסטוריה)
`latest`	המפה האחרונה: `day`, `kind`, `snapshot_ts`, `mark`, `coverage` (סריקות Hyperliquid)
`model`	פרמטרי מודל Binance: חלון, רמות מינוף ומשקליהן, חלוקה בין הצדדים, מרווח שימור (maintenance margin) לכל מטבע

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`	USD מצטבר מ-`mark` כלפי מטה (לונג) או כלפי מעלה (שורט) עד לדלי זה
`peaks`	עד 5 הדליים הגדולים ביותר בכל צד, המרוחקים זה מזה ב-3% לפחות מהמחיר; `dist` = price / mark − 1
`summary`	סכומים כוללים בטווח ±50% מהמחיר, נפח מעבר לטווח זה (`beyond_span_`), פוזיציות שכבר חצו את המחיר במהלך סריקה (`past_mark`), 20 הפוזיציות הגדולות ביותר בכל צד (`top20_*_usd`)
`coverage`	סריקות Hyperliquid בלבד: גודל הלונג/שורט שנמצא ÷ מחצית ה-Open Interest בבורסה; `ok` = שניהם ≥ 0.99. `null` עבור ארכיונים, ימים משוחזרים והמודל
`quality`	נתוני אבחון (משך הסריקה, כתובות, חלון המודל והפרמטרים שלו, `warmup_days` / `warmup_complete`, שעות חסרות); מיועדים להצגה בתיבת ריחוף (hover), לא ללוגיקה. עבור יום משוחזר ראו ימים משוחזרים

ימים משוחזרים

עבור 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`	חלק השווי הנקוב (notional) שהביטחונות שלו נלקחו מהעוגן הקודם, מהעוגן הבא או מהנחה (חשבונות שנפתחו במהלך הפער)
`positions`, `ledger_accounts`	מספר הפוזיציות במפה ומספר החשבונות שההעברות שלהם הורצו מחדש
`coin_warning`	`"reduced_accuracy"` עבור HYPE, אחרת `null`

השחזור אומת מול תמונות מצב אמיתיות (51 ימים): בממוצע 56% מחמשת האשכולות הגדולים בכל צד נמצאים בטווח ±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 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​

מגבלות וגודל התגובה​

עדכונים ושמירה במטמון​

שגיאות​