أول طلب API: HTTP والترويسات وJSON
باختصار
- طلب HTTP إلى API يتكوّن من طريقة وعنوان يُبنى من الرابط الأساسي والمسار والمعاملات وترويسات. يوضع مفتاح Genesis API في الترويسة
X-API-Keyفقط. - رمز الحالة يحدد خطوتك التالية:
200يعني اقرأ البيانات، و304يعني أن شيئاً لم يتغير، و401و403يعنيان تحقق من المفتاح والخطة، و429و503يعنيان انتظر عدد الثواني فيRetry-After. - استجابة Genesis API غلاف من
successوdataوmeta. النسب المئوية تصل كأرقام عادية (0.01تعني 0.01%)، والوقت يأتي بثواني unix. - من أخطاء المبتدئين الشائعة: مفتاح في الرابط، ومتغير بيئة فارغ، وخطأ مطبعي في المسار أو في اسم معامل. الخطأ في اسم المعامل لا يثير أي خطأ: تحصل على مجموعة البيانات كاملة بدل المفلترة.
لاستدعاء API يرسل برنامجك طلب HTTP مكوّناً من طريقة وعنوان وترويسات، ويعيد الخادم رمز حالة وترويسات خاصة به وجسماً هو في Genesis API بصيغة JSON. يمكنك إرسال الطلب من الطرفية بـ curl أو من كود بأي لغة فيها عميل HTTP. الطلب الأول أدناه يتحقق من المفتاح عبر /account/usage، والثاني يجلب معدلات تمويل BTC من /funding/rates. ما هو API وما الذي يمكن أتمتته به مشروح في الدرس 1.
تشريح الطلب
هذا طلب معدلات تمويل BTC كما يرسله curl إلى الخادم، بحسب ما يعرضه الخيار -v في الأسطر التي تبدأ بـ > (المفتاح مستبدل بنص نائب):
> GET /v1/funding/rates?coin=BTC HTTP/1.1
> Host: api.genesisarbitrage.com
> User-Agent: curl/8.7.1
> Accept: */*
> X-API-Key: gns_live_XXXXXXXXXXXXXXXX
| الجزء | في المثال | ماذا يعني |
|---|---|---|
| الطريقة | GET | قراءة البيانات؛ كل endpoint في Genesis API هو GET |
| الرابط الأساسي | https://api.genesisarbitrage.com/v1 | الخادم وإصدار API |
| المسار | /funding/rates | endpoint معدلات التمويل |
| المعاملات | ?coin=BTC | مرشّح: BTC فقط |
| الترويسة | X-API-Key | المفتاح الذي يتعرف به الخادم على حسابك وخطتك |
تأتي المعاملات بعد ? على شكل أزواج name=value تفصل بينها &: ?coin=BTC&exchange=Binance,OKX. مرشحات Genesis API اختيارية، لذا بدون coin يعيد الـ endpoint نفسه كل العملات. تُكتب الكسور العشرية بنقطة وليس بفاصلة: min_spread=0.5.
الترويسات أسطر بصيغة name: value تسافر مع العنوان. أسماء الترويسات لا تتأثر بحالة الأحرف (RFC 9110، القسم 5.1): X-API-Key وx-api-key ترويسة واحدة، وx-request-id بأحرف صغيرة في مخرجات curl هي نفسها X-Request-Id. يقبل Genesis API المفتاح في X-API-Key فقط.
رموز الحالة
يحمل السطر الأول من الاستجابة رمز الحالة، وبرنامجك يقرر خطوته التالية بناءً عليه:
| الرمز | ماذا يعني | ماذا تفعل |
|---|---|---|
200 | تمت خدمة الطلب والبيانات في الجسم | اقرأ data وmeta |
304 | البيانات لم تتغير منذ استجابتك الأخيرة | أعد استخدام البيانات السابقة |
401 | المفتاح مفقود أو غير صالح أو ملغى أو انتهى الاشتراك | تحقق من الترويسة ومن الاشتراك |
403 | الـ endpoint ليس في خطتك (plan_restricted) | غيّر الخطة أو تخلَّ عن الطلب |
429 | تجاوز حد الطلبات أو التنزيل أو الحصة | انتظر Retry-After ثانية |
503 | البيانات قيد إعادة البناء (snapshot_not_ready) | أعد المحاولة بعد Retry-After ثانية |
الاستجابة 200 وحدها تستهلك حصتك: أما 304 والأخطاء فمجانية لكنها تُحتسب ضمن حد الطلبات في الثانية. لا تعود 304 إلا لطلب فيه ترويسة If-None-Match؛ وهذه الترويسة ورموز 400 و404 و410 و500 مشروحة في استجابات Genesis API وأخطاؤه. ولماذا تحتاج إعادة المحاولة بعد 429 إلى توقف، يشرحه مدخل المسرد HTTP 429 Too Many Requests.
الطلب الأول: /account/usage
يعرض /account/usage حالة مفتاحك: الخطة والحصة المستهلكة والحدود. وهو متاح في كل الخطط ولا يستهلك استدعاءً، لذا يذهب طلبك الأول إليه. ضع المفتاح أولاً في متغير بيئة، ثم أرسل الطلب:
# الصق المفتاح واضغط Enter: لن يظهر على الشاشة
read -s GENESIS_API_KEY
export GENESIS_API_KEY
curl -i "https://api.genesisarbitrage.com/v1/account/usage" \
-H "X-API-Key: $GENESIS_API_KEY"
يطبع الخيار -i سطر الحالة والترويسات قبل الجسم. جسم الاستجابة، مثال توضيحي لخطة Trial:
{
"success": true,
"data": {
"plan": "trial",
"calls_used": 0,
"calls_limit": 500000,
"rps_limit": 1,
"freshness_sec": 60,
"period_resets_at": 1796463000
},
"meta": {
"count": 1,
"updated_at": 1794730811,
"freshness_sec": 60,
"plan": "trial"
}
}
plan هي خطتك، وcalls_used من calls_limit هو استهلاك الحصة خلال فترة 30 يوماً. يظهر في المثال 0 لأنه لم تُرسل طلبات أخرى بعد، و/account/usage نفسه لا يستهلك استدعاءً. rps_limit هو عدد الطلبات في الثانية، وfreshness_sec هو وتيرة تحديث بيانات خطتك، وperiod_resets_at هو موعد تصفير الحصة. الحقول موصوفة في قسم الاستخدام من التوثيق.
ابحث بين الترويسات عن X-Request-Id، وهو معرّف الطلب الذي ترسله إلى الدعم بدل مفتاحك، وعن X-RateLimit-Remaining، أي عدد الطلبات المتبقية في نافذة الحد الحالية.
الطلب نفسه بلغة Python
سكربت لـ Python 3.10+ مع مكتبة requests يقرأ المفتاح من متغير البيئة نفسه:
import os
from datetime import datetime, timezone
import requests
BASE = "https://api.genesisarbitrage.com/v1"
key = os.environ["GENESIS_API_KEY"] # KeyError إذا لم يكن المتغير معيّناً
r = requests.get(
BASE + "/account/usage",
headers={"X-API-Key": key},
timeout=10, # بدون مهلة قد تنتظر requests إلى الأبد
)
body = r.json()
if r.status_code != 200 or not body.get("success"):
err = body.get("error") or {}
raise SystemExit(f"{r.status_code} {err.get('code')}")
usage = body["data"]
ts = usage["period_resets_at"]
resets = datetime.fromtimestamp(ts, timezone.utc)
print("plan:", usage["plan"])
print("calls:", usage["calls_used"], "of", usage["calls_limit"])
print("quota resets:", resets.strftime("%Y-%m-%d %H:%M UTC"))
print("X-Request-Id:", r.headers.get("X-Request-Id"))
يوقف os.environ["GENESIS_API_KEY"] السكربت إذا لم يكن المتغير معيّناً، وهذا أفضل من إرسال طلب بلا مفتاح والحصول على 401. وr.headers لا يتأثر بحالة الأحرف، فيُعثر على X-Request-Id حتى لو أرسل الخادم x-request-id.
period_resets_at هو وقت unix: عدد الثواني منذ 1 يناير 1970، 00:00 UTC. وdatetime.fromtimestamp(ts, timezone.utc) يحوّله إلى تاريخ: 1796463000 هو 5 ديسمبر 2026، 09:30 UTC.
الطلب الثاني: معدلات تمويل BTC
التمويل دفعة دورية بين أصحاب مراكز الشراء (long) والبيع (short) على العقد الآجل الدائم، وتسوّيه المنصات كل 8 أو 4 أو ساعة واحدة. يعيد /funding/rates المعدلات عبر كل المنصات، ويحصرها المعامل coin في عملة واحدة. استجابة GET /funding/rates?coin=BTC، مثال توضيحي بمنصتين من القائمة:
{
"success": true,
"data": [
{
"coin": "BTC",
"exchanges": [
{
"exchange": "Bitget",
"funding_pct": 0.01,
"funding_8h_pct": 0.01,
"next_payout": "00:00",
"interval": "8h",
"price": 96021.5,
"trade_url": "https://www.bitget.com/futures/usdt/BTCUSDT"
},
{
"exchange": "Hyper",
"funding_pct": 0.0013,
"funding_8h_pct": 0.0104,
"next_payout": null,
"interval": "1h",
"price": 96030.0,
"trade_url": "https://app.hyperliquid.xyz/trade/BTC"
},
…
]
}
],
"meta": {
"count": 1,
"updated_at": 1794675861,
"freshness_sec": 60,
"plan": "trial"
}
}
كيف تقرأ هذه الاستجابة:
- الغلاف:
successتساويtrue، والبيانات فيdata، والحقول الخدمية فيmeta؛ وmeta.countهو عدد العناصر فيdata، أي عملة واحدة عندcoin=BTC، وبداخلها مصفوفةexchanges؛ - النسب المئوية تصل كأرقام عادية:
"funding_pct": 0.01تعني 0.01% لكل فترة، وليس 1%؛ وعلى مركز بقيمة 10,000 دولار تساوي دفعة واحدة بهذا المعدل 10,000 × 0.01 / 100 = دولاراً واحداً؛ funding_8h_pctيوحّد المعدل على 8 ساعات لتقارَن المنصات ذات الفترات المختلفة مباشرة: تسوّي Hyper كل ساعة، و0.0013 × 8 = 0.0104% لكل 8 ساعات؛next_payoutهو وقت الدفعة التالية بتوقيت UTC كنص بصيغة "HH:MM"، وnullتعني غياب البيانات وليس الصفر؛meta.updated_atهو وقت unix الذي بُنيت فيه اللقطة: 1794675861 هو 14 نوفمبر 2026، 17:04:21 UTC؛ وفي خطة Trial تتجدد اللقطة كل 60 ثانية.
كل الحقول في قسم معدلات التمويل من التوثيق. الكتلة التالية تكمل السكربت: BASE وkey والاستيرادات موجودة فيه أصلاً.
r = requests.get(
BASE + "/funding/rates",
headers={"X-API-Key": key},
params={"coin": "BTC"}, # تبني requests الرابط ?coin=BTC
timeout=10,
)
r.raise_for_status() # يرمي استثناءً عند 4xx و5xx
body = r.json()
if not body["data"]:
raise SystemExit("العملة غير موجودة في البيانات: تحقق من الرمز")
ts = body["meta"]["updated_at"]
snap = datetime.fromtimestamp(ts, timezone.utc)
print("snapshot from", snap.strftime("%Y-%m-%d %H:%M:%S UTC"))
rows = body["data"][0]["exchanges"]
rows.sort(key=lambda e: e["funding_8h_pct"], reverse=True)
for e in rows:
print(f'{e["exchange"]:<8} {e["funding_pct"]:>7}% '
f'per {e["interval"] or "?"}, '
f'{e["funding_8h_pct"]:>7}% per 8h')
على الاستجابة المثالية يطبع السكربت:
snapshot from 2026-11-14 17:04:21 UTC
Hyper 0.0013% per 1h, 0.0104% per 8h
Bitget 0.01% per 8h, 0.01% per 8h
تتصدر Hyper على Bitget مع أن معدلها لكل فترة أقل بنحو 0.01 / 0.0013 ≈ 7.7 مرة. بدون التوحيد على 8 ساعات تخرج هذه المقارنة خاطئة.
أخطاء المبتدئين الشائعة
| الخطأ | ماذا يعيد الخادم | كيف تصلحه |
|---|---|---|
المفتاح في الرابط: ?api_key=… | 401 و"Missing X-API-Key header." | أرسل المفتاح في ترويسة X-API-Key فقط |
| متغير المفتاح فارغ | 401 بالنص نفسه: يتجاهل curl الترويسة الفارغة | تحقق من الطول: echo ${#GENESIS_API_KEY} |
خطأ مطبعي في المسار: /v1/funding/rate أو بلا /v1 | 404 | قارن المسار بالتوثيق |
خطأ مطبعي في اسم المعامل: coins=BTC | 200 وكل العملات: المعامل المجهول يُتجاهل | تحقق من meta.count: مع coin=BTC يساوي 1 |
فاصلة عشرية: min_spread=0,5 | 200 دون تطبيق أي مرشّح | استخدم النقطة: 0.5 |
زوج بدل الرمز: coin=BTCUSDT | 200 وdata فارغة وmeta.count يساوي 0 | استخدم رمز العملة: BTC |
الخطأ المطبعي في المعامل أخبثها: لا يظهر أي خطأ، ومع ذلك يحصل السكربت على مجموعة البيانات كاملة بدل عملة واحدة ويصرف استدعاءً عليها. بعد إضافة مرشّح جديد قارن meta.count بما تتوقعه.
جرّب بنفسك
أرسل طلباً بلا مفتاح
curl -i "https://api.genesisarbitrage.com/v1/account/usage"يعيد401معinvalid_keyو"Missing X-API-Key header." في الجسم. ابحث عنx-request-idبين الترويسات.كرّره مع المفتاح
عيّن المتغير بـ
read -sوأرسل الطلب من قسم/account/usage. تحصل على200وخطتك فيdata.plan.تحقق من تاريخ التصفير
شغّل سكربت Python وقارن تاريخ تصفير الحصة بسطر "resets …" في كتلة "Genesis API" في ملفك الشخصي. الحصول على المفتاح خطوة بخطوة مشروح في البداية السريعة مع Genesis API.
ابحث عن أعلى معدل
أضف الكتلة الثانية إلى السكربت وابحث عن المنصة صاحبة أعلى
funding_8h_pct. وحّدfunding_pctالخاص بها على 8 ساعات يدوياً: المعدل × 8 / الفترة بالساعات.اكسر الطلب عمداً
غيّر
coinإلىcoinsوقارنmeta.count، ثم احذفsمن/funding/ratesوانظر إلى رمز الحالة.
أي الـ endpoints تخدم القرارات المتعلقة بالسبريدات ودفاتر الأوامر والتمويل هو موضوع الدرس 3.
أسئلة وأجوبة
هل يمكنني استدعاء API من المتصفح؟
فقط العناوين التي لا تحتاج مفتاحاً: يُفتح https://api.genesisarbitrage.com/health في المتصفح ويعرض {"ok":true}. شريط العنوان لا يستطيع إضافة ترويسة X-API-Key، لذا تمر الطلبات ذات المفتاح عبر curl أو سكربت أو نموذج "جرّب الطلب" في التوثيق. لا تضمّن المفتاح أبداً في كود موقع أو إضافة: كل من يفتح مصدر الصفحة سيراه.
بماذا يختلف الخيار -i عن -v في curl؟
يطبع -i سطر الحالة وترويسات الاستجابة قبل الجسم. أما -v فيعرض الطلب نفسه أيضاً: الأسطر التي تبدأ بـ > هي ما ذهب إلى الخادم، والتي تبدأ بـ < هي ما عاد منه.
كيف أحوّل وقت unix إلى تاريخ دون Python؟
على macOS نفّذ date -u -r 1796463000؛ وعلى Linux نفّذ date -u -d @1796463000. لهذا الرقم يُظهر الأمران 5 ديسمبر 2026، 09:30 UTC.