Genesis Arbitrage

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

حدود Genesis API: حصة الاستدعاءات والطلبات في الثانية وحداثة البيانات وأخطاء 429

باختصار

  • تحدد خطتك حصة الاستدعاءات لكل 30 يوماً (من 500K في Trial إلى 10M في Max) وحد الطلبات في الثانية (من 1 إلى 15) وحداثة البيانات (من 60 إلى 5 ثوانٍ).
  • الاستجابة 200 وحدها تستهلك الحصة. استجابات 304 والأخطاء مجانية، لكنها تشغل خانة في حد الطلبات في الثانية؛ وعند تجاوز أي حد يعيد الخادم 429 دون أن يحتسب شيئاً.
  • الاستطلاع بوتيرة أسرع من meta.freshness_sec لا يجلب بيانات جديدة: تحصل خطتك على لقطة جديدة مرة واحدة في كل فترة كهذه، ويحوّل If-None-Match الطلبات الزائدة إلى استجابات 304 مجانية.

حدود Genesis API أربعة سقوف لكل مفتاح: حصة الاستدعاءات لفترة 30 يوماً، ومعدل الطلبات في الثانية، وحداثة البيانات، وحجم التنزيل. تحدد خطتك الثلاثة الأولى، أما حجم التنزيل فواحد للجميع: 60 MB من البيانات المضغوطة كل 10 ثوانٍ. عند تجاوز أي حد يعيد الخادم خطأ 429 دون أن يحتسب شيئاً.

الحدود حسب الخطة

الخطةالاستدعاءات لكل 30 يوماًالطلبات في الثانيةالحداثة
Trial، $20 شهرياً500,000160 ث
Start، $50 شهرياً2,000,000230 ث
Pro، $100 شهرياً5,000,000510 ث
Max، $200 شهرياً10,000,000155 ث

حداثة البيانات هي الفاصل الزمني الذي تحصل فيه خطتك على لقطة جديدة: كل 60 ثانية في Trial وكل 5 في Max. تحمل الاستجابات هذه القيمة في الحقل meta.freshness_sec. الدفع لمدة 3 أشهر يوفّر 10%، ولمدة 6 أشهر 20%. مقارنة الخطط في صفحة أسعار Genesis API، والقواعد في قسم الخطط والحدود من التوثيق.

ما الذي يستهلك الحصة

الاستدعاء هو استجابة 200. استجابات 304 (البيانات لم تتغير) وأخطاء 4xx و5xx لا تستهلك الحصة، لكنها تُحتسب ضمن حد الطلبات في الثانية. الطلب إلى /account/usage لا يستهلك استدعاءً.

تغطي الحصة فترة 30 يوماً وليس شهراً تقويمياً. وقت إعادة الضبط موجود في الترويسة X-Quota-Reset وفي الحقل period_resets_at وفي سطر «resets …» في ملفك الشخصي. عندما تنفد الحصة يرد الخادم بـ 429 rate_limited، وتحمل Retry-After عدد الثواني حتى إعادة الضبط، وقد يبلغ ذلك أياماً.

ترويسات حدود الطلبات

تحمل استجابة نقطة نهاية البيانات حالة حدودك (قيم توضيحية):

الترويسةمثالما تُظهره
X-RateLimit-Limit5حد الطلبات في الثانية لخطتك
X-RateLimit-Remaining4الطلبات المتبقية في النافذة الحالية
X-RateLimit-Reset1785200001وقت unix لإعادة ضبط النافذة
X-Quota-Limit5000000حصة الاستدعاءات للفترة البالغة 30 يوماً
X-Quota-Remaining4815799الاستدعاءات المتبقية في الفترة
X-Quota-Reset1786492800وقت unix لإعادة ضبط الحصة
Retry-After1ثوانٍ الانتظار قبل إعادة المحاولة، مع 429 و503

نافذة الطلبات في الثانية مدتها ثانية واحدة، لذا في الاستجابة العادية تشير X-RateLimit-Reset إلى بداية الثانية التالية. المتبقي من الحصة في المثال: 5,000,000 − 184,201 = 4,815,799 استدعاءً، وهي الأرقام نفسها التي يعيدها /account/usage.

نقطة النهاية /account/usage

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": { … }
}
الحقلالنوعالمعنى
planstringالخطة: trial أو start أو pro أو max
calls_usedintالاستدعاءات المستخدمة في الفترة الحالية
calls_limitintحصة الاستدعاءات لكل فترة
rps_limitintحد الطلبات في الثانية
freshness_secintتأخر البيانات بالثواني
period_resets_atintوقت unix لإعادة ضبط الحصة

نقطة النهاية متاحة في كل الخطط وموصوفة في قسم الاستخدام. استدعها عند تشغيل البوت للتحقق من الخطة والحصة المتبقية قبل بدء الاستطلاع.

أخطاء 429: rate_limited وdownload_limited

الاستجابةمتى تأتيما العمل
429 rate_limitedطلبات في الثانية أكثر مما تسمح به خطتكانتظر مدة Retry-After وباعد بين الطلبات
429 rate_limitedاستُهلكت حصة الفترةانتظر إعادة الضبط أو غيّر الخطة
429 rate_limitedتنزيل كامل لتحليلات التمويل أبكر من المسموحخذ شريحة بالمعامل coin أو أرسل If-None-Match
429 download_limitedأكثر من 60 MB من البيانات المضغوطة خلال 10 ثوانٍانتظر مدة Retry-After وضيّق الطلب بالمرشحات

رمز الحالة 429 Too Many Requests معرّف في RFC 6585، حيث الترويسة Retry-After اختيارية. يرسلها Genesis API مع كل 429، وبالثواني دائماً.

الاستجابات الأصغر من 64 KB لا تُحتسب ضمن حجم التنزيل، واستطلاع كل مجموعات البيانات بحداثة خطتك يتسع ضمن الحد بهامش مريح. للتنزيل الكامل لتحليلات التمويل دون coin حد خاص: /funding/analytics/summary و/funding/analytics/recent مرة كل 60 ثانية، و/funding/analytics/daily مرة كل 300 ثانية لكل مفتاح. الطلبات مع coin واستجابات 304 بلا حد؛ والتفاصيل في قسم تحليلات التمويل.

الوصول حسب الخطة و403 plan_restricted

الخطةما هو متاح
Trialمراجحة CEX (Spot – Spot وSpot – Futures وFutures – Futures)، ومعدلات التمويل وفرق التمويل، وFair – Last، وCEX Pumps – Dumps، والفائدة المفتوحة، وإشارات AI، والبحث عن العملات، و/account/usage
Startكل ما في Trial، إضافة إلى الأسهم /arbitrage/stocks وأقسام السلسلة /onchain/{section} ومراجحة التنبؤات بوضعي exact وdutch وحالة المنصات
Pro وMaxكل نقاط النهاية: DEX – Spot وDEX – Futures وCrosschain وDEX Dumps ودفاتر الأوامر وتحليلات التمويل وتحليلات أسواق التنبؤ والأموال الذكية والصفقات والمتداولون ووضعا llm وsport وعمليات تبديل DEX وتحليلات OnChain والعملة

نقطة النهاية خارج خطتك تعيد 403، وكذلك طلب mode=sport إلى /predictions/arbitrage في Start:

{
  "success": false,
  "error": {
    "code": "plan_restricted",
    "message": "This endpoint is not included in your plan."
  }
}

الخطأ 403 لا يستهلك الحصة. وإعادة المحاولة بلا جدوى: لا يفتح الوصول إلا الانتقال إلى خطة أعلى.

كيف تختار الخطة المناسبة لحمل عملك

مثال توضيحي: بوت يستطلع ثلاث نقاط نهاية، /arbitrage/spot-spot و/funding/spread و/market/open-interest، كل 10 ثوانٍ على مدار الساعة.

البوت نفسه عند الاستطلاع بحداثة كل خطة:

الحداثة والاستطلاعالاستدعاءات لكل 30 يوماًالخطةنسبة الحصة
كل 60 ث129,600Trial26%
كل 30 ث259,200Start13%
كل 10 ث777,600Pro16%
كل 5 ث1,555,200Max16%

للاستطلاع كل 10 ثوانٍ تكون Pro وما فوقها خياراً منطقياً: 777,600 / 5,000,000 = 15.552% من الحصة، وحد 5 طلبات في الثانية يكفي لإرسال الثلاثة معاً. وإن كان البوت يقبل بيانات عمرها 30 ثانية، فإن Start مع استطلاع كل 30 ثانية يستهلك 259,200 / 2,000,000 = 12.96% من الحصة.

استطلاع بلا استدعاءات مهدرة: ETag وRetry-After

تحصل خطتك على لقطة جديدة كل meta.freshness_sec ثانية، والاستطلاع بوتيرة أسرع يعيد اللقطة نفسها بالقيمة نفسها في meta.updated_at. دون الترويسة If-None-Match تكون هذه الاستجابة 200 واستدعاءً مستهلكاً. ومعها يرد الخادم بـ 304 دون جسم: لا تُمَس الحصة، لكن تُشغل خانة في حد الطلبات في الثانية.

لا يأتي ETag مع كل استجابة. تعيده مجموعات البيانات الكاملة، أي الطلبات بلا مرشحات، مثل /funding/spread في المثال أدناه. الاستجابة المرشحة (coin وmin_spread وغيرها) بلا ETag، وكل استطلاع يكلّف استدعاءً: المرشحات توفر الحركة، وETag يوفر الحصة. إعادة المحاولة والضغط موصوفان في كيف تستطلع API بكفاءة وفي دليل الاستجابات والأخطاء.

import os
import time

import requests

URL = "https://api.genesisarbitrage.com/v1/funding/spread"
KEY = os.environ["GENESIS_API_KEY"]
etag, pause = None, 30

while True:
    headers = {"X-API-Key": KEY}
    if etag:
        headers["If-None-Match"] = etag
    r = requests.get(URL, headers=headers, timeout=15)
    if r.status_code in (429, 500, 503):
        wait = int(r.headers.get("Retry-After", "5"))
        if wait > 600:  # نفدت الحصة، نتوقف هنا
            raise SystemExit(f"Quota used up, resets in {wait} s")
        time.sleep(wait)
        continue
    r.raise_for_status()  # إعادة المحاولة لن تصلح 401 أو 403
    left = r.headers.get("X-Quota-Remaining")  # قد تكون غائبة
    if left is not None and int(left) < 10_000:
        print("Quota running low:", left)
    if r.status_code == 200:  # مع 304 البيانات لم تتغير
        etag = r.headers.get("ETag")
        body = r.json()
        pause = body["meta"].get("freshness_sec", pause)
        print(body["meta"]["count"], "coins in the response")
    time.sleep(pause)

تغيير الخطة وتجديدها

طريقة الحصول على المفتاح وحفظه موصوفة في دليل مفتاح Genesis API.

أسئلة وأجوبة

ماذا يحدث إذا نفدت الحصة مبكراً؟

يعيد الخادم 429 rate_limited مع Retry-After حتى إعادة ضبط الحصة، ولا يُحتسب شيء. انتظر الفترة الجديدة أو ادفع لخطة أعلى: تسري فوراً مع حصة جديدة.

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

ليس ضمن الحصة: 200 وحدها تستهلكها. لكنها تُحتسب ضمن حد الطلبات في الثانية: استجابات 304 والأخطاء تشغل خانات في نافذة الثانية.

كيف أتحقق من الحصة المتبقية دون استهلاك استدعاء؟

اقرأ X-Quota-Remaining في استجابة البيانات أو استدعِ /account/usage: هذا الطلب لا يستهلك استدعاءً. كما يعرض سطر «Calls used» في ملفك الشخصي الاستخدام.

هل يمكن التحايل على الحد بعدة مفاتيح؟

لا. لكل حساب مفتاح واحد، والحدود تُحتسب لكل مفتاح، وتغيير عنوان IP لا يغيّرها. فتح عدة حسابات للتحايل على الحدود يخالف القواعد؛ وإن احتجت إلى أكثر فانتقل إلى خطة أعلى.