Genesis Arbitrage

Genesis Arbitrage · · 11 dk okuma

İlk API isteğiniz: HTTP, başlıklar ve JSON

Kısaca

  • API'ye giden bir HTTP isteği; bir yöntemden, temel URL, yol ve parametrelerden oluşan bir adresten ve başlıklardan oluşur. Genesis API anahtarı yalnızca X-API-Key başlığında gönderilir.
  • Durum kodu bir sonraki adımı belirler: 200 verileri okuyun, 304 hiçbir şey değişmedi, 401 ve 403 anahtarı ve planı kontrol edin, 429 ve 503 Retry-After saniye bekleyin.
  • Genesis API yanıtı success, data ve meta alanlarından oluşan bir zarftır. Yüzdeler düz sayı olarak gelir (0.01 yüzde 0,01 demektir), zaman ise unix saniyesidir.
  • Yeni başlayanların sık yaptığı hatalar: URL'de anahtar, boş ortam değişkeni ve yolda ya da parametre adında yazım hatası. Parametre hatası uyarı vermez: filtrelenmiş veri yerine tüm veri seti gelir.

Bir API'yi çağırmak için programınız yöntem, adres ve başlıklardan oluşan bir HTTP isteği gönderir; sunucu ise durum kodu, kendi başlıkları ve bir gövde döndürür. Genesis API'de gövde JSON biçimindedir. İsteği terminalden curl ile ya da HTTP istemcisi olan herhangi bir dilde kodla gönderebilirsiniz. Aşağıdaki ilk istek anahtarı /account/usage ile kontrol eder, ikincisi /funding/rates üzerinden BTC fonlama oranlarını alır. API'nin ne olduğu ve onunla nelerin otomatikleştirilebileceği 1. derste anlatılıyor.

İsteğin yapısı

Aşağıdaki, curl'ün BTC fonlama oranları için sunucuya gönderdiği istektir; -v bayrağı bunu > ile başlayan satırlarda gösterir (anahtarın yerinde bir yer tutucu var):

> GET /v1/funding/rates?coin=BTC HTTP/1.1
> Host: api.genesisarbitrage.com
> User-Agent: curl/8.7.1
> Accept: */*
> X-API-Key: gns_live_XXXXXXXXXXXXXXXX
ParçaÖrnekteNe anlama gelir
YöntemGETVeri okur; Genesis API'nin tüm endpoint'leri GET'tir
Temel URLhttps://api.genesisarbitrage.com/v1Sunucu ve API sürümü
Yol/funding/ratesFonlama oranları endpoint'i
Parametreler?coin=BTCFiltre: yalnızca BTC
BaşlıkX-API-KeySunucunun hesabınızı ve planınızı tanımak için kullandığı anahtar

Parametreler ? işaretinden sonra ad=değer çiftleri olarak gelir ve & ile birleştirilir: ?coin=BTC&exchange=Binance,OKX. Genesis API filtreleri isteğe bağlıdır; coin olmadan aynı endpoint tüm coin'leri döndürür. Ondalık sayılarda nokta kullanılır, virgül asla: min_spread=0.5.

Başlıklar, adresle birlikte giden ad: değer satırlarıdır. Başlık adlarında büyük/küçük harf fark etmez (RFC 9110, bölüm 5.1): X-API-Key ile x-api-key aynı başlıktır, curl çıktısındaki küçük harfli x-request-id de X-Request-Id ile aynıdır. Genesis API anahtarı yalnızca X-API-Key içinde kabul eder.

Durum kodları

Yanıtın ilk satırı durum kodunu taşır ve programınız bundan sonra ne yapacağına buna bakarak karar verir:

KodNe anlama gelirNe yapmalı
200İstek karşılandı, veriler gövdededata ve meta alanlarını okuyun
304Veriler son yanıtınızdan beri değişmediÖnceki verileri kullanmaya devam edin
401Anahtar yok, geçersiz, iptal edilmiş veya abonelik süresi dolmuşBaşlığı ve aboneliği kontrol edin
403Endpoint planınızda yok (plan_restricted)Planı değiştirin veya isteği bırakın
429İstek, indirme veya kota limiti aşıldıRetry-After saniye bekleyin
503Veriler yeniden oluşturuluyor (snapshot_not_ready)Retry-After saniye sonra tekrar deneyin

Kotanızı yalnızca 200 harcar: 304 ve hatalar ücretsizdir, ancak saniyedeki istek limitine yine de sayılır. 304 yalnızca If-None-Match başlıklı bir isteğe döner; bu başlık ile 400, 404, 410 ve 500 kodları Genesis API yanıtları ve hataları bölümünde anlatılıyor. 429 sonrasında neden bekleme gerektiği, sözlükteki HTTP 429 Too Many Requests maddesinde açıklanıyor.

İlk istek: /account/usage

/account/usage anahtarınızın durumunu gösterir: plan, kullanılan kota ve limitler. Her planda kullanılabilir ve bir çağrı harcamaz, bu yüzden ilk isteğiniz buraya gider. Önce anahtarı bir ortam değişkenine yazın, sonra isteği gönderin:

# anahtarı yapıştırıp Enter'a basın: ekranda görünmez
read -s GENESIS_API_KEY
export GENESIS_API_KEY

curl -i "https://api.genesisarbitrage.com/v1/account/usage" \
  -H "X-API-Key: $GENESIS_API_KEY"

-i bayrağı gövdeden önce durum satırını ve başlıkları yazdırır. Yanıt gövdesi, Trial planı için örnek niteliğinde bir yanıttır:

{
  "success": true,
  "data": {
    "plan": "trial",
    "calls_used": 0,
    "calls_limit": 500000,
    "rps_limit": 1,
    "freshness_sec": 60,
    "period_resets_at": 1796463000
  },
  "meta": {
    "count": 1,
    "updated_at": 1794730811,
    "freshness_sec": 60,
    "plan": "trial"
  }
}

plan planınızdır, calls_limit içinden calls_used ise 30 günlük dönemdeki kota kullanımıdır. Örnekte 0 görünüyor, çünkü başka istek yapılmadı ve /account/usage kendisi çağrı harcamaz. rps_limit saniyedeki istek sayısı, freshness_sec planınızın verilerinin ne sıklıkla yenilendiği, period_resets_at ise kotanın ne zaman sıfırlanacağıdır. Alanlar Kullanım dokümantasyon bölümünde açıklanıyor.

Başlıklar arasında X-Request-Id değerini bulun: anahtarınız yerine destek ekibine göndereceğiniz istek kimliğidir. X-RateLimit-Remaining ise geçerli rate limit penceresinde kalan istek sayısıdır.

Aynı istek Python ile

Python 3.10+ ve requests kütüphanesiyle yazılmış bir betik, anahtarı aynı ortam değişkeninden okur:

import os
from datetime import datetime, timezone

import requests

BASE = "https://api.genesisarbitrage.com/v1"
key = os.environ["GENESIS_API_KEY"]  # tanımlı değilse KeyError

r = requests.get(
    BASE + "/account/usage",
    headers={"X-API-Key": key},
    timeout=10,  # timeout olmadan requests sonsuza kadar bekleyebilir
)
body = r.json()
if r.status_code != 200 or not body.get("success"):
    err = body.get("error") or {}
    raise SystemExit(f"{r.status_code} {err.get('code')}")

usage = body["data"]
ts = usage["period_resets_at"]
resets = datetime.fromtimestamp(ts, timezone.utc)
print("plan:", usage["plan"])
print("calls:", usage["calls_used"], "of", usage["calls_limit"])
print("quota resets:", resets.strftime("%Y-%m-%d %H:%M UTC"))
print("X-Request-Id:", r.headers.get("X-Request-Id"))

os.environ["GENESIS_API_KEY"], değişken tanımlı değilse betiği durdurur; bu, anahtarsız istek gönderip 401 almaktan iyidir. r.headers büyük/küçük harfe duyarsızdır, bu yüzden sunucu x-request-id gönderse bile X-Request-Id bulunur.

period_resets_at unix zamanıdır: 1 Ocak 1970, 00:00 UTC'den beri geçen saniye sayısı. datetime.fromtimestamp(ts, timezone.utc) bunu tarihe çevirir: 1796463000, 5 Aralık 2026, 09:30 UTC'dir.

İkinci istek: BTC fonlama oranları

Fonlama, sürekli vadeli işlem sözleşmesinde long ve short pozisyonlar arasındaki periyodik ödemedir ve borsalar bunu 8, 4 veya 1 saatte bir uzlaştırır. /funding/rates tüm borsalardaki oranları döndürür, coin parametresi ise sonucu tek bir coin'e daraltır. GET /funding/rates?coin=BTC yanıtı, listeden iki borsalı örnek niteliğinde bir yanıt:

{
  "success": true,
  "data": [
    {
      "coin": "BTC",
      "exchanges": [
        {
          "exchange": "Bitget",
          "funding_pct": 0.01,
          "funding_8h_pct": 0.01,
          "next_payout": "00:00",
          "interval": "8h",
          "price": 96021.5,
          "trade_url": "https://www.bitget.com/futures/usdt/BTCUSDT"
        },
        {
          "exchange": "Hyper",
          "funding_pct": 0.0013,
          "funding_8h_pct": 0.0104,
          "next_payout": null,
          "interval": "1h",
          "price": 96030.0,
          "trade_url": "https://app.hyperliquid.xyz/trade/BTC"
        },
        …
      ]
    }
  ],
  "meta": {
    "count": 1,
    "updated_at": 1794675861,
    "freshness_sec": 60,
    "plan": "trial"
  }
}

Bu yanıt şöyle okunur:

Tüm alanlar Fonlama oranları dokümantasyon bölümünde. Sonraki blok betiği sürdürür: BASE, key ve import'lar zaten tanımlı.

r = requests.get(
    BASE + "/funding/rates",
    headers={"X-API-Key": key},
    params={"coin": "BTC"},  # requests ?coin=BTC'yi oluşturur
    timeout=10,
)
r.raise_for_status()  # 4xx ve 5xx'te hata fırlatır
body = r.json()
if not body["data"]:
    raise SystemExit("coin not in the data: check the ticker")

ts = body["meta"]["updated_at"]
snap = datetime.fromtimestamp(ts, timezone.utc)
print("snapshot from", snap.strftime("%Y-%m-%d %H:%M:%S UTC"))

rows = body["data"][0]["exchanges"]
rows.sort(key=lambda e: e["funding_8h_pct"], reverse=True)
for e in rows:
    print(f'{e["exchange"]:<8} {e["funding_pct"]:>7}% '
          f'per {e["interval"] or "?"}, '
          f'{e["funding_8h_pct"]:>7}% per 8h')

Örnek yanıt için betik şunu yazdırır:

snapshot from 2026-11-14 17:04:21 UTC
Hyper     0.0013% per 1h,  0.0104% per 8h
Bitget      0.01% per 8h,    0.01% per 8h

Hyper, aralık başına oranı 0.01 / 0.0013 ≈ 7,7 kat düşük olmasına rağmen Bitget'in üstünde yer alır. 8 saate normalleştirme yapılmazsa bu karşılaştırma yanlış sonuç verir.

Yeni başlayanların sık yaptığı hatalar

HataSunucunun döndürdüğüNasıl düzeltilir
URL'de anahtar: ?api_key=…401 ve "Missing X-API-Key header."Anahtarı yalnızca X-API-Key başlığında gönderin
Boş anahtar değişkeniAynı metinle 401: curl boş başlığı atarUzunluğu kontrol edin: echo ${#GENESIS_API_KEY}
Yolda yazım hatası: /v1/funding/rate veya /v1 yok404Yolu dokümantasyonla karşılaştırın
Parametre adında yazım hatası: coins=BTC200 ve tüm coin'ler: bilinmeyen parametre yok sayılırmeta.count değerine bakın: coin=BTC ile 1'dir
Ondalık virgül: min_spread=0,5Filtre uygulanmadan 200Nokta kullanın: 0.5
Ticker yerine parite: coin=BTCUSDT200, boş data, meta.count 0Coin ticker'ını kullanın: BTC

Bunların en sinsisi parametre yazım hatasıdır: hata yoktur, ama betik tek coin yerine tüm veri setini alır ve bunun için bir çağrı harcar. Yeni bir filtre ekledikten sonra meta.count değerini beklediğinizle karşılaştırın.

Kendiniz deneyin

  1. Anahtarsız istek gönderin

    curl -i "https://api.genesisarbitrage.com/v1/account/usage" komutu gövdesinde invalid_key ve "Missing X-API-Key header." ile 401 döndürür. Başlıklar arasında x-request-id değerini bulun.

  2. Aynı isteği anahtarla tekrarlayın

    Değişkeni read -s ile tanımlayın ve /account/usage bölümündeki isteği gönderin. 200 alırsınız ve planınız data.plan içindedir.

  3. Sıfırlanma tarihini kontrol edin

    Python betiğini çalıştırın ve kota sıfırlanma tarihini profilinizdeki "Genesis API" bloğunda yer alan "resets …" satırıyla karşılaştırın. Adım adım anahtar alma Genesis API hızlı başlangıç rehberinde.

  4. En yüksek oranı bulun

    İkinci bloğu betiğe ekleyin ve funding_8h_pct değeri en yüksek olan borsayı bulun. Onun funding_pct değerini elle 8 saate normalleştirin: oran × 8 / saat cinsinden aralık.

  5. İsteği bilerek bozun

    coin yerine coins yazın ve meta.count değerlerini karşılaştırın, sonra /funding/rates içindeki s harfini silin ve durum koduna bakın.

Spread, emir defteri ve fonlama kararlarına hangi endpoint'lerin hizmet ettiği 3. dersin konusudur.

Sorular ve cevaplar

API'yi tarayıcıdan çağırabilir miyim?

Yalnızca anahtar gerektirmeyen adresleri: https://api.genesisarbitrage.com/health tarayıcıda açılır ve {"ok":true} gösterir. Adres çubuğu X-API-Key başlığı ekleyemez, bu yüzden anahtarlı istekler curl, bir betik veya dokümantasyondaki "Deneyin" formu üzerinden gider. Anahtarı asla web sitesi veya eklenti koduna gömmeyin: sayfa kaynağını açan herkes onu görür.

curl'de -i bayrağı -v'den nasıl farklıdır?

-i, gövdeden önce durum satırını ve yanıt başlıklarını yazdırır. -v ayrıca isteğin kendisini de gösterir: > ile başlayan satırlar sunucuya giden, < ile başlayan satırlar geri gelendir.

Unix zamanını Python olmadan tarihe nasıl çeviririm?

macOS'ta date -u -r 1796463000, Linux'ta date -u -d @1796463000 çalıştırın. Bu sayı için ikisi de 5 Aralık 2026, 09:30 UTC'yi gösterir.