استجابات Genesis API وأخطاؤه: صيغة JSON وETag وردّ 304 ورموز HTTP
باختصار
- الاستجابة الناجحة من Genesis API غلاف من
successوdataوmeta؛ والخطأ هوsuccess: falseمع كائنerrorفيه رمز ورسالة. - إرسال ETag السابق في
If-None-Matchيعيد304بلا جسم إذا لم تتغير البيانات، ولا يستهلك ردّ 304 أي حصة. - أعد المحاولة مع
429و503بعد مهلةRetry-After. أما400و401و403و404و410فلا تُصلحها إعادة المحاولة — غيّر الطلب أو المفتاح أو الخطة.
يردّ Genesis API على كل طلب بصيغة JSON، وهي صيغة بيانات نصية مبنية من كائنات مفتاح–قيمة ومصفوفات. تأتي الاستجابة الناجحة دائماً في غلاف واحد من success وdata وmeta؛ ويأتي الخطأ مع رمز حالة HTTP وكائن error. يخبر رمز الحالة برنامجك بما يفعله بعد ذلك: استخدام البيانات، أو الانتظار Retry-After ثانية ثم إعادة المحاولة، أو تصحيح الطلب.
غلاف الاستجابة: success وdata وmeta
استجابة GET /arbitrage/spot-spot مختصرة من التوثيق (نقطة النهاية متاحة في كل الخطط):
{
"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"
}
}
| الحقل | النوع | المحتوى |
|---|---|---|
success | boolean | true — نجح الطلب، false — خطأ |
data | مصفوفة أو كائن | بيانات نقطة النهاية |
meta.count | int | عدد العناصر في data |
meta.updated_at | int | وقت Unix الذي بُنيت فيه البيانات |
meta.freshness_sec | int | تأخير تقديم البيانات لخطتك بالثواني |
meta.plan | string | خطتك، وهي pro في المثال |
الاستثناء هو تحليلات التمويل: يحمل meta فيها count وupdated_at وschema_version، من دون freshness_sec أو plan. يُوصف الغلاف في قسم صيغة الاستجابة من التوثيق، وحقول data في صفحة كل نقطة نهاية.
تسري ثلاثة أعراف على كل نقاط النهاية:
- القيمة الفارغة هي
null: مثلاًmax_position_usdفي DEX – Futures تكونnullعندما لا توفر المنصة حدّ المركز؛ - السبريدات والمعدلات نسب مئوية:
"spread_pct": 0.92تعني 0.92%، لا 92%؛ - الطوابع الزمنية بثواني Unix:
1783802410هو 11 يوليو 2026، 20:40:10 UTC؛ أما التواريخ المرسلة كسلاسل نصية، مثلpool_created_atفي Cross-chain، فنوعها في التوثيق سلسلة نصية.
data: مصفوفة صفوف أو كائن
يُذكر شكل data في وصف كل نقطة نهاية. في GET /arbitrage/spot-spot هو مصفوفة: عنصر لكل زوج مراجحة، مثل صف الجدول في الموقع. وفي GET /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": { … }
}
/account/usage متاحة في كل الخطط وتعرض خطتك واستهلاك الحصة وقيمة freshness_sec: الاستعلام أكثر من ذلك لا يفيد. تُوصف الحقول في الاستخدام، ويُشرح أول طلب في البدء السريع. الشيفرة التي تتعامل مع عدة نقاط نهاية يجب أن تتحقق من الشكل صراحةً: isinstance(data, list) في Python.
الفلاتر: اختيارية، ومن دونها تحصل على المجموعة كاملة
كل معاملات الفلترة اختيارية: الطلب بدونها يعيد مجموعة بيانات نقطة النهاية كاملة. اذكر عدة منصات في exchange مفصولة بفواصل، وحدّد العملة برمزها في coin:
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 معاملات -d إلى سلسلة استعلام: ?coin=BTC&exchange=Binance,OKX&min_spread=0.5. اكتب أسماء المنصات كما تعود في حقول الاستجابة: ByBit وGate وMEXC. معاملات نقاط نهاية المراجحة في دليل نقاط نهاية المراجحة.
تحتسب الحصة الاستجابات لا الصفوف: الطلب بفلاتر أو بدونها استدعاء واحد. يقلّص الفلتر حجم جسم الاستجابة، وبالتالي حركة البيانات واستهلاك حدّ التنزيل. كل الحدود في دليل حدود Genesis API.
ضغط gzip
يرسل Genesis API مجموعات البيانات الكاملة والاستجابات الكبيرة مضغوطة بـ gzip عندما يرسل العميل الترويسة Accept-Encoding: gzip (RFC 9110، القسم 12.5.3). قد تصل الاستجابة الصغيرة غير مضغوطة.
مكتبة Python requests ترسل هذه الترويسة بنفسها وتفك ضغط الاستجابة. أما curl فلا يطلب الضغط من دون الخيار --compressed؛ ومعه يطلبه ويفكّه.
يحتسب حدّ التنزيل البيانات المضغوطة: 60 MB كحد أقصى لكل 10 ثوانٍ لكل مفتاح، ولا تُحتسب الاستجابات الأقل من 64 KB. عند تجاوز الحد تحصل على 429 download_limited.
ETag و304: تخطَّ البيانات غير المتغيرة
ETag ترويسة استجابة تحمل وسم إصدار للبيانات. يعيد العميل هذا الوسم في الترويسة If-None-Match. إذا لم تتغير البيانات يردّ الخادم بـ 304 Not Modified بلا جسم؛ وإذا تغيرت فبـ 200 عادي مع بيانات جديدة وETag جديد.
# مجموعة البيانات كاملة، بلا فلاتر: اطبع ترويسات الاستجابة فقط
curl -sS -D - -o /dev/null --compressed \
"https://api.genesisarbitrage.com/v1/arbitrage/spot-spot" \
-H "X-API-Key: gns_live_XXXXXXXXXXXXXXXX"
# كرّر الطلب بـ ETag من الاستجابة الأولى (قيمة توضيحية)
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 مع استجابة الطلب بلا فلاتر ويتغير مع كل لقطة بيانات جديدة. أما استجابة الطلب المفلتر فتُبنى لذلك الطلب وتأتي بلا ETag؛ والفلتر نفسه هنا يوفّر الحركة. يفيد ETag أكثر مع البيانات بطيئة التغير: ملخص تحليلات التمويل يتغير ETag فيه كل 15 دقيقة تقريباً، ولا تُحتسب ردود 304 ضمن حدّ التنزيل الكامل له.
ردّ 304 لا يستهلك حصة لكنه يُحتسب ضمن حدّ الطلبات في الثانية. أرسل الوسم كما وصل تماماً: وفق RFC 9110 هو سلسلة بين علامتي اقتباس، والبادئة W/ تدلّ على وسم ضعيف.
رموز الأخطاء وما يجب فعله
عند الخطأ يعيد Genesis API حالة HTTP المناسبة وجسماً فيه success: false:
{
"success": false,
"error": {
"code": "rate_limited",
"message": "Requests per second limit exceeded."
}
}
error.code رمز مقروء آلياً يستطيع برنامجك التفرّع بناءً عليه. وerror.message شرح للإنسان: مع 400 يذكر السبب، ومع 410 عنوان البديل.
| HTTP | error.code | المعنى | ما العمل |
|---|---|---|---|
400 | bad_request | معاملات الطلب غير صالحة، مثلاً volume=700 في /orderbooks/exec | صحّح المعاملات وفق message: سيفشل الطلب نفسه مجدداً |
401 | invalid_key | المفتاح غائب أو غير صالح أو ملغى، أو انتهى اشتراك API | تحقق من الترويسة X-API-Key وحالة الاشتراك في ملفك الشخصي |
403 | plan_restricted | نقطة النهاية ليست ضمن خطتك | انتقل إلى خطة تشملها أو أسقط الطلب |
404 | not_found | نقطة النهاية أو المورد غير موجود: مجموعة بيانات أو قسم أو عملة أو دفتر أوامر | تحقق من المسار والمعاملات بالرجوع إلى التوثيق |
410 | gone | نقطة النهاية أُلغيت | انتقل إلى العنوان المذكور في message |
429 | rate_limited | تجاوز حدّ الطلبات في الثانية، أو استُنفدت حصة الفترة | انتظر Retry-After ثانية وخفّف الوتيرة؛ وإذا استُنفدت الحصة فانتظر إعادة التعيين أو رقِّ الخطة |
429 | download_limited | تجاوز حجم التنزيل: 60 MB من البيانات المضغوطة كل 10 ثوانٍ لكل مفتاح | انتظر Retry-After، وقلّل الحركة بالفلاتر وcoin وIf-None-Match |
500 | internal_error | خطأ داخلي | أعد المحاولة لاحقاً؛ وإذا استمر فتواصل مع الدعم مع X-Request-Id |
503 | snapshot_not_ready | تجري إعادة بناء البيانات أو إعادة تشغيل مصدرها | أعد المحاولة بعد Retry-After ثانية |
تأتي الترويسة Retry-After مع 429 و503 وتحمل عدد الثواني للانتظار: عادةً بضع ثوانٍ، لكن عند استنفاد حصة الفترة تكون المدة حتى إعادة تعيين الحصة، وقد تبلغ أياماً. أخطاء 4xx و5xx لا تستهلك حصة لكنها تُحتسب ضمن حدّ الطلبات في الثانية، لذا غالباً ما تعيد المحاولة المبكرة الخطأ نفسه. مصطلحات القاموس: HTTP 429 وrate limit.
X-Request-Id: ما يُرسل إلى الدعم
كل استجابة من Genesis API، ناجحة أو لا، تحمل الترويسة X-Request-Id بمعرّف الطلب. إذا تكرر خطأ أو بدت البيانات خاطئة فأرسل إلى الدعم:
- قيمة
X-Request-Id؛ - وقت الطلب بتوقيت UTC؛
- نقطة النهاية مع معاملاتها، مثل
GET /arbitrage/spot-spot?coin=BTC؛ - حالة HTTP و
error.code.
لا ترسل مفتاحك. إذا وصل إلى محادثة أو سجلات أو شيفرة يراها آخرون، فأعد إصداره في ملفك الشخصي: يتوقف المفتاح القديم عن العمل فوراً.
ترتيب معالجة الاستجابة
تحقق من رمز الحالة
200— اقرأdataوmetaواحفظ ETag إن وصل.304— استخدم بيانات الاستجابة السابقة.عالج الأخطاء المؤقتة
429و503مع مهلة قصيرة — انتظرRetry-Afterثانية وأعد المحاولة، ثلاث مرات متتالية كحد أقصى.500— أعد المحاولة لاحقاً.توقف عند أخطاء الطلب
400و401و403و404و410، و429بمهلة ساعات أو أيام — صحّح المعاملات أو المفتاح أو الخطة، أو انتظر إعادة تعيين الحصة.تحقق من عمر البيانات
قارن
meta.updated_atبالوقت الحالي: البوت الذي يتصرف بناءً على لقطة قديمة يرى سبريدات اختفت بالفعل.جدولة الطلب التالي
ليس قبل
meta.freshness_secثانية، معIf-None-Matchللطلبات بلا فلاتر.
دالة get_json في Python
تجمع الدالة هذه القواعد: تحتفظ بآخر ETag لكل عنوان وتعيد البيانات السابقة عند 304، وتنتظر Retry-After مع 429 و503 وتعيد المحاولة حتى ثلاث مرات، لكنها لا تنتظر مهلاً تتجاوز دقيقة. الأخطاء الأخرى ترفع استثناءً بالحالة والرسالة وX-Request-Id. يُقرأ المفتاح من متغير البيئة GENESIS_API_KEY.
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 = {} # (المسار، المعاملات) -> (ETag، البيانات)
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): # طلب واحد مع 3 إعادات كحد أقصى
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] # البيانات لم تتغير
wait = float(r.headers.get("Retry-After", 1))
if r.status_code in (429, 503) and attempt < 3 and wait <= 60:
time.sleep(wait) # لا ننتظر ساعات أو أياماً
continue
try:
body = r.json()
except ValueError:
raise GenesisError(r.status_code, "not JSON") 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: # فقط مع الاستجابات بلا فلاتر
cache[key] = (r.headers["ETag"], body["data"])
return body["data"]
المعامل timeout=15 ضروري: فمن دون مهلة ينتظر requests الاستجابة إلى الأبد.
الاستعلام بفترة خطتك: تأتي مجموعة البيانات الكاملة مع ETag، وتُفلتر الصفوف في الشيفرة. أخطاء 4xx توقف البرنامج؛ وعطل الخادم ينتظر الدورة التالية.
pause = get_json("/account/usage")["freshness_sec"]
while True:
try:
rows = get_json("/arbitrage/spot-spot") # المجموعة كاملة
top = [x for x in rows if x["spread_pct"] >= 1]
print(len(top), "أزواج بسبريد 1% أو أكثر")
except GenesisError as e:
if e.status < 500:
raise # 4xx: الطلب أو المفتاح أو الخطة أو الحصة
print("خطأ في الخادم، إعادة المحاولة في الدورة التالية:", e)
time.sleep(pause)
أسئلة وأجوبة
هل يستهلك ردّ 304 حصة؟
لا. الاستجابات 200 وحدها تستهلك الحصة. ردود 304 وأخطاء 4xx و5xx مجانية لكنها تُحتسب ضمن حدّ الطلبات في الثانية.
ماذا أفعل بعد 410 ؟
نقطة النهاية أُلغيت، وعنوان البديل في error.message. مثلاً أُلغيت GET /arbitrage/predictions في 15 نوفمبر 2026، ويشير message فيها إلى /predictions/arbitrage. حدّث المسار في شيفرتك.
لماذا data فارغة دون أي خطأ؟
أزالت الفلاتر كل الصفوف: مثلاً min_spread أعلى من كل السبريدات الحالية. تكون meta.count في هذه الاستجابة 0، فخفّف الفلتر.
لماذا لا يوجد ETag في الاستجابة؟
يأتي ETag مع استجابة الطلب بلا فلاتر. أما استجابة طلب فيه coin أو exchange أو min_spread أو فلتر آخر فتُبنى لذلك الطلب وتأتي بلا وسم، لذا لا ينطبق If-None-Match عليها.