Genesis Arbitrage

Genesis Arbitrage · · 15 dk okuma

Kripto piyasa API'sini rate limite takılmadan sorgulama: ETag, gzip, filtreler ve 429 sonrası yeniden deneme

Kısaca

  • Bir API'nin genellikle üç limiti vardır: saniyedeki istek sayısı, dönem başına çağrı kotası ve indirme hacmi. Genesis API'de bu, saniyede 1 ila 15 istek, 30 günde 500K ila 10M çağrı ve anahtar başına 10 saniyede 60 MB sıkıştırılmış veridir.
  • Sorgu aralığını meta.freshness_sec değerine göre belirleyin: daha sık sorgulamak aynı anlık görüntüyü döndürür. If-None-Match tekrarı ücretsiz bir 304'e çevirir, gzip ve filtreler trafiği azaltır, coin başına istek yerine tek bir tam veri seti çağrıdan tasarruf ettirir.
  • 429 ve 503 yanıtlarını Retry-After saniye sonra veya bu başlık yoksa üstel geri çekilme ile rastgele jitter kullanarak yeniden deneyin. İstemci tarafındaki token bucket hızınızı limitin altında tutar, X-RateLimit-* ve X-Quota-* başlıkları ise kalan payı gösterir.

Bir API'yi 429 hatası almadan sorgulamak için istekleri aynı anda üç limite göre şekillendirin: saniyedeki istek sayısı, dönem kotası ve indirdiğiniz veri hacmi. Beş teknik bunu karşılar: verinin yenilenme süresinden kısa olmayan bir aralık, ETag ile koşullu istekler, gzip sıkıştırma, büyük indirmeler yerine filtreler ve sunucunun istediği beklemeden sonra yeniden deneme. Aşağıdaki sayılar ve kod, kripto piyasa verileri için bir REST API olan Genesis API içindir, ancak teknikler borsa API'leri dahil her HTTP API'si için geçerlidir.

Üç API limiti: saniyedeki istek, kota ve hacim

Saniye başına rate limit ani yüklenmeleri yakalar: aynı anda gönderilen bir istek grubunu. Kota, tüm dönem boyunca ortalama hızınızı yakalar; hacim limiti ise istek az olsa bile ağır indirmeleri yakalar.

LimitNeyi sayarGenesis APILimit aşılınca
Saniyedeki istek304 ve hatalar dahil her istekTrial'da 1, Start'ta 2, Pro'da 5, Max'te 15429 rate_limited, Retry-After: 1
Dönem kotasıYalnızca 200 yanıtları30 günde 500K, 2M, 5M, 10M çağrı429 rate_limited, kota sıfırlanana kadar Retry-After
İndirme hacmi64 KB ve üzeri sıkıştırılmış yanıtlarHer planda anahtar başına 10 saniyede 60 MBPencere bitene kadar 429 download_limited

Genesis API, limiti aşan istekler için asla ücret almaz: 429 kota harcamaz ve hiçbir maliyeti yoktur. Tüm kurallar Genesis API limitleri rehberinde ve dokümantasyonun Planlar ve limitler bölümünde yer alır.

Borsa API'leri daha karmaşık olabilir. Binance, istek ağırlığını IP adresi başına sayar ve her endpoint'in kendi ağırlığı vardır. 429 sonrası istek göndermeye devam eden istemci, 418 durumuyla otomatik IP yasağı alır; tekrar edenler daha uzun yasaklanır (Binance dokümantasyonu).

Sorgu aralığı: 30 günde kaç çağrı harcarsınız

Verinin yenilendiğinden daha sık sorgulamak tekrardan başka bir şey getirmez. Genesis Arbitrage çekirdeği veriyi her saniye yeniler, planınızın API çıktısı ise her meta.freshness_sec saniyede bir yenilenir: Trial'da 60, Start'ta 30, Pro'da 10 ve Max'te 5. Bu, planınızın veri tazeliğidir ve sorgu aralığınızın alt sınırıdır. Genesis API'de WebSocket veya webhook yoktur, veriyi REST üzerinden sorgulayarak alırsınız.

Örnek (açıklayıcı): Start planındaki bir bot — ayda 50 $, 2M çağrı, saniyede 2 istek, 30 sn tazelik — dört endpoint'i sorgular: /arbitrage/spot-spot, /arbitrage/spot-futures, /funding/spread ve /market/open-interest.

Aralık30 günde çağrıStart kotasındaki payAynı anlık görüntünün tekrarı
60 sn172.800%8,64yok
30 sn345.600%17,28yok
10 sn1.036.800%51,843 yanıtın 2'si
5 sn2.073.600%103,686 yanıtın 5'i

5 saniyede bir sorgulamak kotayı 29. günde tüketir: günde 4 × 86.400 / 5 = 69.120 çağrı ve 2.000.000 / 69.120 ≈ 28,9 gün. Her altı yanıttan beşi aynı meta.updated_at değerine sahip tek bir anlık görüntüyü tekrar eder ve If-None-Match olmadan her biri bir çağrıya mal olur.

30 saniyede bir sorguda ortalama hız 4 / 30 ≈ 0,13 istek/sn'dir. Ancak aynı anda gönderilen dört istek aynı saniyeye düşer ve ikisi 429 alır. 30 saniyeden taze veriye ihtiyacınız varsa çözüm, daha düşük freshness_sec değerine sahip bir plandır: Pro anlık görüntüyü her 10 saniyede, Max her 5 saniyede yeniler.

Koşullu istekler: ETag, If-None-Match ve 304

ETag, yanıtın sürüm etiketidir. İstemci onu saklar ve aynı URL'ye bir sonraki isteğinde If-None-Match başlığıyla geri gönderir; sürüm değişmediyse sunucu 304 Not Modified yanıtı verir. RFC 9110 uyarınca 304 başlıklardan sonra biter ve gövde taşımaz, yani kendi veri kopyanızı kullanırsınız.

Genesis API'de 304 kota harcamaz ama saniyedeki istek limitinde yine bir yer kaplar. Yalnızca filtresiz tam veri setleri etiket alır. coin, exchange, min_spread veya başka filtreli isteklerin yanıtları ile /orderbooks/book ve /orderbooks/coin/{coin} her istekte yeniden oluşturulur ve ETag olmadan gelir.

ETag, verinin sizin sorgu sıklığınızdan daha seyrek değiştiği yerde kotadan tasarruf ettirir. Spread'lerdeki etiket her anlık görüntüde değişir, bu yüzden freshness_sec başına bir kez sorguladığınızda neredeyse her yanıt 200 olur.

Pro'da örnek (açıklayıcı): fonlama analitiğinin günlük toplamları olan /funding/analytics/daily her saat yeniden oluşturulur; bir yıllık geçmiş biriktiğinde tam bölüm yaklaşık 12 MB gzip olur ve coin olmadan en fazla 300 saniyede bir sunulur. 300 saniyede bir sorgulamak 30 günde 2.592.000 / 300 = 8.640 istek eder. If-None-Match ile bölüm 30 × 24 = 720 kez indirilir, kalan 8.640 − 720 = 7.920 yanıt 304 olarak gelir.

Sonuç: 8.640 yerine 720 çağrı ve 104 GB yerine yaklaşık 8,6 GB trafik. 304 yanıtları tam indirme limitine sayılmaz.

Filtreler ve coin: neyin çağrıdan, neyin trafikten tasarruf ettirdiği

Filtre yanıtı küçültür ama çağrı sayısını değil: kota yanıtları sayar ve coin=BTC içeren bir istek tam veri seti kadar maliyetlidir. Bu yüzden seçim, önce hangisinin tükendiğine bağlıdır: çağrıların mı, trafiğin mi.

Start'ta örnek (açıklayıcı): bir bot beş coin için fonlamayı izler. 30 saniyede bir coin ile /funding/rates'e yapılan beş istek, 30 günde 5 × 86.400 = 432.000 çağrı eder, üstüne döngü başına beş istek saniyede 2 limitine karşı gelir. Coin'lerin kodda ayıklandığı tek bir tam /funding/rates ise 86.400 çağrıya mal olur, yani beş kat az, ayrıca ETag alır.

GörevNasıl istenirNeyi kazandırır
Tek veri setinden birkaç coinIf-None-Match ile tam veri seti, filtre koddaÇağrı: birkaç yerine tek istek
Ağır bir bölümden tek coincoin parametresiTrafik ve hacim limiti
Eşiğin üstündeki satırlarmin_spread, min_volumeTrafik, ama her sorgu bir çağrıdır
Yavaş bir bölümün tamamıIf-None-Match ile tam veri setiÇağrı ve trafik

En ağır bölümler fonlama analitiğine aittir: tam özet yaklaşık 600 KB gzip, 7 günlük ödemeler yaklaşık 1 MB ve günlük toplamlar 12 MB'a kadardır (Fonlama endpoint'leri). coin ile tek coin'lik dilim, tam indirme limitinin dışındadır; bu limit özet ve ödemeler için 60 saniyede bir, günlük toplamlar için 300 saniyede birdir.

Gzip sıkıştırma

Sıkıştırma, hatta giden bayt sayısını azaltır. İstemci bunu Accept-Encoding: gzip ile ister, sunucu sıkıştırılmış gövde ve Content-Encoding: gzip başlığıyla yanıt verir. Python'ın requests kütüphanesi Accept-Encoding'e gzip ekler ve yanıtı kendisi açar; curl aynısını --compressed ile yapar.

Genesis API'de sıkıştırma bir limite bağlıdır: indirme hacmi sıkıştırılmış veriyle, anahtar başına 10 saniyede 60 MB olarak sayılır ve 64 KB'ın altındaki yanıtlar sayılmaz. Tam veri setleri ve büyük yanıtlar, istemci istediğinde gzip'li gelir (Genesis API yanıtları ve hataları). Ağ üzerinden gerçekte kaç gövde baytı geçtiğini görmek için curl'ün size_download değişkenini kullanın:

# body bytes on the wire with and without gzip; each request is a call
URL="https://api.genesisarbitrage.com/v1/funding/rates"
curl -s -o /dev/null --compressed -w "gzip: %{size_download}\n" \
  -H "X-API-Key: $GENESIS_API_KEY" "$URL"
curl -s -o /dev/null -w "uncompressed: %{size_download}\n" \
  -H "X-API-Key: $GENESIS_API_KEY" "$URL"

429 sonrası yeniden deneme: Retry-After ve jitter'lı geri çekilme

HTTP 429 Too Many Requests, limiti aşan istemciye sunucunun yanıtıdır. RFC 6585 uyarınca yanıt Retry-After başlığı taşıyabilir, RFC 9110 uyarınca değeri saniye sayısı veya bir tarihtir. Genesis API her 429 ve 503 ile saniye cinsinden Retry-After gönderir.

Beklemeden yapılan yeniden deneme neredeyse her zaman aynı hatayı alır ve saniyelik pencerede bir yer daha kaplar. Retry-After varsa sunucunun istediği kadar bekleyin. Yoksa her başarısızlıktan sonra katlanarak uzayan süre bekleyin: en fazla 1, 2, 4, 8 saniye.

Jitter, beklemeye eklenen rastgele süredir ve çok sayıda istemci olduğunda önemlidir: o olmadan aynı saniyede hata alan herkes aynı saniyede yeniden dener. backoff fonksiyonu sıfırla mevcut basamak arasında rastgele bir bekleme seçer ve Retry-After değerine bir saniyenin kesri ekler. fetch, 429, 500 ve 503 yanıtlarını yeniden dener ve bekleme 10 dakikadan uzunsa durur: tükenmiş bir kota böyle görünür.

import os
import random
import time

import requests

BASE = "https://api.genesisarbitrage.com/v1"
api = requests.Session()  # reuses the TCP connection, gzip is on
api.headers["X-API-Key"] = os.environ["GENESIS_API_KEY"]
cache = {}  # path -> (ETag, data): full datasets only


def backoff(attempt, retry_after=None, cap=60.0):
    """Pause before a retry, in seconds."""
    if retry_after and retry_after.isdigit():
        return int(retry_after) + random.uniform(0, 1)
    return random.uniform(0, min(cap, 2 ** attempt))


def fetch(path, params=None, tries=5):
    """GET from the API: returns (data, response headers)."""
    for attempt in range(tries):
        tag = None if params else cache.get(path, (None,))[0]
        try:
            r = api.get(BASE + path, params=params, timeout=15,
                        headers={"If-None-Match": tag} if tag else {})
        except (requests.ConnectionError, requests.Timeout):
            time.sleep(backoff(attempt))
            continue
        if r.status_code == 304:  # same snapshot, no quota used
            return cache[path][1], r.headers
        if r.status_code in (429, 500, 503):
            wait = backoff(attempt, r.headers.get("Retry-After"))
            if wait > 600:  # this is what an exhausted quota looks like
                raise RuntimeError(f"quota resets in {wait:.0f} s")
            time.sleep(wait)
            continue
        r.raise_for_status()  # 400, 401, 403, 404, 410: do not retry
        data = r.json()["data"]
        if not params and "ETag" in r.headers:
            cache[path] = (r.headers["ETag"], data)
        return data, r.headers
    raise RuntimeError(f"{path}: no response after {tries} tries")
YanıtBeklemeYeniden deneme
429 rate_limited, saniyelikRetry-After: 1 artı saniyenin bir kesriEvet
429 rate_limited, kotaKota sıfırlanana kadar, günler sürebilirHayır
429 download_limitedRetry-After, pencere bitene kadarEvet, daha dar isteklerle
503 snapshot_not_readyRetry-AfterEvet
500, zaman aşımı, kopan bağlantıJitter'lı üstelEvet
400, 401, 403, 404, 410—Hayır, isteği düzeltin

Tükenmiş kotayı saniyelik limitten Retry-After ile ayırt edersiniz: bir saniyeye karşı sıfırlanmaya kadar saatler veya günler; yanıt gövdesinde ayrıca Monthly call quota exceeded. yazar. Hata kodları ve gövdeleri dokümantasyonun Hatalar bölümündedir.

İstemci tarafı rate limiter: token bucket

Yeniden deneme bir 429'la ilgilenir; istemci tarafı limiter ise onu önler. Token bucket şöyle çalışır: token'lar saniyede rate hızıyla gelir, her istek bir token alır ve boş kova sizi bekletir. Kapasite olan burst, bekleme olmadan art arda kaç isteğin çıkabileceğini belirler.

import time


class TokenBucket:
    """At most rate requests per second, up to burst back to back."""

    def __init__(self, rate, burst=1):
        self.rate, self.burst = rate, burst
        self.tokens = float(burst)
        self.last = time.monotonic()

    def take(self):
        while True:
            now = time.monotonic()
            self.tokens = min(self.burst, self.tokens
                              + (now - self.last) * self.rate)
            self.last = now
            if self.tokens >= 1:
                self.tokens -= 1
                return
            time.sleep((1 - self.tokens) / self.rate)

Limiti /account/usage içindeki rps_limit alanından (Kullanım bölümü) veya X-RateLimit-Limit başlığından alın. Hızı limitin biraz altına ayarlayın, örneğin 0.9 * rps_limit: ağ gecikmesi düzensizdir, bu yüzden yarım saniye arayla gönderilen istekler sunucuya birbirine daha yakın ulaşabilir.

İzleme: X-RateLimit-* ve X-Quota-* başlıkları

Veri yanıtı limitlerinizin durumunu taşır: X-RateLimit-Remaining ve X-RateLimit-Reset saniyelik pencerede ne kaldığını ve ne zaman sıfırlanacağını, X-Quota-Remaining, X-Quota-Limit ve X-Quota-Reset ise kalan kotayı, boyutunu ve sıfırlanma unix zamanını verir. Tek bir kalan değerden daha yararlı olan hızdır: dönemin bu noktasında kotanın ne kadarı gitmiş.

PERIOD = 30 * 86400  # Genesis API counts quota per 30 days


def watch(h):
    """Checks limit headroom from the response headers."""
    if h.get("X-RateLimit-Remaining") == "0":  # window used up
        reset = float(h.get("X-RateLimit-Reset", 0))
        time.sleep(max(0.0, reset - time.time()))
    try:
        left = int(h["X-Quota-Remaining"])
        limit = int(h["X-Quota-Limit"])
        reset = int(h["X-Quota-Reset"])
    except (KeyError, ValueError):
        return  # 429 responses carry no X-Quota-* headers
    used = 1 - left / limit
    passed = 1 - (reset - time.time()) / PERIOD
    if used > passed + 0.05:
        print(f"quota is running ahead: {used:.0%} used"
              f" with {passed:.0%} of the period gone")

Fonksiyon, limiti dolunca pencerenin sıfırlanmasını bekler ve kota kullanımı takvimin 5 yüzde puandan fazla önüne geçtiğinde uyarır. Örnek (açıklayıcı): 15. güne kadar kotanın %70'i gitmiştir, yani aynı hızla çağrılar dönemin 15 / 0,7 ≈ 21,4. gününde biter. /account/usage aynı sayıları başlıksız verir: calls_used, calls_limit ve period_resets_at.

Birkaç endpoint için zamanlama

Birden çok endpoint olduğunda her birine kendi aralığı verilir ve ilk istekler toplu çıkmasın diye dağıtılır. Aralığı göreve göre seçin, ama asla freshness_sec altına inmeyin: spread'ler planınızın tam hızını ister, birçok strateji için ise fonlama ve açık pozisyon için bir dakika yeterlidir.

import heapq

usage, _ = fetch("/account/usage")  # does not use a call
fresh = usage["freshness_sec"]
bucket = TokenBucket(rate=0.9 * usage["rps_limit"])

JOBS = {  # path -> polling interval, s
    "/arbitrage/spot-spot": fresh,
    "/funding/spread": max(fresh, 60),
    "/market/open-interest": max(fresh, 60),
}
t0 = time.monotonic()
queue = [(t0 + i * fresh / len(JOBS), path, every)
         for i, (path, every) in enumerate(JOBS.items())]
heapq.heapify(queue)

while True:
    due, path, every = heapq.heappop(queue)
    time.sleep(max(0.0, due - time.monotonic()))
    bucket.take()
    data, hdrs = fetch(path)
    watch(hdrs)
    print(path, len(data))
    heapq.heappush(queue, (due + every, path, every))

Start'ta bu, 30 günde 86.400 + 43.200 + 43.200 = 172.800 çağrı eder, kotanın %8,64'ü: spread'ler 30 saniyede bir, fonlama ve açık pozisyon 60 saniyede bir. İlk istekler 30 / 3 = 10 saniye arayla çıkar, sonra her endpoint kendi ritmini korur ve bucket.take() çakışmalara karşı korur. Bu sorguya dayanan, Telegram bildirimli bir bot Python ile kripto arbitraj botu yazısındadır.

503 ve sunucu hatalarında ne yapmalı

RFC 9110 uyarınca 503 Service Unavailable, geçici aşırı yük veya bakım anlamına gelir ve sunucu Retry-After ile bir bekleme önerebilir. Genesis API'de bu 503 snapshot_not_ready olur: veri yeniden oluşturuluyor veya kaynağı yeniden başlıyordur. Retry-After saniye sonra yeniden deneyin; bekleme genellikle birkaç saniyedir.

Taze yanıt gelmediği sürece botunuz son sorgudan kalan veriyi tutar ve bu veri eskir. Sinyal göndermeden önce meta.updated_at değerini şu anki zamanla karşılaştırın: bir dakikalık anlık görüntüdeki bir çift borsada çoktan kaybolmuş olabilir. Diğer riskler Otomasyon riskleri dersinde anlatılır.

500 internal_error, zaman aşımı ve kopan bağlantıları üstel geri çekilmeyle yeniden deneyin. Hata sürerse X-Request-Id değeri, UTC cinsinden istek zamanı, endpoint ve durum koduyla destek ekibine yazın. Anahtarınızı asla göndermeyin.

Sorular ve cevaplar

Genesis API'ye saniyede kaç istek gönderebilirim?

Planınızın izin verdiği kadar: Trial'da 1, Start'ta 2, Pro'da 5 ve Max'te 15. Limit anahtar başınadır ve 304 yanıtlarını ile hataları içerir. Planınızın değeri X-RateLimit-Limit başlığında ve /account/usage içindeki rps_limit alanındadır.

Hatalar ve 304 yanıtları kotamdan düşer mi?

Hayır. Yalnızca 200 yanıtı kota harcar; 304, 429, 503 ve diğer hatalar ücretsizdir ve hiçbir maliyeti yoktur. Ancak saniyedeki istek limitinde yer kaplarlar, bu yüzden beklemeden yapılan yeniden denemeler yeni 429 yanıtları doğurur.

10 saniyede 60 MB sınırının altında nasıl kalırım?

Gzip'i açın: limit sıkıştırılmış veriyi sayar. Tam veri setlerinde If-None-Match gönderin: 304'ün gövdesi yoktur. Fonlama analitiği gibi ağır bölümleri coin dilimi olarak alın ve aynı tam veri setini freshness_sec'ten sık indirmeyin. 64 KB'ın altındaki yanıtlar sayılmaz ve dokümantasyona göre her veri setini planınızın tazelik aralığında sorgulamak limitin altına rahatça sığar.

429 Too Many Requests hatası ne anlama gelir?

Sunucu, istemci bir zaman penceresinde limiti aştığı için isteği reddetmiştir. Yanıt, beklenecek saniye sayısı olan Retry-After taşıyabilir; yoksa her başarısızlıktan sonra beklemeyi ikiye katlayın. Genesis API'de 429, rate_limited veya download_limited koduyla gelir.