Genesis Arbitrage

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

أول طلب 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/ratesendpoint معدلات التمويل
المعاملات?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"
  }
}

كيف تقرأ هذه الاستجابة:

كل الحقول في قسم معدلات التمويل من التوثيق. الكتلة التالية تكمل السكربت: 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 أو بلا /v1404قارن المسار بالتوثيق
خطأ مطبعي في اسم المعامل: coins=BTC200 وكل العملات: المعامل المجهول يُتجاهلتحقق من meta.count: مع coin=BTC يساوي 1
فاصلة عشرية: min_spread=0,5200 دون تطبيق أي مرشّحاستخدم النقطة: 0.5
زوج بدل الرمز: coin=BTCUSDT200 وdata فارغة وmeta.count يساوي 0استخدم رمز العملة: BTC

الخطأ المطبعي في المعامل أخبثها: لا يظهر أي خطأ، ومع ذلك يحصل السكربت على مجموعة البيانات كاملة بدل عملة واحدة ويصرف استدعاءً عليها. بعد إضافة مرشّح جديد قارن meta.count بما تتوقعه.

جرّب بنفسك

  1. أرسل طلباً بلا مفتاح

    curl -i "https://api.genesisarbitrage.com/v1/account/usage" يعيد 401 مع invalid_key و"Missing X-API-Key header." في الجسم. ابحث عن x-request-id بين الترويسات.

  2. كرّره مع المفتاح

    عيّن المتغير بـ read -s وأرسل الطلب من قسم /account/usage. تحصل على 200 وخطتك في data.plan.

  3. تحقق من تاريخ التصفير

    شغّل سكربت Python وقارن تاريخ تصفير الحصة بسطر "resets …" في كتلة "Genesis API" في ملفك الشخصي. الحصول على المفتاح خطوة بخطوة مشروح في البداية السريعة مع Genesis API.

  4. ابحث عن أعلى معدل

    أضف الكتلة الثانية إلى السكربت وابحث عن المنصة صاحبة أعلى funding_8h_pct. وحّد funding_pct الخاص بها على 8 ساعات يدوياً: المعدل × 8 / الفترة بالساعات.

  5. اكسر الطلب عمداً

    غيّر 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.