Genesis Arbitrage

Genesis Arbitrage · · 11 dk okuma

Genesis API yanıtları ve hataları: JSON biçimi, ETag ve 304, HTTP kodları

Kısaca

  • Başarılı bir Genesis API yanıtı success, data ve meta zarfıdır; hata ise success: false ile kod ve mesaj içeren bir error nesnesidir.
  • Önceki ETag'i If-None-Match ile göndermek, veri değişmemişse gövdesiz 304 döndürür ve 304 kota harcamaz.
  • 429 ve 503 yanıtlarını Retry-After süresi kadar bekleyip yeniden deneyin. 400, 401, 403, 404 ve 410 yeniden denemeyle düzelmez — isteği, anahtarı veya tarifeyi değiştirin.

Genesis API her isteğe JSON ile yanıt verir; JSON, anahtar–değer nesnelerinden ve dizilerden oluşan bir metin veri biçimidir. Başarılı yanıt her zaman success, data ve meta içeren aynı zarfta gelir; hata ise bir HTTP durum kodu ve bir error nesnesiyle gelir. Durum kodu programınıza ne yapacağını söyler: veriyi kullanmak, Retry-After saniye bekleyip yeniden denemek veya isteği düzeltmek.

Yanıt zarfı: success, data ve meta

Dokümantasyondan kısaltılmış bir GET /arbitrage/spot-spot yanıtı (uç nokta her tarifede kullanılabilir):

{
  "success": true,
  "data": [
    {
      "coin": "FUEL",
      "exchange_buy": "ByBit",
      "exchange_sell": "Gate",
      "spread_pct": 0.11,
      …
    }
  ],
  "meta": {
    "count": 214,
    "updated_at": 1783802410,
    "freshness_sec": 10,
    "plan": "pro"
  }
}
AlanTürİçerik
successbooleantrue — istek başarılı, false — hata
datadizi veya nesneUç noktanın verisi
meta.countintdata içindeki öğe sayısı
meta.updated_atintVerinin oluşturulduğu Unix zamanı
meta.freshness_secintTarifeniz için sunum gecikmesi, saniye
meta.planstringTarifeniz, örnekte pro

İstisna fonlama analitiğidir: meta alanında count, updated_at ve schema_version bulunur, freshness_sec ve plan yoktur. Zarf, dokümantasyonun Yanıt formatı bölümünde, data alanları ise her uç noktanın sayfasında anlatılır.

Üç kural her uç nokta için geçerlidir:

data: satır dizisi veya nesne

data biçimi her uç noktanın açıklamasında belirtilir. GET /arbitrage/spot-spot için bu bir dizidir: her arbitraj çifti için bir öğe, sitedeki tablonun bir satırı gibi. GET /account/usage için ise anahtarınızın durumunu içeren tek bir nesnedir:

curl "https://api.genesisarbitrage.com/v1/account/usage" \
  -H "X-API-Key: gns_live_XXXXXXXXXXXXXXXX"
{
  "success": true,
  "data": {
    "plan": "pro",
    "calls_used": 184201,
    "calls_limit": 5000000,
    "rps_limit": 5,
    "freshness_sec": 10,
    "period_resets_at": 1786492800
  },
  "meta": { … }
}

/account/usage her tarifede kullanılabilir; tarifenizi, kota kullanımınızı ve freshness_sec değerini gösterir: bundan sık sorgulamanın faydası yoktur. Alanlar Kullanım bölümünde, ilk istek ise hızlı başlangıç rehberinde adım adım anlatılır. Birkaç uç noktayla çalışan kod, biçimi açıkça kontrol etmelidir: Python'da isinstance(data, list).

Filtreler: isteğe bağlı, filtresiz tam veri seti

Tüm filtre parametreleri isteğe bağlıdır: onlarsız yapılan istek, uç noktanın tam veri setini döndürür. exchange alanına birkaç borsayı virgülle ayırarak yazın, coin alanına coini tickerıyla verin:

curl -G --compressed \
  "https://api.genesisarbitrage.com/v1/arbitrage/spot-spot" \
  -d coin=BTC -d exchange=Binance,OKX -d min_spread=0.5 \
  -H "X-API-Key: gns_live_XXXXXXXXXXXXXXXX"

-G bayrağı -d parametrelerini sorgu dizesine çevirir: ?coin=BTC&exchange=Binance,OKX&min_spread=0.5. Borsa adlarını yanıt alanlarında döndüğü şekilde yazın: ByBit, Gate, MEXC. Arbitraj uç noktalarının parametreleri arbitraj uç noktaları rehberinde yer alır.

Kota satırları değil yanıtları sayar: filtreli veya filtresiz bir istek tek çağrıdır. Filtre yanıt gövdesini, dolayısıyla trafiği ve indirme limiti kullanımını azaltır. Tüm limitler Genesis API limitleri rehberinde ele alınır.

gzip sıkıştırma

Genesis API, istemci Accept-Encoding: gzip başlığını gönderdiğinde tam veri setlerini ve büyük yanıtları gzip ile sıkıştırarak gönderir (RFC 9110, bölüm 12.5.3). Küçük bir yanıt sıkıştırılmadan gelebilir.

Python requests bu başlığı kendisi gönderir ve yanıtı açar. curl, --compressed bayrağı olmadan sıkıştırma istemez; bayrakla birlikte hem ister hem açar.

İndirme limiti sıkıştırılmış veriyi sayar: anahtar başına 10 saniyede en fazla 60 MB; 64 KB'tan küçük yanıtlar sayılmaz. Limit aşılırsa 429 download_limited alırsınız.

ETag ve 304: değişmeyen veriyi atlayın

ETag, verinin sürüm etiketini taşıyan bir yanıt başlığıdır. İstemci bu etiketi If-None-Match başlığında geri gönderir. Veri değişmemişse sunucu gövdesiz 304 Not Modified döndürür; değişmişse yeni veri ve yeni ETag ile normal bir 200 verir.

# Tam veri seti, filtresiz: yalnızca yanıt başlıklarını yazdır
curl -sS -D - -o /dev/null --compressed \
  "https://api.genesisarbitrage.com/v1/arbitrage/spot-spot" \
  -H "X-API-Key: gns_live_XXXXXXXXXXXXXXXX"

# İlk yanıttaki ETag ile tekrarla (örnek değer)
curl -sS -D - -o /dev/null --compressed \
  "https://api.genesisarbitrage.com/v1/arbitrage/spot-spot" \
  -H "X-API-Key: gns_live_XXXXXXXXXXXXXXXX" \
  -H 'If-None-Match: W/"5d1f0c9a"'

ETag, filtresiz isteğin yanıtıyla gelir ve her yeni veri anlık görüntüsüyle değişir. Filtreli isteğin yanıtı o istek için oluşturulur ve ETag olmadan gelir; orada trafiği filtrenin kendisi azaltır. ETag en çok yavaş değişen verilerde işe yarar: fonlama analitiği özetinin ETag'i yaklaşık 15 dakikada bir değişir ve 304 yanıtları onun tam indirme limitine sayılmaz.

304 yanıtı kota harcamaz, ancak saniyedeki istek limitine sayılır. Etiketi geldiği gibi geri gönderin: RFC 9110 uyarınca etiket tırnak içinde bir dizedir ve W/ öneki zayıf etiketi belirtir.

Hata kodları ve ne yapmalı

Hata durumunda Genesis API ilgili HTTP durum kodunu ve success: false içeren bir gövde döndürür:

{
  "success": false,
  "error": {
    "code": "rate_limited",
    "message": "Requests per second limit exceeded."
  }
}

error.code, programınızın dallanabileceği makine tarafından okunabilir bir koddur. error.message insan için açıklamadır: 400 için nedeni, 410 için yeni adresi verir.

HTTPerror.codeAnlamıNe yapmalı
400bad_requestGeçersiz istek parametreleri, örneğin /orderbooks/exec üzerinde volume=700Parametreleri message'a göre düzeltin: aynı istek yine başarısız olur
401invalid_keyAnahtar yok, geçersiz veya iptal edilmiş ya da API aboneliği sona ermişX-API-Key başlığını ve profilinizdeki abonelik durumunu kontrol edin
403plan_restrictedUç nokta tarifenizde yokOnu içeren bir tarifeye geçin veya isteği bırakın
404not_foundUç nokta veya kaynak bulunamadı: veri seti, bölüm, coin, emir defteriYolu ve parametreleri dokümantasyonla karşılaştırın
410goneUç nokta kaldırıldımessage içinde verilen adrese geçin
429rate_limitedSaniyedeki istek limiti aşıldı veya dönem kotası bittiRetry-After saniye bekleyin ve yavaşlayın; kota bittiyse sıfırlanmayı bekleyin veya tarifeyi yükseltin
429download_limitedİndirme hacmi aşıldı: anahtar başına 10 sn'de 60 MB sıkıştırılmış veriRetry-After kadar bekleyin, trafiği filtrelerle, coin ve If-None-Match ile azaltın
500internal_errorİç hataDaha sonra yeniden deneyin; sürerse X-Request-Id ile desteğe yazın
503snapshot_not_readyVeri yeniden oluşturuluyor veya kaynağı yeniden başlıyorRetry-After saniye sonra yeniden deneyin

Retry-After başlığı 429 ve 503 ile gelir ve beklenecek saniye sayısını taşır: genellikle birkaç saniyedir, ancak dönem kotası bittiğinde kotanın sıfırlanmasına kalan süredir ve bu günler olabilir. 4xx ve 5xx hataları kota harcamaz ancak saniyedeki istek limitine sayılır; bu yüzden erken yapılan yeniden deneme büyük olasılıkla aynı hatayı döndürür. Sözlük maddeleri: HTTP 429 ve rate limit.

X-Request-Id: desteğe ne gönderilir

Başarılı olsun olmasın her Genesis API yanıtı, isteğin tanımlayıcısını içeren bir X-Request-Id başlığı taşır. Hata tekrar ediyorsa veya veri yanlış görünüyorsa desteğe şunları gönderin:

Anahtarınızı göndermeyin. Anahtar bir sohbete, günlüklere veya başkalarının görebileceği koda düştüyse profilinizde yeniden oluşturun: eski anahtar hemen çalışmayı bırakır.

Yanıtları işleme sırası

  1. Durum kodunu kontrol edin

    200 — data ve meta alanlarını okuyun, ETag geldiyse saklayın. 304 — önceki yanıttaki veriyi kullanın.

  2. Geçici hataları işleyin

    Kısa beklemeli 429 ve 503 — Retry-After saniye bekleyip yeniden deneyin, üst üste en fazla üç kez. 500 — daha sonra yeniden deneyin.

  3. İstek hatalarında durun

    400, 401, 403, 404, 410 ve saatler veya günler süren beklemeli 429 — parametreleri, anahtarı veya tarifeyi düzeltin ya da kota sıfırlanmasını bekleyin.

  4. Verinin yaşını kontrol edin

    meta.updated_at değerini şimdiki zamanla karşılaştırın: eski anlık görüntüyle işlem yapan bir bot, çoktan kaybolmuş spreadler görür.

  5. Sonraki isteği planlayın

    En erken meta.freshness_sec saniye sonra, filtresiz isteklerde If-None-Match ile.

Python'da get_json fonksiyonu

Fonksiyon bu kuralları bir araya getirir: her adres için son ETag'i saklar ve 304 durumunda önceki veriyi döndürür, 429 ve 503 durumunda Retry-After kadar bekleyip üç kereye kadar yeniden dener, ancak bir dakikadan uzun beklemeleri beklemez. Diğer hatalar durum kodu, mesaj ve X-Request-Id ile bir istisna oluşturur. Anahtar GENESIS_API_KEY ortam değişkeninden gelir.

import os
import time
import requests

BASE = "https://api.genesisarbitrage.com/v1"
session = requests.Session()
session.headers["X-API-Key"] = os.environ["GENESIS_API_KEY"]
cache = {}  # (path, params) -> (ETag, data)


class GenesisError(Exception):
    def __init__(self, status, text):
        super().__init__(f"{status} {text}")
        self.status = status


def get_json(path, params=None):
    key = (path, tuple(sorted((params or {}).items())))
    for attempt in range(4):  # bir istek ve en fazla 3 yeniden deneme
        hdr = {"If-None-Match": cache[key][0]} if key in cache else {}
        r = session.get(BASE + path, params=params,
                        headers=hdr, timeout=15)
        if r.status_code == 304:
            return cache[key][1]  # veri değişmedi
        wait = float(r.headers.get("Retry-After", 1))
        if r.status_code in (429, 503) and attempt < 3 and wait <= 60:
            time.sleep(wait)  # saatler veya günler asla beklenmez
            continue
        try:
            body = r.json()
        except ValueError:
            raise GenesisError(r.status_code, "JSON değil") from None
        if r.status_code != 200 or not body.get("success"):
            err = body.get("error") or {}
            raise GenesisError(r.status_code, (
                f"{err.get('code')}: {err.get('message')}; "
                f"X-Request-Id {r.headers.get('X-Request-Id')}"))
        if "ETag" in r.headers:  # yalnızca filtresiz yanıtlarda
            cache[key] = (r.headers["ETag"], body["data"])
        return body["data"]

timeout=15 parametresi şarttır: zaman aşımı olmadan requests yanıtı sonsuza kadar bekler.

Tarifenizin aralığında sorgulama: tam veri seti ETag ile gelir, satırlar kodda süzülür. 4xx hataları programı durdurur; sunucu arızası bir sonraki döngüyü bekler.

pause = get_json("/account/usage")["freshness_sec"]
while True:
    try:
        rows = get_json("/arbitrage/spot-spot")  # tam veri seti
        top = [x for x in rows if x["spread_pct"] >= 1]
        print(len(top), "çiftte spread %1 veya üzeri")
    except GenesisError as e:
        if e.status < 500:
            raise  # 4xx: istek, anahtar, tarife veya kota
        print("sunucu hatası, sonraki döngüde yeniden denenecek:", e)
    time.sleep(pause)

Sorular ve cevaplar

304 yanıtı kota harcar mı?

Hayır. Yalnızca 200 yanıtları kota harcar. 304 yanıtları ile 4xx ve 5xx hataları ücretsizdir, ancak saniyedeki istek limitine sayılır.

410 sonrasında ne yapmalıyım?

Uç nokta kaldırılmıştır ve yeni adres error.message içindedir. Örneğin GET /arbitrage/predictions 15 Kasım 2026'da kaldırıldı ve message alanı /predictions/arbitrage adresini gösterir. Koddaki yolu güncelleyin.

Hata yokken data neden boş?

Filtreler tüm satırları eledi: örneğin min_spread, mevcut tüm spreadlerden yüksek. Böyle bir yanıtta meta.count 0'dır; filtreyi gevşetin.

Yanıtta neden ETag yok?

ETag, filtresiz isteğin yanıtıyla gelir. coin, exchange, min_spread veya başka bir filtreyle yapılan isteğin yanıtı o istek için oluşturulur ve etiketsiz gelir, bu yüzden If-None-Match ona uygulanmaz.