İ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-Keybaşlığında gönderilir. - Durum kodu bir sonraki adımı belirler:
200verileri okuyun,304hiçbir şey değişmedi,401ve403anahtarı ve planı kontrol edin,429ve503Retry-Aftersaniye bekleyin. - Genesis API yanıtı
success,datavemetaalanlarından oluşan bir zarftır. Yüzdeler düz sayı olarak gelir (0.01yü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 | Örnekte | Ne anlama gelir |
|---|---|---|
| Yöntem | GET | Veri okur; Genesis API'nin tüm endpoint'leri GET'tir |
| Temel URL | https://api.genesisarbitrage.com/v1 | Sunucu ve API sürümü |
| Yol | /funding/rates | Fonlama oranları endpoint'i |
| Parametreler | ?coin=BTC | Filtre: yalnızca BTC |
| Başlık | X-API-Key | Sunucunun 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:
| Kod | Ne anlama gelir | Ne yapmalı |
|---|---|---|
200 | İstek karşılandı, veriler gövdede | data ve meta alanlarını okuyun |
304 | Veriler son yanıtınızdan beri değişmedi | Önceki verileri kullanmaya devam edin |
401 | Anahtar yok, geçersiz, iptal edilmiş veya abonelik süresi dolmuş | Başlığı ve aboneliği kontrol edin |
403 | Endpoint 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 |
503 | Veriler 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:
- zarf:
successdeğeritrue'dur, verilerdataiçindedir, servis alanları isemetaiçindedir;meta.count,dataiçindeki öğe sayısıdır,coin=BTCiçin bu tek bir coin'dir ve içinde birexchangesdizisi bulunur; - yüzdeler düz sayı olarak gelir:
"funding_pct": 0.01, aralık başına yüzde 0,01 demektir, yüzde 1 değil; 10.000 $'lık bir pozisyonda bu orandaki tek bir ödeme 10.000 × 0,01 / 100 = 1 $'dır; funding_8h_pct, oranı 8 saate normalleştirir; böylece farklı aralıklara sahip borsalar doğrudan karşılaştırılabilir: Hyper her saat uzlaştırır ve 0,0013 × 8 = 8 saatte yüzde 0,0104'tür;next_payout, bir sonraki ödeme zamanıdır; UTC'de "HH:MM" dizesi olarak gelir,nullise sıfır değil, veri yok demektir;meta.updated_at, snapshot'ın oluşturulduğu unix zamanıdır: 1794675861, 14 Kasım 2026, 17:04:21 UTC'dir; Trial'da snapshot 60 saniyede bir yenilenir.
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
| Hata | Sunucunun 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şkeni | Aynı metinle 401: curl boş başlığı atar | Uzunluğu kontrol edin: echo ${#GENESIS_API_KEY} |
Yolda yazım hatası: /v1/funding/rate veya /v1 yok | 404 | Yolu dokümantasyonla karşılaştırın |
Parametre adında yazım hatası: coins=BTC | 200 ve tüm coin'ler: bilinmeyen parametre yok sayılır | meta.count değerine bakın: coin=BTC ile 1'dir |
Ondalık virgül: min_spread=0,5 | Filtre uygulanmadan 200 | Nokta kullanın: 0.5 |
Ticker yerine parite: coin=BTCUSDT | 200, boş data, meta.count 0 | Coin 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
Anahtarsız istek gönderin
curl -i "https://api.genesisarbitrage.com/v1/account/usage"komutu gövdesindeinvalid_keyve "Missing X-API-Key header." ile401döndürür. Başlıklar arasındax-request-iddeğerini bulun.Aynı isteği anahtarla tekrarlayın
Değişkeni
read -sile tanımlayın ve/account/usagebölümündeki isteği gönderin.200alırsınız ve planınızdata.planiçindedir.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.
En yüksek oranı bulun
İkinci bloğu betiğe ekleyin ve
funding_8h_pctdeğeri en yüksek olan borsayı bulun. Onunfunding_pctdeğerini elle 8 saate normalleştirin: oran × 8 / saat cinsinden aralık.İsteği bilerek bozun
coinyerinecoinsyazın vemeta.countdeğerlerini karşılaştırın, sonra/funding/ratesiçindekisharfini 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.