Kingfisher API Dokümantasyonu: Geliştiriciler İçin Tam Rehber

Giriş: Kripto Verilerine Programlı Erişim

Kingfisher API, geliştiricilerin ve algoritmik trader'ların kripto piyasası verilerine programlı olarak erişmesini sağlayan güçlü bir REST API'dir. Pro plan kullanıcıları için mevcuttur.

Bu dokümantasyonda öğrenecekleriniz:

• API'ye nasıl başlanır
• Authentication ve anahtar yönetimi
• Temel endpoint'ler ve kullanım
• Python ve JavaScript örnekleri
• Rate limiting ve best practices
• Sıkça sorulan sorular

API'ye Başlama

Ön Koşullar

Gereksinimler:

1. Pro Plan Aboneliği:
   - API erişimi Pro planla sınırlıdır
   - Standard plan API erişimi yoktur
   - Upgrade gerekli

2. API Anahtarı:
   - Dashboard'dan生成
   - Production ve test anahtarları
   - Güvenli saklama şart

3. Temel Programlama Bilgisi:
   - HTTP istekleri
   - JSON parsing
   - Authentication (Bearer token)
   - Python veya JavaScript (tercihen)

API Anahtarı Oluşturma

Adım Adım:

1. Kingfisher Dashboard'a Giriş:
   URL: https://app.thekingfisher.io/dashboard
   Giriş yapın

2. Ayarlar → API Sekmesi:
   - "API Keys" seçeneği
   - "Create New Key" butonu

3. Anahtar Bilgileri:
   - İsim: "Production" veya "Test"
   - Kısıtlamalar: IP adresi (opsiyonel ama önerili)
   - "Create" ile oluştur

4. Anahtarı Kaydet:
   - API key'i kopyalayın (sadece bir kez gösterilir)
   - Güvenli bir yere saklayın
   - Asla paylaşmayın veya commit etmeyin

5. Test Etme:
   - İlk istek ile test edin
   - Anahtarın çalıştığını doğrulayın

Anahtar Türleri:

Production Key:
- Gerçek trading için
- Canlı veri erişimi
- Rate limits: Daha yüksek
- Production kullanımı şart

Test Key:
- Geliştirme için
- Sandbox data
- Rate limits: Daha düşük
- Ücretsiz test

Öneri:
- Her iki anahtarı da oluşturun
- Geliştirme'de test key kullanın
- Production'da production key kullanın

Authentication

Bearer Token Authentication

Tüm İstekler İçin:

HTTP Header:
Authorization: Bearer YOUR_API_KEY

Örnek:
curl -H "Authorization: Bearer sk_live_xxxxx" \\
     https://api.thekingfisher.io/v1/liquidation-map

Not:
- API key'iniz "sk_live_" ile başlar
- Header her istekte gerekli
- Key'i güvende tutun

Python Örneği:

import requests

API_KEY = "sk_live_xxxxx"
BASE_URL = "https://api.thekingfisher.io/v1"

headers = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json"
}

response = requests.get(
    f"{BASE_URL}/liquidation-map",
    headers=headers
)

data = response.json()
print(data)

JavaScript Örneği:

const API_KEY = "sk_live_xxxxx";
const BASE_URL = "https://api.thekingfisher.io/v1";

fetch(`${BASE_URL}/liquidation-map`, {
    headers: {
        'Authorization': `Bearer ${API_KEY}`,
        'Content-Type': 'application/json'
    }
})
.then(response => response.json())
.then(data => console.log(data));

Temel Endpoint'ler

1. Liquidation Map

Endpoint:

GET /v1/liquidation-map

Açıklama:
Belirli bir coin için liquidation map verilerini
gerçek zamanlı olarak getirir.

Query Parametreleri:
- symbol (zorunlu): "BTC", "ETH", vb.
- exchange (opsiyonel): "binance", "all" (varsayılan)
- timeframe (opsiyonel): "1h", "4h", "1d" (varsayılan: "4h")

Response:
{
  "symbol": "BTC",
  "price": 50000.00,
  "clusters": [
    {
      "price": 48000,
      "long_amount": 1000000000,
      "short_amount": 200000000,
      "exchange": "binance"
    },
    ...
  ],
  "updated_at": "2026-02-04T02:30:00Z"
}

Python Örneği:

import requests

def get_liquidation_map(symbol="BTC", exchange="binance", timeframe="4h"):
    url = f"{BASE_URL}/liquidation-map"
    params = {
        "symbol": symbol,
        "exchange": exchange,
        "timeframe": timeframe
    }
    response = requests.get(url, headers=headers, params=params)
    return response.json()

# Kullanım
data = get_liquidation_map("BTC", "binance", "4h")
print(f"Bitcoin fiyatı: ${data['price']:,.2f}")
print(f"Cluster sayısı: {len(data['clusters'])}")

# En büyük long cluster'u bul
long_clusters = [c for c in data['clusters'] if c['long_amount'] > 0]
if long_clusters:
    largest_long = max(long_clusters, key=lambda x: x['long_amount'])
    print(f"En büyük long cluster: ${largest_long['price']:,.0f}")
    print(f"  Miktar: ${largest_long['long_amount']:,.0f}")

JavaScript Örneği:

async function getLiquidationMap(symbol = 'BTC', exchange = 'binance', timeframe = '4h') {
    const params = new URLSearchParams({
        symbol: symbol,
        exchange: exchange,
        timeframe: timeframe
    });

    const response = await fetch(`${BASE_URL}/liquidation-map?${params}`, {
        headers: {
            'Authorization': `Bearer ${API_KEY}`,
            'Content-Type': 'application/json'
        }
    });

    return await response.json();
}

// Kullanım
getLiquidationMap('BTC', 'binance', '4h')
    .then(data => {
        console.log(`Bitcoin fiyatı: $${data.price.toLocaleString()}`);
        console.log(`Cluster sayısı: ${data.clusters.length}`);

        // En büyük long cluster'u bul
        const longClusters = data.clusters.filter(c => c.long_amount > 0);
        if (longClusters.length > 0) {
            const largestLong = longClusters.reduce((a, b) =>
                a.long_amount > b.long_amount ? a : b
            );
            console.log(`En büyük long cluster: $${largestLong.price.toLocaleString()}`);
            console.log(`  Miktar: $${largestLong.long_amount.toLocaleString()}`);
        }
    });

2. GEX+ (Gamma Exposure)

Endpoint:

GET /v1/gex

Açıklama:
Belirli bir coin için GEX+ (Gamma Exposure)
verilerini getirir.

Query Parametreleri:
- symbol (zorunlu): "BTC", "ETH", vb.
- exchange (opsiyonel): "all" (varsayılan)

Response:
{
  "symbol": "BTC",
  "gex_value": 800000000,
  "gex_percentile": 75,
  "dealer_positioning": "long_gamma",
  "updated_at": "2026-02-04T02:30:00Z"
}

Python Örneği:

def get_gex(symbol="BTC"):
    url = f"{BASE_URL}/gex"
    params = {"symbol": symbol}
    response = requests.get(url, headers=headers, params=params)
    return response.json()

# Kullanım
data = get_gex("BTC")
print(f"GEX+ Değeri: ${data['gex_value']:,.0f}")
print(f"Percentile: {data['gex_percentile']}th")

# Yorumlama
if data['gex_value'] > 1000000000:
    print("→ Çok yüksek GEX+ (stabilizing)")
elif data['gex_value'] > 0:
    print("→ Pozitif GEX+ (stabilizing)")
elif data['gex_value'] < -1000000000:
    print("→ Çok düşük GEX+ (volatilite artırıcı)")
else:
    print("→ Negatif GEX+ (volatilite artırıcı)")

3. Open Interest

Endpoint:

GET /v1/open-interest

Açıklama:
Belirli bir coin için Open Interest
verilerini getirir.

Query Parametreleri:
- symbol (zorunlu): "BTC", "ETH", vb.
- exchange (opsiyonel): "all" (varsayılan)
- timeframe (opsiyonel): "1d" (varsayılan)

Response:
{
  "symbol": "BTC",
  "oi_value": 12000000000,
  "oi_change_24h": 0.15,
  "oi_change_7d": 0.25,
  "updated_at": "2026-02-04T02:30:00Z"
}

Python Örneği:

def get_open_interest(symbol="BTC"):
    url = f"{BASE_URL}/open-interest"
    params = {"symbol": symbol}
    response = requests.get(url, headers=headers, params=params)
    return response.json()

# Kullanım
data = get_open_interest("BTC")
print(f"Open Interest: ${data['oi_value']/1e9:.2f}B")
print(f"24 Saat Değişim: %{data['oi_change_24h']*100:.1f}")
print(f"7 Gün Değişim: %{data['oi_change_7d']*100:.1f}")

# Trend analizi
if data['oi_change_24h'] > 0.1:
    print("→ Güçlü artış (para girişi)")
elif data['oi_change_24h'] > 0:
    print("→ Hafif artış")
else:
    print("→ Azalış (para çıkışı)")

4. Funding Rate

Endpoint:

GET /v1/funding-rate

Açıklama:
Belirli bir coin için funding rate
verilerini getirir.

Query Parametreleri:
- symbol (zorunlu): "BTC", "ETH", vb.
- exchange (opsiyonel): "all" (varsayılan)

Response:
{
  "symbol": "BTC",
  "current_rate": 0.0001,
  "predicted_rate": 0.00012,
  "avg_24h": 0.00008,
  "next_funding_time": "2026-02-04T08:00:00Z"
}

Python Örneği:

def get_funding_rate(symbol="BTC"):
    url = f"{BASE_URL}/funding-rate"
    params = {"symbol": symbol}
    response = requests.get(url, headers=headers, params=params)
    return response.json()

# Kullanım
data = get_funding_rate("BTC")
print(f"Mevcut Funding: %{data['current_rate']*100:.3f}")
print(f"Tahmini Funding: %{data['predicted_rate']*100:.3f}")
print(f"24 Saat Ortalama: %{data['avg_24h']*100:.3f}")

# Extreme kontrolü
if data['current_rate'] > 0.0005:
    print("⚠️  EXTREME POZİTİF (long'lar öder)")
elif data['current_rate'] < -0.0005:
    print("⚠️  EXTREME NEGATİF (short'lar öder)")
elif data['current_rate'] > 0:
    print("→ Pozitif (normal)")
else:
    print("→ Negatif (normal)")

5. Long/Short Ratio

Endpoint:

GET /v1/long-short-ratio

Açıklama:
Belirli bir coin için long/short ratio
verilerini getirir.

Query Parametreleri:
- symbol (zorunlu): "BTC", "ETH", vb.
- exchange (opsiyonel): "all" (varsayılan)

Response:
{
  "symbol": "BTC",
  "ls_ratio": 1.5,
  "long_percent": 60.0,
  "short_percent": 40.0,
  "updated_at": "2026-02-04T02:30:00Z"
}

Python Örneği:

def get_long_short_ratio(symbol="BTC"):
    url = f"{BASE_URL}/long-short-ratio"
    params = {"symbol": symbol}
    response = requests.get(url, headers=headers, params=params)
    return response.json()

# Kullanım
data = get_long_short_ratio("BTC")
print(f"L/S Ratio: {data['ls_ratio']:.2f}")
print(f"Long: %{data['long_percent']:.1f}")
print(f"Short: %{data['short_percent']:.1f}")

# Extreme kontrolü
if data['ls_ratio'] > 3.0:
    print("⚠️  EXTREME LONG (tepe sinyali)")
elif data['ls_ratio'] < 0.33:
    print("⚠️  EXTREME SHORT (dip sinyali)")
elif data['ls_ratio'] > 1.0:
    print("→ Long dominance")
else:
    print("→ Short dominance")

Rate Limiting

Limits ve Best Practices

Rate Limits:

Pro Plan Limits:
- 100 istek / dakika
- 2,000 istek / saat
- 40,000 istek / gün

Test Plan Limits:
- 20 istek / dakika
- 400 istek / saat
- 8,000 istek / gün

Headers:
X-RateLimit-Remaining: Kalan istek sayısı
X-RateLimit-Reset: Reset zamanı (Unix timestamp)

Best Practices:

1. Rate Limit Takibi:
   - Response headers'ı kontrol edin
   - Kalan istekleri izleyin
   - Reset zamanını bilin

2. Caching:
   - Sık değişmeyen veriyi cache'leyin
   - 1-5 dakika cache yeterli
   - Rate limit kullanımını azaltır

3. Retry Logic:
   - 429 (Too Many Requests) alırsanız bekleyin
   - Exponential backoff kullanın
   - Maksimum 3 deneme

4. Batch Requests:
   - Birden fazla endpoint'i çağırmak yerine
   - Batch endpoint'i kullanın (varsa)
   - Daha verimli

Python Rate Limiting Örneği:

import time
import requests
from requests.adapters import HTTPAdapter
from urllib3.util.retry import Retry

def create_session():
    session = requests.Session()

    # Retry strategy
    retry = Retry(
        total=3,
        backoff_factor=1,
        status_forcelist=[429, 500, 502, 503, 504]
    )
    adapter = HTTPAdapter(max_retries=retry)
    session.mount('https://', adapter)

    return session

def make_request(session, url, params=None, max_retries=3):
    for attempt in range(max_retries):
        response = session.get(url, headers=headers, params=params)

        # Rate limit kontrolü
        remaining = int(response.headers.get('X-RateLimit-Remaining', 0))
        reset = int(response.headers.get('X-RateLimit-Reset', 0))

        if remaining < 5:
            # Rate limit yaklaşıyor, bekle
            wait_time = max(1, reset - int(time.time()))
            print(f"Rate limit yaklaşıyor, {wait_time} saniye bekleniyor...")
            time.sleep(wait_time)

        if response.status_code == 429:
            # Rate limit aşıldı, bekle ve retry
            wait_time = 2 ** attempt  # Exponential backoff
            print(f"Rate limit aşıldı, {wait_time} saniye bekleniyor...")
            time.sleep(wait_time)
            continue

        return response

    return None

# Kullanım
session = create_session()
data = make_request(session, f"{BASE_URL}/liquidation-map", params={"symbol": "BTC"})

Kompleks Örnekler

Multi-Coin Analiz Script

Python Örneği:

import requests
import pandas as pd
from datetime import datetime

class KingfisherAnalyzer:
    def __init__(self, api_key):
        self.api_key = api_key
        self.base_url = "https://api.thekingfisher.io/v1"
        self.headers = {
            "Authorization": f"Bearer {api_key}",
            "Content-Type": "application/json"
        }

    def get_liquidation_map(self, symbol):
        params = {"symbol": symbol}
        response = requests.get(
            f"{self.base_url}/liquidation-map",
            headers=self.headers,
            params=params
        )
        return response.json()

    def get_gex(self, symbol):
        params = {"symbol": symbol}
        response = requests.get(
            f"{self.base_url}/gex",
            headers=self.headers,
            params=params
        )
        return response.json()

    def get_open_interest(self, symbol):
        params = {"symbol": symbol}
        response = requests.get(
            f"{self.base_url}/open-interest",
            headers=self.headers,
            params=params
        )
        return response.json()

    def get_funding_rate(self, symbol):
        params = {"symbol": symbol}
        response = requests.get(
            f"{self.base_url}/funding-rate",
            headers=self.headers,
            params=params
        )
        return response.json()

    def get_long_short_ratio(self, symbol):
        params = {"symbol": symbol}
        response = requests.get(
            f"{self.base_url}/long-short-ratio",
            headers=self.headers,
            params=params
        )
        return response.json()

    def analyze_coin(self, symbol):
        """Tüm verileri topla ve analiz et"""
        print(f"\n{'='*60}")
        print(f"{symbol} Analizi")
        print(f"{'='*60}")

        # Tüm verileri al
        lm = self.get_liquidation_map(symbol)
        gex = self.get_gex(symbol)
        oi = self.get_open_interest(symbol)
        fr = self.get_funding_rate(symbol)
        ls = self.get_long_short_ratio(symbol)

        # Fiyat
        print(f"\nFiyat: ${lm['price']:,.2f}")

        # Liquidation map
        long_clusters = [c for c in lm['clusters'] if c['long_amount'] > 0]
        if long_clusters:
            largest_long = max(long_clusters, key=lambda x: x['long_amount'])
            print(f"\nEn Büyük Long Cluster:")
            print(f"  Seviye: ${largest_long['price']:,.0f}")
            print(f"  Miktar: ${largest_long['long_amount']/1e9:.2f}B")

        # GEX+
        print(f"\nGEX+: ${gex['gex_value']/1e6:.0f}M")
        print(f"  Percentile: {gex['gex_percentile']}th")
        print(f"  Dealer: {gex['dealer_positioning']}")

        # Open Interest
        print(f"\nOpen Interest: ${oi['oi_value']/1e9:.2f}B")
        print(f"  24S Değişim: %{oi['oi_change_24h']*100:.1f}")

        # Funding Rate
        print(f"\nFunding Rate: %{fr['current_rate']*100:.3f}")

        # Long/Short Ratio
        print(f"\nL/S Ratio: {ls['ls_ratio']:.2f}")
        print(f"  Long: %{ls['long_percent']:.1f}")
        print(f"  Short: %{ls['short_percent']:.1f}")

        # Sinyal analizi
        signals = self.generate_signals(lm, gex, oi, fr, ls)
        print(f"\nSinyaller:")
        for signal in signals:
            print(f"  {signal}")

    def generate_signals(self, lm, gex, oi, fr, ls):
        """Trading sinyalleri oluştur"""
        signals = []

        # Liquidation map sinyali
        long_clusters = [c for c in lm['clusters'] if c['long_amount'] > 500_000_000]
        if long_clusters:
            largest_long = max(long_clusters, key=lambda x: x['long_amount'])
            if lm['price'] - largest_long['price'] < lm['price'] * 0.05:
                signals.append(f"💰 Yakın long cluster @ ${largest_long['price']:,.0f}")

        # GEX+ sinyali
        if gex['gex_value'] > 1_000_000_000:
            signals.append("✅ Çok yüksek GEX+ (stabilizing)")
        elif gex['gex_value'] < -1_000_000_000:
            signals.append("⚠️  Çok düşük GEX+ (volatilite artırıcı)")

        # Open Interest sinyali
        if oi['oi_change_24h'] > 0.2:
            signals.append("📈 Güçlü OI artışı (trend güçleniyor)")
        elif oi['oi_change_24h'] < -0.1:
            signals.append("📉 OI azalışı (trend zayıflıyor)")

        # Funding rate sinyali
        if fr['current_rate'] > 0.0005:
            signals.append("🔥 Extreme pozitif funding (tepe riski)")
        elif fr['current_rate'] < -0.0005:
            signals.append("❄️  Extreme negatif funding (dip fırsatı)")

        # Long/Short ratio sinyali
        if ls['ls_ratio'] > 3.0:
            signals.append("⚠️  Extreme long (tepe sinyali)")
        elif ls['ls_ratio'] < 0.33:
            signals.append("💚 Extreme short (dip sinyalı)")

        return signals

# Kullanım
analyzer = KingfisherAnalyzer("sk_live_xxxxx")

# Birden fazla coin analizi
coins = ["BTC", "ETH", "SOL"]
for coin in coins:
    analyzer.analyze_coin(coin)
    time.sleep(1)  # Rate limit için bekle

Hata Yönetimi

Hata Türleri ve Çözümleri

Yaygın Hatalar:

1. 401 Unauthorized:
   - API key yanlış veya eksik
   - Çözüm: API key'i kontrol edin

2. 403 Forbidden:
   - Yetersiz izinler
   - Çözüm: Pro plan'a upgrade edin

3. 404 Not Found:
   - Endpoint yanlış
   - Çözüm: URL'i kontrol edin

4. 429 Too Many Requests:
   - Rate limit aşıldı
   - Çözüm: Bekleyin ve retry edin

5. 500 Internal Server Error:
   - Sunucu hatası
   - Çözüm: Retry edin

Python Hata Yönetimi:

import requests
from requests.exceptions import RequestException

def safe_api_call(url, params=None, max_retries=3):
    for attempt in range(max_retries):
        try:
            response = requests.get(url, headers=headers, params=params)

            # Başarılı
            if response.status_code == 200:
                return response.json()

            # Hata durumları
            elif response.status_code == 401:
                raise Exception("API key yanlış veya eksik")

            elif response.status_code == 403:
                raise Exception("Pro plan gerekli")

            elif response.status_code == 404:
                raise Exception("Endpoint bulunamadı")

            elif response.status_code == 429:
                # Rate limit, bekle ve retry
                wait_time = 2 ** attempt
                print(f"Rate limit, {wait_time}s bekleniyor...")
                time.sleep(wait_time)
                continue

            elif response.status_code >= 500:
                # Sunucu hatası, retry
                if attempt < max_retries - 1:
                    time.sleep(1)
                    continue
                else:
                    raise Exception(f"Sunucu hatası: {response.status_code}")

        except RequestException as e:
            if attempt < max_retries - 1:
                time.sleep(1)
                continue
            else:
                raise Exception(f"İstek hatası: {e}")

    return None

# Kullanım
try:
    data = safe_api_call(f"{BASE_URL}/liquidation-map", params={"symbol": "BTC"})
    print(data)
except Exception as e:
    print(f"Hata: {e}")

Sıkça Sorulan Sorular (FAQ)

S1: API'ye nasıl erişirim?

Cevap:
Pro plan aboneliği gerekli.

Adımlar:
1. Pro plan'a upgrade edin ($109/ay)
2. Dashboard'dan API key oluşturun
3. Documentation'ı okuyun
4. Test edin

Test Key:
- Geliştirme için test key kullanın
- Production'da production key kullanın

S2: Rate limit nedir?

Cevap:
Pro plan: 100 istek/dakika
Test plan: 20 istek/dakika

Aşıldığında:
- 429 hatası alırsınız
- Beklemeli ve retry etmelisiniz
- Response headers'da bilgi var

Best Practice:
- Caching kullanın
- Batch requests yapın
- Rate limit'i izleyin

S3: Webhook desteği var mı?

Cevap:
Şu anda yok, ama planlanıyor.

Alternatif:
- Polling (periyodik istek)
- WebSocket planlanıyor
- Product roadmap'da

Şu anda:
- Sık polling (her 1-5 dakika)
- Rate limit'e dikkat
- Caching kullanın

Sonuç: Kripto Verilerine Erişin

Önemli Noktalar

Kingfisher API Özeti:

Öğrendikleriniz:
1. API'ye başlama
2. Authentication
3. Temel endpoint'ler
4. Python ve JavaScript örnekleri
5. Rate limiting
6. Hata yönetimi

Kingfisher API Avantajları:
- %100 doğru veri
- Gerçek zamanlı güncelleme
- Tüm borsalar entegre
- Detaylı dokümantasyon
- Python/JavaScript örnekleri

Başarı İçin Kurallar:

1. Güvenlik:
   - API key'i güvende tutun
   - Production ve test key ayrın
   - Git'e commit etmeyin

2. Rate Limit:
   - Limits'i izleyin
   - Caching kullanın
   - Retry logic implement edin

3. Hata Yönetimi:
   - Tüm hataları handle edin
   - Graceful degradation
   - Loglama

4. Best Practices:
   - Sık değişmeyen veriyi cache'leyin
   - Batch requests yapın
   - Asynchronous çağrılar kullanın

Pro Plan'a Upgrade Edin

Kaynaklar:

• API Documentation
• Python SDK
• JavaScript SDK
• Support

Geliştirmeye Başlayın →