Likidasyon Haritası API'si

Likidasyon Haritası API'si, kaldıraçlı perpetual vadeli işlem pozisyonlarının zorla kapatılacağı seviyelerin güncel fiyata göre nerede toplandığını gösterir: fiyat her bir seviyeye düşerse kaç ABD doları değerinde long pozisyonun, yükselirse kaç dolarlık short pozisyonun likide olacağı. BTC, ETH, SOL ve HYPE için her gün bir harita yayımlanır.

İki kaynak her zaman ayrı ayrı döndürülür ve ayrı ayrı etiketlenmelidir:

`source`	Etiket	Nedir	Coinler	Geçmiş
`hyperliquid`	Hyperliquid — gerçek pozisyonlar	Olgular: her pozisyon sahibi için okunan pozisyonlar ve likidasyon fiyatları.	BTC, ETH, SOL, HYPE	2025-07-29'dan itibaren
`binance_model`	Binance — model	Bir tahmin: Binance pozisyonları açıklamaz, bu nedenle seviyeler kamuya açık açık pozisyon (open interest) verisi ve saatlik mumlardan modellenir.	BTC, ETH, SOL, HYPE	2023-01-01'den itibaren; HYPE 2025-06-06'dan itibaren

Haritaların nasıl oluşturulduğu, bir kovanın (bucket) neyi ifade ettiği ve verilerin haritalar hakkında ne gösterdiği için bkz.: Likidasyon Haritası Metodolojisi.

Bir işlem sinyali değildir

Likidasyon haritası betimleyici bir araçtır; bir fiyat hedefi veya işlem sinyali değildir.

Uç Noktalar

Yöntem	Yol	Açıklama
`GET`	`/v1/liqmap/meta`	Kaynaklar, coinler, geçmiş kapsamı, boşluklar, en son anlık görüntü
`GET`	`/v1/liqmap/map`	Tek bir günün seviyeleri (varsayılan: en son harita)
`GET`	`/v1/liqmap/heatmap`	Isı haritası için gün × fiyat matrisi

Temel URL: https://api.blocklens.co. Tüm yanıtlar JSON formatındadır: {"success": true, "data": {…}}.

Kimlik Doğrulama

Tüm istekler bir API anahtarı gerektirir:

Authorization: Bearer YOUR_API_KEY

API anahtarları için Kimlik Doğrulama, hangi planların API erişimi içerdiği ve istek limitleri için Hız Limitleri ve Abonelik Seviyeleri sayfalarına bakın.

Abonelik seviyeleri ve geçmiş

Geçmiş penceresi yalnızca Lab arayüzünde değil, doğrudan API düzeyinde uygulanır:

Seviye	Güncel harita	Geçmiş (`/map?date=`, `/heatmap`)
Free	evet	son 30 gün
Pro, Enterprise	evet	tümü (Hyperliquid 2025-07-29'dan, Binance modeli 2023-01-01'den itibaren)

Her yanıt bir access bloğu içerir:

"access": {"tier": "free", "grade": 0, "full_history": false, "history_from": "2026-09-21", "clipped": false}

history_from — çağıranın görebileceği ilk gün (tam geçmiş için null).
clipped — /heatmap için history_from öncesindeki günler istendiğinde ve bunlar kesildiğinde true.
history_from öncesindeki bir gün için /map 403 döndürür (bkz. Hatalar). /heatmap ise bu nedenle hiçbir zaman 403 döndürmez: izin verilen kısmı döndürür ve clipped alanını ayarlar.

Günler ve anlık görüntü zamanı

snapshot_ts — haritanın betimlediği an (UTC, ISO 8601); day — bu anın UTC tarihi.
Hyperliquid üç tür anlık görüntüye sahiptir:
- kind = "scan" — her pozisyon sahibine yönelik günlük taramamız (yaklaşık 02:00–03:40 UTC, borsanın açık pozisyon verisine göre kapsam bilgisiyle);
- kind = "archive" — arşivlenmiş tam borsa durumu (geçmiş; yaklaşık iki günlük gecikmeyle yayımlanır, gün içindeki saati değişkendir — her zaman snapshot_ts değerini okuyun);
- kind = "reconstructed" — arşivlenmiş anlık görüntüsü olmayan bir gün için tahmin (2025-08-01 ve 2025-10-25 … 2025-12-14). Pozisyonlar, komşu arşivlenmiş anlık görüntüler arasındaki borsa işlemleri ve hesap transferlerinden, day gününün 00:05 UTC anı için yeniden oluşturulur: büyüklükler ve giriş fiyatları kesindir, likidasyon fiyatları tahminidir. HYPE için doğruluk düşüktür. Yeniden oluşturulmuş bir satır asla gerçek bir satırın yerini almaz.
Bir gün için hangi türün döndürüldüğü: /map — scan, yoksa archive, yoksa reconstructed; bir /heatmap satırı — archive, yoksa scan, yoksa reconstructed. Güncel harita en son taramadır.
Binance modeli: kind = "model", day gününün 00:00 UTC anındaki durum, 180 günlük bir pencereden oluşturulur. Bu pencere içinde listelenen bir coin için (HYPE, 2025-05-30'da listelendi) ilk aylar kısmi bir ısınma dönemidir: /meta içindeki warmup_complete_from, /map içindeki quality.warmup_complete ve /heatmap içindeki warmup alanlarına bakın.

GET /v1/liqmap/meta

Parametre yoktur. Verisi bulunan her kaynağı ve coini listeler.

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}
  }
}

Alan	Anlamı
`first_day`, `last_day`, `days`	Haritası olan günler (tüm türler birlikte)
`gaps`, `gaps_detail`	Hiç haritası olmayan gün aralıkları; `cause`: `source` — kaynakta veri yok ve hiçbir şey yeniden oluşturulmadı, kalıcı; `pipeline` — bizim tarafımızda kaçırıldı, yeniden oluşturulabilir. Yeniden oluşturulmuş günler boşluk değildir
`reconstructed`	Yalnızca `kind = "reconstructed"` (tahminler) ile sunulan gün aralıkları: `from`, `to`, `days`, `cause` (`source`), sabit bir `reason`, `warning` — `null` veya `"reduced_accuracy"` (HYPE). Hiç yoksa `[]`. Hyperliquid: 2025-08-01 ve 2025-10-25 … 2025-12-14
`heatmap_bin`	Bu coin için `/heatmap` fiyat aralığı (bin)
`warmup_complete_from`	Tam 180 günlük model penceresine sahip ilk gün (coin geçmiş dönem içinde listelenmediyse `first_day` ile aynıdır)
`latest`	En son harita: `day`, `kind`, `snapshot_ts`, `mark`, `coverage` (Hyperliquid taramaları)
`model`	Binance modeli parametreleri: pencere, ağırlıklarıyla kaldıraçlar, taraf dağılımı, coin başına sürdürme teminatı (maintenance margin)

GET /v1/liqmap/map

Parametre	Varsayılan	Açıklama
`source`	zorunlu	`hyperliquid` veya `binance_model`
`coin`	`BTC`	`BTC`, `ETH`, `SOL`, `HYPE`
`variant`	`all`	`ex_top20` — taraf başına en büyük 20 pozisyon hariç (yalnızca Hyperliquid)
`date`	en son	`YYYY-MM-DD`; abonelik seviyesi penceresine göre kontrol edilir
`kind`	`scan`, yoksa `archive`, yoksa `reconstructed`	Yalnızca Hyperliquid: `scan`, `archive` veya `reconstructed`. `kind` ile döndürülen gün abonelik seviyesi penceresine göre kontrol edilir
`price_min`, `price_max`	fiyatın ±%50'si	`levels` listesini kırpar; kümülatif toplamlar yine tam haritadan hesaplanır

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}
  }
}

Alan	Anlamı
`levels`	Fiyata göre artan sırada, eşit genişlikte `[low, high)` kovaları; genişlikleri fiyatın yaklaşık %0,25'i kadardır (`step`). `long_usd` — fiyat kovaya düşerse likide olacak long pozisyonlar (yalnızca `mark` altında); `short_usd` — fiyat kovaya yükselirse likide olacak short pozisyonlar (yalnızca `mark` üstünde). USD = \|büyüklük\| × likidasyon fiyatı
`n_long`, `n_short`	Kovadaki pozisyon sayısı (Hyperliquid; model için `0`)
`long_cum`, `short_cum`	`mark` seviyesinden bu kovaya kadar aşağı (long) veya yukarı (short) kümülatif USD
`peaks`	Taraf başına en fazla 5 en büyük kova, birbirinden en az fiyatın %3'ü kadar uzakta; `dist` = fiyat / mark − 1
`summary`	Fiyatın ±%50'si içindeki toplamlar, bu aralığın ötesindeki hacim (`beyond_span_`), tarama sırasında fiyatı zaten geçmiş pozisyonlar (`past_mark`), taraf başına en büyük 20 pozisyon (`top20_*_usd`)
`coverage`	Yalnızca Hyperliquid taramaları: bulunan long/short büyüklüğü ÷ borsa açık pozisyonunun yarısı; `ok` = her ikisi de ≥ 0.99. Arşivler, yeniden oluşturulmuş günler ve model için `null`
`quality`	Tanılama bilgileri (tarama süresi, adresler, model penceresi ve parametreleri, `warmup_days` / `warmup_complete`, eksik saatler); uygulama mantığında kullanılmak için değil, araç ipucunda (tooltip) göstermek içindir. Yeniden oluşturulmuş bir gün için bkz. Yeniden oluşturulmuş günler

Yeniden oluşturulmuş günler

kind = "reconstructed" için coverage değeri null olur ve quality tahmini betimler:

"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}

Alan	Anlamı
`method`	Yeniden oluşturma yönteminin sürümü
`anchor_prev`, `anchor_next`	Arşivlenmiş anlık görüntüsü olan komşu günler
`days_to_anchor`	Daha yakın çapaya gün cinsinden uzaklık — doğruluğu belirleyen ana etken
`share_prev`, `share_next`, `share_assumed`	Teminatı önceki çapadan, sonraki çapadan veya bir varsayımdan (boşluk döneminde yeni açılan hesaplar) gelen nominal değer payları
`positions`, `ledger_accounts`	Haritadaki pozisyonlar ve transferleri yeniden oynatılan hesaplar
`coin_warning`	HYPE için `"reduced_accuracy"`, aksi halde `null`

Gerçek anlık görüntülerle doğrulama (51 gün): taraf başına ilk 5 kümenin ortalama %56'sı gerçek kümelerin ±%1'i içinde kalıyor — bir çapaya 1–3 gün uzaklıkta %68, 22–26 gün uzaklıkta %46. Bu günler mutlaka tahmin olarak etiketlenmelidir.

GET /v1/liqmap/heatmap

Parametre	Varsayılan	Açıklama
`source`, `coin`, `variant`	`/map` ile aynı
`from_date`	izin verilen ilk gün	Abonelik seviyesi penceresinden önceyse → kesilir, `access.clipped = true`
`to_date`	en son gün
`price_min`, `price_max`	döndürülen günlerin en düşük fiyatının 0.5 katı … en yüksek fiyatının 1.5 katı	Bin ızgarasına hizalanır

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 dizilerinin j satırı days[j] gününün haritasıdır; i sütunu [price_lo + i·bin, price_lo + (i+1)·bin) fiyat aralığıdır (bin). Değerler tam sayı USD'dir. Long değerleri yalnızca o günün fiyatının altında, short değerleri yalnızca üstünde sıfırdan farklıdır.
Bin'ler: BTC $500, ETH $20, SOL $0.5, HYPE $0.25 — her iki kaynak için aynı ızgara.
Haritası olmayan günler days içinde yer almaz (boş satır yoktur).
marks[j] — snapshot_ts[j] anındaki fiyat; close[j] — days[j] gününün UTC günlük kapanışı (BTC, ETH, SOL; HYPE ve henüz kapanmamış bir gün için null).
kinds[j] — satırın türü; "reconstructed" bir tahmini işaretler (taralı veya soluk gösterin).
warmup[j] — o günün model penceresi kısmi bir ısınma dönemiyse true.
scale.p99 — sıfır olmayan hücrelerin 99. yüzdelik dilimi; renk ölçeğini bu değerde sınırlayın.

Limitler ve yanıt boyutu

Bir ısı haritası isteği en fazla 2.000.000 hücre (gün × bin) kapsayabilir; daha büyük istekler 400 döndürür.
En büyük varsayılan istek — SOL için tam Binance modeli geçmişi (2023-01-01'den bugüne, $0.5 bin'ler) — taraf başına yaklaşık 1.390 × 777 hücre, sıkıştırılmamış JSON olarak yaklaşık 6 MB'tır. Yanıtlar aktarım sırasında gzip ile sıkıştırılır.
İlk görünüm için from_date (örneğin son 90 gün) ve/veya güncel fiyat etrafında price_min / price_max gönderin; tam geçmişi talep üzerine yükleyin.
API anahtarı başına istek limitleri: Hız Limitleri ve Abonelik Seviyeleri.

Güncellemeler ve önbellekleme

Haritalar günde bir kez oluşturulur (Binance modeli yaklaşık 01:30 UTC'de, Hyperliquid taraması 02:00 UTC'den itibaren) ve yaklaşık 05:30 UTC'ye kadar yayımlanır. Bu saate kadar en son harita bir önceki güne aittir.
Yanıtlar, bir sonraki günlük güncellemeye kadar sunucuda önbelleğe alınır.
Aynı URL farklı abonelik seviyeleri için farklı geçmiş döndürdüğünden yanıtlar Cache-Control: private, max-age=3600 ve Vary: Authorization başlıklarıyla gönderilir — paylaşılan önbelleklerde asla saklanmazlar.

Hatalar

Durum	Ne zaman	Gövde
400	Bilinmeyen `source` / `coin` / `variant`, Binance modeli için `ex_top20`, hatalı bir tarih, sonlu olmayan veya negatif `price_min` / `price_max` ya da `price_min >= price_max`, 2.000.000 hücreyi aşan bir ısı haritası	`{"error": "Invalid parameter", "message": "…"}`
401	Eksik veya geçersiz API anahtarı
403	`history_from` öncesindeki bir gün için `/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	İstenen kaynak, coin veya gün için harita yok	`{"error": "Not found", "message": "…"}`
429	Hız limiti aşıldı	Bkz. Hız Limitleri ve Abonelik Seviyeleri

Uç Noktalar​

Kimlik Doğrulama​

Abonelik seviyeleri ve geçmiş​

Günler ve anlık görüntü zamanı​

GET /v1/liqmap/meta​

GET /v1/liqmap/map​

Yeniden oluşturulmuş günler​

GET /v1/liqmap/heatmap​

Limitler ve yanıt boyutu​

Güncellemeler ve önbellekleme​

Hatalar​