Genesis Arbitrage

Genesis Arbitrage · · 14 دقائق قراءة

كيف تستطلع API سوق العملات الرقمية دون تجاوز حدود المعدل: ETag وgzip والفلاتر وإعادة المحاولة بعد 429

باختصار

  • لدى أي API عادةً ثلاثة حدود: الطلبات في الثانية، وحصة الاستدعاءات لكل فترة، وحجم التنزيل. في Genesis API هي من 1 إلى 15 طلباً في الثانية، ومن 500K إلى 10M استدعاء لكل 30 يوماً، و60 ميغابايت من البيانات المضغوطة لكل 10 ثوانٍ لكل مفتاح.
  • حدّد فاصل الاستطلاع من meta.freshness_sec: الاستطلاع الأسرع يعيد اللقطة نفسها. يحوّل If-None-Match التكرار إلى 304 مجاني، ويقلل gzip والفلاتر حجم الحركة، ومجموعة بيانات كاملة واحدة بدل طلب لكل عملة توفر الاستدعاءات.
  • أعد محاولة 429 و503 بعد Retry-After ثانية، أو عند غياب هذه الترويسة بتراجع أسي مع jitter عشوائي. يُبقي token bucket على جهة العميل وتيرتك تحت الحد، وتُظهر ترويسات X-RateLimit-* وX-Quota-* الهامش المتبقي.

لاستطلاع API دون أخطاء 429، ابنِ طلباتك على ثلاثة حدود في وقت واحد: الطلبات في الثانية، وحصة الاستدعاءات للفترة، وحجم البيانات التي تنزّلها. تغطي ذلك خمس تقنيات: فاصل لا يقل عن تحديث البيانات، وطلبات شرطية بـ ETag، وضغط gzip، وفلاتر بدل التنزيلات الضخمة، وإعادة المحاولة بعد المهلة التي يطلبها الخادم. الأرقام والشيفرة أدناه خاصة بـ Genesis API، وهو REST API لبيانات سوق العملات الرقمية، لكن التقنيات تعمل مع أي HTTP API، ومنها واجهات البورصات.

ثلاثة حدود في API: الطلبات في الثانية والحصة والحجم

يلتقط حد المعدل في الثانية الدفعات: مجموعة طلبات تُرسل دفعة واحدة. وتلتقط الحصة وتيرتك المتوسطة على امتداد الفترة، ويلتقط حد الحجم التنزيلات الثقيلة حتى لو كانت الطلبات قليلة.

الحدما الذي يحتسبهGenesis APIعند التجاوز
الطلبات في الثانيةكل طلب، بما فيه 304 والأخطاء1 في Trial، و2 في Start، و5 في Pro، و15 في Max429 rate_limited، Retry-After: 1
الحصة للفترةاستجابات 200 فقط500K و2M و5M و10M استدعاء لكل 30 يوماً429 rate_limited، Retry-After حتى تُجدَّد الحصة
حجم التنزيلالاستجابات المضغوطة من 64 KB فما فوق60 MB لكل 10 ثوانٍ لكل مفتاح، في كل الخطط429 download_limited حتى تنتهي النافذة

لا يحاسب Genesis API على الطلبات التي تتجاوز الحد: لا يستهلك 429 أي حصة ولا يكلف شيئاً. كل القواعد في دليل حدود Genesis API وفي قسم الخطط والحدود من التوثيق.

قد تكون واجهات البورصات أكثر تعقيداً. تحتسب Binance وزن الطلبات لكل عنوان IP، ولكل endpoint وزنه الخاص. والعميل الذي يواصل الإرسال بعد 429 يتعرض لحظر IP تلقائي بالحالة 418، وتطول مدة الحظر مع تكرار المخالفة (توثيق Binance).

فاصل الاستطلاع: كم استدعاءً تستهلك في 30 يوماً

الاستطلاع بوتيرة أسرع من تحديث البيانات لا يجلب سوى التكرار. تحدّث نواة Genesis Arbitrage البيانات كل ثانية، أما مخرجات API لخطتك فتتجدد مرة كل meta.freshness_sec ثانية: 60 في Trial، و30 في Start، و10 في Pro، و5 في Max. هذه هي حداثة البيانات في خطتك والحد الأدنى لفاصل الاستطلاع. لا يوفر Genesis API WebSocket ولا webhooks، لذا تحصل على البيانات بالاستطلاع عبر REST.

مثال توضيحي: بوت على خطة Start — 50 دولاراً في الشهر، و2M استدعاء، وطلبان في الثانية، وحداثة 30 ث — يستطلع أربع نقاط: /arbitrage/spot-spot و/arbitrage/spot-futures و/funding/spread و/market/open-interest.

الفاصلالاستدعاءات في 30 يوماًحصة من Startتكرارات اللقطة الواحدة
60 ث172,8008.64%لا شيء
30 ث345,60017.28%لا شيء
10 ث1,036,80051.84%2 من 3
5 ث2,073,600103.68%5 من 6

الاستطلاع كل 5 ثوانٍ يستنفد الحصة في اليوم 29: 4 × 86,400 / 5 = 69,120 استدعاء في اليوم، و2,000,000 / 69,120 ≈ 28.9 يوماً. خمس من كل ست استجابات تكرر اللقطة نفسها بالقيمة نفسها لـ meta.updated_at، وبدون If-None-Match تكلف كل واحدة منها استدعاءً.

عند استطلاع واحد كل 30 ثانية تكون الوتيرة المتوسطة 4 / 30 ≈ 0.13 طلب في الثانية. لكن أربعة طلبات تُرسل معاً تقع في الثانية نفسها، ويحصل اثنان منها على 429. وإذا احتجت بيانات أحدث من 30 ثانية فالحل خطة بـ freshness_sec أقل: تحدّث Pro اللقطة كل 10 ثوانٍ، وMax كل 5.

الطلبات الشرطية: ETag وIf-None-Match و304

ETag علامة إصدار للاستجابة. يحفظها العميل ويعيد إرسالها في ترويسة If-None-Match مع طلبه التالي إلى العنوان نفسه؛ فإذا لم يتغير الإصدار يرد الخادم بـ 304 Not Modified. وبحسب RFC 9110 تنتهي استجابة 304 بعد الترويسات ولا تحمل جسماً، فتستخدم نسختك الخاصة من البيانات.

في Genesis API لا تستهلك 304 حصة لكنها تشغل خانة في حد الطلبات في الثانية. ولا تحصل على علامة إلا مجموعات البيانات الكاملة بلا فلاتر. أما الاستجابات للطلبات التي فيها coin أو exchange أو min_spread أو فلاتر أخرى، وكذلك /orderbooks/book و/orderbooks/coin/{coin}، فتُبنى لكل طلب وتأتي بلا ETag.

يوفر ETag الحصة حيث تتغير البيانات أبطأ مما تطلبها. تتغير علامة السبريدات مع كل لقطة، فإذا استطلعت مرة كل freshness_sec فتكاد كل استجابة تكون 200.

مثال توضيحي على Pro: تُعاد توليد المجاميع اليومية لـتحليلات التمويل، /funding/analytics/daily، كل ساعة؛ وبعد أن يتراكم سجل سنة يبلغ القسم الكامل نحو 12 MB بعد gzip، ويُقدَّم بدون coin مرة واحدة كل 300 ثانية على الأكثر. الاستطلاع كل 300 ثانية يعني 2,592,000 / 300 = 8,640 طلباً في 30 يوماً. ومع If-None-Match يُنزَّل القسم 30 × 24 = 720 مرة، وتعود الاستجابات الأخرى وعددها 8,640 − 720 = 7,920 بـ 304.

النتيجة: 720 استدعاءً بدل 8,640، ونحو 8.6 GB من الحركة بدل 104 GB. ولا تُحتسب استجابات 304 ضمن حد التنزيل الكامل.

الفلاتر وcoin: ما الذي يوفر الاستدعاءات وما الذي يوفر الحركة

يصغّر الفلتر الاستجابة لكنه لا يقلل عدد الاستدعاءات: تحتسب الحصة الاستجابات، والطلب بـ coin=BTC يكلف مثل مجموعة البيانات الكاملة. لذا يعتمد الاختيار على ما ينفد أولاً: الاستدعاءات أم الحركة.

مثال توضيحي على Start: بوت يتتبع التمويل لخمس عملات. خمسة طلبات إلى /funding/rates بـ coin كل 30 ثانية تعني 5 × 86,400 = 432,000 استدعاء في 30 يوماً، إضافة إلى خمسة طلبات في كل دورة مقابل حد طلبين في الثانية. أما /funding/rates كاملاً واحداً مع انتقاء العملات في الشيفرة فيكلف 86,400 استدعاء، أي أقل بخمس مرات، ويحصل على ETag.

المهمةكيف تطلبما الذي يوفره
عدة عملات من مجموعة بيانات واحدةالمجموعة الكاملة مع If-None-Match والفلترة في الشيفرةالاستدعاءات: طلب واحد بدل عدة طلبات
عملة واحدة من قسم ثقيلالمعامل coinالحركة وحد الحجم
صفوف فوق عتبةmin_spread وmin_volumeالحركة، لكن كل استطلاع استدعاء
قسم بطيء كاملاًالمجموعة الكاملة مع If-None-Matchالاستدعاءات والحركة

أثقل الأقسام هي تحليلات التمويل: الملخص الكامل نحو 600 KB بعد gzip، ودفعات 7 أيام نحو 1 MB، والمجاميع اليومية حتى 12 MB (نقاط التمويل). والشريحة الخاصة بعملة واحدة مع coin معفاة من حد التنزيل الكامل، وهو مرة كل 60 ثانية للملخص والدفعات ومرة كل 300 للمجاميع اليومية.

ضغط gzip

يقلل الضغط عدد البايتات على الشبكة. يطلبه العميل بـ Accept-Encoding: gzip، ويرد الخادم بجسم مضغوط وترويسة Content-Encoding: gzip. تضيف مكتبة requests في Python القيمة gzip إلى Accept-Encoding وتفك ضغط الاستجابة بنفسها؛ وكذلك يفعل curl مع --compressed.

في Genesis API يرتبط الضغط بأحد الحدود: يُحتسب حجم التنزيل على البيانات المضغوطة، 60 MB لكل 10 ثوانٍ لكل مفتاح، ولا تُحتسب الاستجابات الأصغر من 64 KB. تأتي مجموعات البيانات الكاملة والاستجابات الكبيرة مضغوطة بـ gzip إذا طلب العميل ذلك (استجابات Genesis API وأخطاؤه). ولمعرفة عدد بايتات الجسم التي عبرت الشبكة فعلاً استخدم المتغير size_download في curl:

# 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: Retry-After والتراجع مع jitter

HTTP 429 Too Many Requests هو رد الخادم على عميل تجاوز حداً. وبحسب RFC 6585 قد تحمل الاستجابة ترويسة Retry-After، وبحسب RFC 9110 تكون قيمتها إما عدد ثوانٍ وإما تاريخاً. يرسل Genesis API الترويسة Retry-After مع كل 429 و503، بالثواني.

إعادة المحاولة دون مهلة تعيد الخطأ نفسه تقريباً دائماً وتأخذ خانة أخرى في نافذة الثانية. إن وُجدت Retry-After فانتظر المدة التي يطلبها الخادم. وإن لم توجد فانتظر مدة تتضاعف بعد كل إخفاق: حتى 1 ثم 2 ثم 4 ثم 8 ثوانٍ.

Jitter، وهو إضافة عشوائية إلى المهلة، مهم عندما يكثر العملاء: بدونه يعيد كل من تلقى خطأً في الثانية نفسها محاولته في الثانية نفسها أيضاً. تختار الدالة backoff مهلة عشوائية بين الصفر والخطوة الحالية، وتضيف جزءاً من الثانية إلى Retry-After. وتعيد fetch محاولة 429 و500 و503، وتتوقف عندما تتجاوز المهلة 10 دقائق: هذا ما تبدو عليه حصة مستنفدة.

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")
الاستجابةالمهلةإعادة المحاولة
429 rate_limited، في الثانيةRetry-After: 1 مع جزء من الثانيةنعم
429 rate_limited، الحصةحتى تُجدَّد الحصة، وقد تكون أياماًلا
429 download_limitedRetry-After، حتى تنتهي النافذةنعم، بطلبات أضيق
503 snapshot_not_readyRetry-Afterنعم
500، مهلة منتهية، اتصال مقطوعأسية مع jitterنعم
400 و401 و403 و404 و410—لا، صحّح الطلب

تميّز الحصة المستنفدة عن حد الثانية بـ Retry-After: ثانية واحدة مقابل ساعات أو أيام حتى التجديد، مع Monthly call quota exceeded. في جسم الاستجابة. رموز الأخطاء وأجسامها في قسم الأخطاء من التوثيق.

محدّد المعدل على جهة العميل: token bucket

تعالج إعادة المحاولة خطأ 429، ويمنعه المحدّد على جهة العميل. يعمل token bucket هكذا: تصل الرموز بمعدل rate في الثانية، ويأخذ كل طلب رمزاً، والسلة الفارغة تجبرك على الانتظار. وتحدد السعة burst عدد الطلبات التي يمكن إرسالها متتالية دون توقف.

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)

خذ الحد من الحقل rps_limit في /account/usage (قسم الاستخدام) أو من الترويسة X-RateLimit-Limit. واضبط المعدل أقل قليلاً من الحد، مثلاً 0.9 * rps_limit: زمن الشبكة غير منتظم، فقد تصل الطلبات المرسلة بفارق نصف ثانية إلى الخادم متقاربة أكثر.

المراقبة: ترويسات X-RateLimit-* وX-Quota-*

تحمل استجابة البيانات حالة حدودك: تعطي X-RateLimit-Remaining وX-RateLimit-Reset ما تبقى في نافذة الثانية ووقت تجديدها، بينما تعطي X-Quota-Remaining وX-Quota-Limit وX-Quota-Reset الحصة المتبقية وحجمها ووقت التجديد بصيغة unix. والأنفع من أي رصيد منفرد هو الوتيرة: ما نسبة الحصة المستهلكة عند هذه النقطة من الفترة.

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")

تنتظر الدالة تجديد النافذة عند استنفاد حدها، وتحذّر عندما يتقدم استهلاك الحصة على التقويم بأكثر من 5 نقاط مئوية. مثال توضيحي: استُهلك 70% من الحصة بحلول اليوم 15، فبالوتيرة نفسها تنفد الاستدعاءات عند 15 / 0.7 ≈ 21.4 يوماً من الفترة. ويعطي /account/usage الأرقام نفسها دون ترويسات: calls_used وcalls_limit وperiod_resets_at.

جدول لعدة نقاط

مع عدة نقاط يحصل كل منها على فاصله الخاص، وتُوزَّع الطلبات الأولى كي لا تخرج دفعة واحدة. اختر الفاصل حسب المهمة، لكن لا تنزل عن freshness_sec: تحتاج السبريدات إلى معدل خطتك كاملاً، أما في كثير من الاستراتيجيات فتكفي دقيقة للتمويل والفائدة المفتوحة.

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 يعني ذلك 86,400 + 43,200 + 43,200 = 172,800 استدعاء في 30 يوماً، أي 8.64% من الحصة: السبريدات كل 30 ثانية، والتمويل والفائدة المفتوحة كل 60. تخرج الطلبات الأولى بفارق 30 / 3 = 10 ثوانٍ، ثم تحافظ كل نقطة على إيقاعها، ويحمي bucket.take() من التصادم. وبوت مبني على هذا الاستطلاع مع تنبيهات Telegram في بوت أربيتراج العملات الرقمية بـ Python.

ماذا تفعل عند 503 وأخطاء الخادم

بحسب RFC 9110 تعني 503 Service Unavailable حملاً زائداً مؤقتاً أو صيانة، وقد يقترح الخادم مهلة في Retry-After. في Genesis API هذا هو 503 snapshot_not_ready: تُعاد بناء البيانات أو يُعاد تشغيل مصدرها. أعد المحاولة بعد Retry-After ثانية؛ والمهلة عادةً بضع ثوانٍ.

وما دامت لا توجد استجابة جديدة، يحتفظ بوتك بالبيانات من آخر استطلاع، وهذه البيانات تقدم. قبل إرسال إشارة قارن meta.updated_at بالوقت الحالي: قد يكون زوج من لقطة عمرها دقيقة قد اختفى في البورصة. وتُشرح المخاطر الأخرى في درس مخاطر الأتمتة.

أعد محاولة 500 internal_error والمهل المنتهية والاتصالات المقطوعة بتراجع أسي. وإذا استمر الخطأ فراسل الدعم مع قيمة X-Request-Id ووقت الطلب بالتوقيت UTC والـ endpoint ورمز الحالة. ولا ترسل مفتاحك أبداً.

أسئلة وأجوبة

كم طلباً في الثانية يمكنني إرساله إلى Genesis API؟

بقدر ما تسمح خطتك: 1 في Trial، و2 في Start، و5 في Pro، و15 في Max. الحد لكل مفتاح ويشمل استجابات 304 والأخطاء. قيمة خطتك في الترويسة X-RateLimit-Limit وفي الحقل rps_limit من /account/usage.

هل تُحتسب الأخطاء واستجابات 304 من حصتي؟

لا. استجابة 200 وحدها تستهلك الحصة؛ أما 304 و429 و503 وسائر الأخطاء فمجانية ولا تكلف شيئاً. لكنها تأخذ خانات في حد الطلبات في الثانية، لذا تثير إعادة المحاولة بلا مهلة استجابات 429 جديدة.

كيف أبقى تحت 60 MB لكل 10 ثوانٍ؟

فعّل gzip: يحتسب الحد البيانات المضغوطة. أرسل If-None-Match مع مجموعات البيانات الكاملة: لا جسم في 304. وخذ الأقسام الثقيلة مثل تحليلات التمويل كشريحة coin، ولا تنزّل مجموعة البيانات الكاملة نفسها أكثر من مرة كل freshness_sec. الاستجابات الأصغر من 64 KB لا تُحتسب، وبحسب التوثيق فإن استطلاع كل مجموعة بيانات بحداثة خطتك يبقى تحت الحد بهامش واسع.

ماذا يعني الخطأ 429 Too Many Requests؟

رفض الخادم الطلب لأن العميل تجاوز حداً ضمن نافذة زمنية. قد تحمل الاستجابة Retry-After، وهو عدد الثواني المطلوب انتظارها؛ وبدونها ضاعف المهلة بعد كل إخفاق. في Genesis API يأتي 429 مع الرمز rate_limited أو download_limited.