حدود 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,000 | 1 | 60 ث |
| Start، $50 شهرياً | 2,000,000 | 2 | 30 ث |
| Pro، $100 شهرياً | 5,000,000 | 5 | 10 ث |
| Max، $200 شهرياً | 10,000,000 | 15 | 5 ث |
حداثة البيانات هي الفاصل الزمني الذي تحصل فيه خطتك على لقطة جديدة: كل 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-Limit | 5 | حد الطلبات في الثانية لخطتك |
X-RateLimit-Remaining | 4 | الطلبات المتبقية في النافذة الحالية |
X-RateLimit-Reset | 1785200001 | وقت unix لإعادة ضبط النافذة |
X-Quota-Limit | 5000000 | حصة الاستدعاءات للفترة البالغة 30 يوماً |
X-Quota-Remaining | 4815799 | الاستدعاءات المتبقية في الفترة |
X-Quota-Reset | 1786492800 | وقت unix لإعادة ضبط الحصة |
Retry-After | 1 | ثوانٍ الانتظار قبل إعادة المحاولة، مع 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": { … }
}
| الحقل | النوع | المعنى |
|---|---|---|
plan | string | الخطة: trial أو start أو pro أو max |
calls_used | int | الاستدعاءات المستخدمة في الفترة الحالية |
calls_limit | int | حصة الاستدعاءات لكل فترة |
rps_limit | int | حد الطلبات في الثانية |
freshness_sec | int | تأخر البيانات بالثواني |
period_resets_at | int | وقت 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 ثوانٍ على مدار الساعة.
- الطلبات في الثانية: 3 / 10 = 0.3 في المتوسط. إذا أُرسلت الثلاثة معاً وقعت في الثانية نفسها، وفي Trial وStart تعيد الزائدة
429. - الاستدعاءات في اليوم: 86,400 / 10 = 8,640 استطلاعاً، 8,640 × 3 = 25,920 استدعاءً.
- الاستدعاءات لكل 30 يوماً: 25,920 × 30 = 777,600. وهذا أكثر من حصة Trial البالغة 500,000؛ وفي Start يساوي 777,600 / 2,000,000 = 38.88% من الحصة.
- الحداثة: في Start تتحدث اللقطة كل 30 ثانية، أي 86,400 / 30 = 2,880 مرة في اليوم. تأتي البيانات الجديدة من 2,880 × 3 × 30 = 259,200 استدعاء، أما الـ 777,600 − 259,200 = 518,400 الباقية فتعيد الشيء نفسه.
البوت نفسه عند الاستطلاع بحداثة كل خطة:
| الحداثة والاستطلاع | الاستدعاءات لكل 30 يوماً | الخطة | نسبة الحصة |
|---|---|---|---|
| كل 60 ث | 129,600 | Trial | 26% |
| كل 30 ث | 259,200 | Start | 13% |
| كل 10 ث | 777,600 | Pro | 16% |
| كل 5 ث | 1,555,200 | Max | 16% |
للاستطلاع كل 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)
تغيير الخطة وتجديدها
- تسري الخطة الجديدة بعد الدفع مباشرة: حدود وحداثة جديدة، وتبدأ الحصة من الصفر، ويسقط ما تبقى من الخطة السابقة. ينبهك الموقع قبل الدفع.
- تجديد الخطة نفسها يضيف أياماً إلى المدة ولا يعيد ضبط الحصة: تستمر فترة الـ 30 يوماً الحالية.
- يبقى مفتاحك كما هو عند تغيير الخطة أو تجديدها، فلا تحتاج برامجك إلى تحديث.
- يُطبَّق خصم المدة على السعر الشهري: Pro لمدة 6 أشهر هي $100 × 0.8 × 6 = $480 بدلاً من $600، ولمدة 3 أشهر $100 × 0.9 × 3 = $270.
طريقة الحصول على المفتاح وحفظه موصوفة في دليل مفتاح Genesis API.
أسئلة وأجوبة
ماذا يحدث إذا نفدت الحصة مبكراً؟
يعيد الخادم 429 rate_limited مع Retry-After حتى إعادة ضبط الحصة، ولا يُحتسب شيء. انتظر الفترة الجديدة أو ادفع لخطة أعلى: تسري فوراً مع حصة جديدة.
هل تُحتسب استجابات 304 والأخطاء ضمن الحدود؟
ليس ضمن الحصة: 200 وحدها تستهلكها. لكنها تُحتسب ضمن حد الطلبات في الثانية: استجابات 304 والأخطاء تشغل خانات في نافذة الثانية.
كيف أتحقق من الحصة المتبقية دون استهلاك استدعاء؟
اقرأ X-Quota-Remaining في استجابة البيانات أو استدعِ /account/usage: هذا الطلب لا يستهلك استدعاءً. كما يعرض سطر «Calls used» في ملفك الشخصي الاستخدام.
هل يمكن التحايل على الحد بعدة مفاتيح؟
لا. لكل حساب مفتاح واحد، والحدود تُحتسب لكل مفتاح، وتغيير عنوان IP لا يغيّرها. فتح عدة حسابات للتحايل على الحدود يخالف القواعد؛ وإن احتجت إلى أكثر فانتقل إلى خطة أعلى.