Genesis Arbitrage

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

مراقب الفروق والتمويل بلغة Python

باختصار

  • المراقب برنامج طرفية: كل meta.freshness_sec ثانية يسحب مجموعتي /arbitrage/spot-spot و/funding/spread كاملتين، ويرشّح الصفوف بالعتبات، ويطبع الجداول ويضيفها إلى ملف CSV.
  • تُطلب المجموعتان بلا مرشحات، فتأتيان مع ETag: الإعادة بـ If-None-Match قبل اللقطة التالية تعيد 304 دون استهلاك الحصة. عند 429 و503 ينتظر العميل Retry-After ثانية.
  • ما يتبقى بعد رسوم taker المفترضة 0.1% لكل ساق هو الفرق ناقص 0.2 نقطة مئوية. على Pro وMax يعيد المراقب فحص أفضل ثلاثة أزواج بدفتر أوامر بقيمة 1,000 دولار.
  • الحد الأعلى 86,400 استدعاء لكل 30 يوماً على Trial، أي 17.28% من الحصة، و1,296,000 على Pro مع فحص الدفاتر، أي 25.92%.

مراقب الفروق والتمويل برنامج يسحب في حلقة الفروق بين المنصات وفروق التمويل، ويُبقي الصفوف فوق عتباتك ويطبعها جدولاً في الطرفية. المراقب في هذا الدرس نحو 170 سطراً بلغة Python: بياناته من Genesis API، وسجله في ملف CSV، ولا يفتح صفقات. ولا يرسل تنبيهات أيضاً؛ البوت الذي يرسل رسائل Telegram مشروح في بوت أربيتراج العملات الرقمية بلغة Python.

خطة الاستطلاع: نقاط النهاية والتواتر واستهلاك الاستدعاءات

الطلبماذا يعطيمتى
/account/usageالخطة وfreshness_sec وrps_limitعند البدء، لا يستهلك الحصة
/arbitrage/spot-spotأزواج Spot – Spotفي كل دورة، المجموعة كاملة
/funding/spreadأفضل أزواج المنصات بالتمويلفي كل دورة، المجموعة كاملة
/orderbooks/spreads/spot-spotOrder-book Δ لـ 1,000 دولارPro وMax، ثلاثة أزواج في الدورة

يحدد meta.freshness_sec التواتر: تحصل خطتك على لقطة جديدة كل 60 ثانية على Trial، و30 على Start، و10 على Pro، و5 على Max. الاستطلاع الأسرع يعيد اللقطة نفسها بالـ meta.updated_at نفسه. حقول المجموعتين في وثائق Spot — Spot وفرق التمويل.

الخطة والحصةالفاصلالطلبات في الدورةالاستدعاءات لكل 30 يوماً
Trial، 500K60 ث286,400
Start، 2M30 ث2172,800
Pro، 5M10 ث51,296,000
Max، 10M5 ث52,592,000

على Trial: 2 × 86,400 / 60 × 30 = 86,400 استدعاء، أي 17.28% من الحصة. على Pro تنضم ثلاثة فحوص دفاتر إلى المجموعتين: 5 × 86,400 / 10 × 30 = 1,296,000 استدعاء، أي 25.92% من 5M. قواعد الحصة في دليل حدود Genesis API.

يلتزم المراقب بحد الطلبات في الثانية بفاصل 1.1 / rps_limit ثانية بين الطلبات: 1.1 ثانية على Trial و0.22 على Pro. دورة من خمسة طلبات على Pro تستغرق نحو ثانية.

الإعدادات وعميل بـ ETag وRetry-After

تشكّل كتل الكود السبع في هذا الدرس ملف monitor.py كاملاً: احفظها واحدة بعد أخرى في ملف واحد. العتبات في الإعدادات توضيحية؛ اضبطها بحسب رسومك وأحجامك.

import csv
import os
import time
from datetime import datetime, timezone

import requests

API = "https://api.genesisarbitrage.com/v1"
MIN_SPREAD = 1.0     # الفرق في الصف من 1%
MIN_VOLUME = 50_000  # حجم 24 ساعة على المنصتين من 50,000 دولار
MIN_FUNDING = 0.05   # فرق التمويل من 0.05%
FEE = 0.1            # رسوم taker المفترضة لكل ساق، %
TOP = 10             # عدد الصفوف في كل جدول
BOOK_TOP = 3         # أزواج تُفحص بالدفاتر في كل دورة، Pro/Max
BOOK_USD = 1000      # حجم فحص دفتر الأوامر، دولار
CSV_FILE = "monitor.csv"

api = requests.Session()
api.headers["X-API-Key"] = os.environ["GENESIS_API_KEY"]
cache = {}                # الطلب -> (ETag، جسم الاستجابة)
stats = {200: 0, 304: 0}  # عدد استجابات 200 و304 التي وصلت
pace = {"gap": 1.1, "last": 0.0}  # الفاصل بين الطلبات، ث

المفتاح يأتي من متغير البيئة GENESIS_API_KEY ويُرسل في ترويسة X-API-Key مع كل طلب، ولا يوضع في الرابط أبداً. يحفظ cache الـ ETag وجسم آخر استجابة لكل طلب، ويعدّ stats استجابات 200 و304، ويتذكر pace وقت إرسال آخر طلب.

def get(path, params=None):
    """GET إلى Genesis API: ضبط الوتيرة وETag وإعادة المحاولة بحسب Retry-After."""
    key = (path, tuple(sorted((params or {}).items())))
    for _ in range(4):  # طلب واحد وحتى ثلاث إعادات
        wait = pace["last"] + pace["gap"] - time.monotonic()
        if wait > 0:
            time.sleep(wait)  # لا يزيد على rps_limit طلب في الثانية
        pace["last"] = time.monotonic()
        hdr = {"If-None-Match": cache[key][0]} if key in cache else {}
        r = api.get(API + path, params=params, headers=hdr,
                    timeout=15)
        if r.status_code == 304:  # اللقطة لم تتغير
            stats[304] += 1
            return cache[key][1]
        if r.status_code in (429, 503):
            wait = int(r.headers.get("Retry-After", "5"))
            if wait > 60:  # هكذا تبدو الحصة المستنفدة
                raise SystemExit(f"الحصة مستنفدة: انتظر {wait} ث")
            time.sleep(wait)
            continue
        r.raise_for_status()  # 400 و401 و403: الإعادة لن تفيد
        stats[200] += 1
        body = r.json()
        if "ETag" in r.headers:  # فقط مجموعات البيانات الكاملة تحمله
            cache[key] = (r.headers["ETag"], body)
        return body
    raise RuntimeError("API مشغول، سنعيد المحاولة في الدورة التالية")

ETag هو وسم إصدار للّقطة. ترسله get في ترويسة If-None-Match، وما دامت اللقطة لم تتغير يردّ الخادم بـ 304 بلا جسم: لا تُستهلك الحصة، وتعيد الدالة الجسم السابق. عند 429 و503 تنتظر Retry-After ثانية ثم تعيد المحاولة، والانتظار الأطول من دقيقة يعني أن حصة الفترة نفدت، فيتوقف المراقب. رموز الأخطاء وقواعد الإعادة في دليل استجابات Genesis API وأخطاؤه.

الفروق والتمويل: التحميل والعتبات والفرز

def spot_rows():
    """أزواج Spot – Spot فوق العتبات، ويمكن تحويل العملة."""
    body = get("/arbitrage/spot-spot")  # بلا مرشحات: لها ETag
    rows = []
    for x in body["data"]:
        vol = min(x["volume_24h_buy"] or 0, x["volume_24h_sell"] or 0)
        if (x["spread_pct"] >= MIN_SPREAD and vol >= MIN_VOLUME
                and x["withdraw_enabled_buy"]
                and x["deposit_enabled_sell"]):
            rows.append({**x, "net": net(x["spread_pct"])})
    rows.sort(key=lambda x: x["spread_pct"], reverse=True)
    return rows[:TOP], body["meta"]


def funding_rows():
    """العملات ذات أوسع فرق تمويل."""
    body = get("/funding/spread")  # بلا مرشحات: لها ETag
    rows = [x for x in body["data"] if x["spread_pct"] >= MIN_FUNDING]
    rows.sort(key=lambda x: x["spread_pct"], reverse=True)
    return rows[:TOP], body["meta"]

تُطلب مجموعتا البيانات بلا معاملات: الاستجابة لطلب فيه min_spread أو coin أو مرشح آخر تُبنى لذلك الطلب وتأتي بلا ETag. يطبّق المراقب العتبات بنفسه: فرق لا يقل عن MIN_SPREAD، وحجم 24 ساعة لا يقل عن MIN_VOLUME على المنصتين، والسحب مفتوح على منصة الشراء والإيداع مفتوح على منصة البيع. الحجم null يُحتسب صفراً، فلا يمرّ هذا الصف.

تُفرز الصفوف حسب spread_pct تنازلياً، وأول TOP منها تدخل الجدول. في /funding/spread تُقارن عتبة MIN_FUNDING مع spread_pct لأفضل زوج.

ما يتبقى بعد الرسوم وفحص دفتر الأوامر

def net(spread_pct):
    """ما يتبقى بعد رسمي taker، تقريباً، %"""
    return round(spread_pct - 2 * FEE, 4)


def book_net(row):
    """ما يتبقى بعد BOOK_USD من الدفتر والرسوم. Pro وMax."""
    body = get("/orderbooks/spreads/spot-spot",
               {"coin": row["coin"], "volume": BOOK_USD})
    pair = (row["exchange_buy"], row["exchange_sell"])
    for x in body["data"]:
        if (x["exchange_buy"], x["exchange_sell"]) != pair:
            continue
        od = x["order_delta"]
        if od["status"] != "ok":
            return od["status"]  # no_book أو exhausted
        return net(od["spread_pct"])
    return "gone"  # الزوج خرج من مجموعة البيانات

رسوم taker المفترضة 0.1% على الشراء و0.1% على البيع تخفض الفرق بنحو 0.2 نقطة مئوية: زوج بفرق 1.62% يترك 1.62 − 2 × 0.1 = 1.42%. ضع رسوم منصاتك في FEE (maker وtaker). رسوم السحب غير موجودة في استجابات API، والمراقب لا يحتسبها.

على Pro وMax تعيد book_net فحص أفضل ثلاثة أزواج بدفاتر الأوامر: الطلب /orderbooks/spreads/spot-spot مع عملة الزوج وvolume=1000 يعيد صفوف تلك العملة مع كائن order_delta، وتأخذ الدالة الصف الذي له زوج المنصات نفسه (Order-book Δ). إن لم يوجد دفتر أو نفد، تحصل بدل الرقم على الحالة no_book أو exhausted. الطلب مع coin بلا ETag ويكلّف استدعاءً دائماً، ولهذا تجري الدورة ثلاثة طلبات فقط، يحددها BOOK_TOP.

جدول الطرفية

def show(spot, s_meta, fund, f_meta):
    now = time.time()
    s_age = now - s_meta["updated_at"]
    f_age = now - f_meta["updated_at"]
    print(f"\nSpot – Spot، عمر اللقطة {s_age:.0f} ث")
    print(f"{'العملة':<8}{'شراء → بيع':<20}"
          f"{'الفرق':>7}{'-الرسوم':>9}{'الدفتر':>11}")
    for x in spot:
        pair = f'{x["exchange_buy"]} → {x["exchange_sell"]}'
        book = x.get("book", "—")
        if isinstance(book, float):
            book = f"{book:.2f}"
        print(f'{x["coin"]:<8}{pair:<20}{x["spread_pct"]:>7.2f}'
              f'{x["net"]:>9.2f}{book:>11}')
    print(f"\nالتمويل، عمر اللقطة {f_age:.0f} ث")
    for x in fund:
        b = x["best"]
        legs = (f'{b["exchange_1"]} {b["interval_1"] or "?"} / '
                f'{b["exchange_2"]} {b["interval_2"] or "?"}')
        print(f'{x["coin"]:<8}{legs:<27}{x["spread_pct"]:>8.4f} %')
    print(f"استجابات 200: {stats[200]}، و304: {stats[304]}")

يعرض الجدول الأول العملة وزوج المنصات وspread_pct وما يتبقى بعد الرسوم وما يتبقى بعد الدفتر؛ والشرطة تعني أن الدفتر لم يُفحص. يعرض الثاني أفضل زوج منصات بالتمويل مع فواصل التمويل وspread_pct. فوق الجدولين عمر اللقطة، أي الوقت الحالي ناقص meta.updated_at، وتحتهما عدد استجابات 200 و304 منذ البدء.

سجل CSV

def save(spot, fund):
    """يضيف الدورة إلى CSV: الوقت ومجموعة البيانات والزوج والفروق."""
    new = not os.path.exists(CSV_FILE)
    ts = datetime.now(timezone.utc).strftime("%Y-%m-%d %H:%M:%S")
    with open(CSV_FILE, "a", newline="", encoding="utf-8") as f:
        w = csv.writer(f)
        if new:
            w.writerow(["time_utc", "dataset", "coin", "leg_1",
                        "leg_2", "spread_pct", "net_pct", "book"])
        for x in spot:
            w.writerow([ts, "spot-spot", x["coin"], x["exchange_buy"],
                        x["exchange_sell"], x["spread_pct"], x["net"],
                        x.get("book")])  # None تصبح خلية فارغة
        for x in fund:
            b = x["best"]
            w.writerow([ts, "funding", x["coin"], b["exchange_1"],
                        b["exchange_2"], x["spread_pct"], None, None])

جدول الطرفية يبقى حتى الدورة التالية، أما monitor.csv فيحفظ كل دورة: ترى منه كم يدوم الزوج وفي أي ساعات يظهر. وحدة csv جزء من المكتبة القياسية في Python. افتح الملف بـ newline="" كما تشترط وثائق الوحدة، وإلا ظهر \r زائد في الملف على الأنظمة التي تستخدم نهايات الأسطر \r\n.

عمود book يحمل ما يتبقى بعد الدفتر بالنسبة المئوية أو الحالة exhausted أو no_book. تكتب الوحدة None خلية فارغة، فيبقى العمود فارغاً لصفوف التمويل والأزواج التي لم تُفحص. الأوقات بتوقيت UTC.

الحلقة الرئيسية

def main():
    usage = get("/account/usage")["data"]  # لا يستهلك الحصة
    books = usage["plan"] in ("pro", "max")
    pace["gap"] = 1.1 / usage["rps_limit"]
    print("الخطة", usage["plan"], "| لقطة كل",
          usage["freshness_sec"], "ث | دفاتر الأوامر:",
          "نعم" if books else "لا")
    pause = usage["freshness_sec"]
    while True:
        try:
            spot, s_meta = spot_rows()
            fund, f_meta = funding_rows()
            if books:
                for x in spot[:BOOK_TOP]:
                    x["book"] = book_net(x)
            show(spot, s_meta, fund, f_meta)
            save(spot, fund)
            pause = s_meta.get("freshness_sec", pause)
        except requests.HTTPError as e:
            if e.response.status_code < 500:
                raise  # المفتاح أو الخطة أو المعاملات: الإعادة لن تفيد
            print("خطأ في الخادم، سنعيد المحاولة:", e)
        except (requests.RequestException, RuntimeError) as e:
            print("لا استجابة، سنعيد المحاولة:", e)
        time.sleep(pause)  # أسرع من freshness_sec = اللقطة نفسها


if __name__ == "__main__":
    try:
        main()
    except KeyboardInterrupt:
        print("\nتوقف المراقب، السجل في", CSV_FILE)

عند البدء يستدعي المراقب /account/usage: الطلب لا يستهلك الحصة ويعيد الخطة وfreshness_sec وrps_limit (الاستخدام). تحدد الخطة هل تُفحص دفاتر الأوامر، ويحدد rps_limit الفاصل بين الطلبات. يتحمل المراقب أعطال الشبكة وأخطاء 5xx حتى الدورة التالية، بينما توقفه أخطاء 4xx (مفتاح خاطئ أو اشتراك منتهٍ أو خطة بلا نقطة النهاية).

كيف تشغّله وتقرأ المخرجات

python3 --version   # مطلوب Python 3.10 أو أحدث
python3 -m pip install requests
export GENESIS_API_KEY="gns_live_XXXXXXXXXXXXXXXX"
python3 monitor.py

مخرجات الخطة Pro، مثال توضيحي:

الخطة pro | لقطة كل 10 ث | دفاتر الأوامر: نعم

Spot – Spot، عمر اللقطة 4 ث
العملة  شراء → بيع           الفرق    -الرسوم     الدفتر
KLM     ByBit → Gate           1.62     1.42       0.86
XYZ     MEXC → Gate            1.24     1.04  exhausted
ABC     BingX → HTX            1.12     0.92       0.31
QRS     Gate → OKX             1.05     0.85          —

التمويل، عمر اللقطة 4 ث
XYZ     MEXC 4h / Bitget 8h          0.0600 %
ABC     Hyper 1h / CoinEx 8h         0.0500 %
استجابات 200: 6، و304: 0

KLM: فرق الصف 1.62%، وبعد الرسمين 1.42%، وبعد 1,000 دولار من دفتر الأوامر مع الرسوم 0.86%. نفد دفتر XYZ عند 1,000 دولار: مع زوج كهذا تقلّل الحجم أو تتجاوزه. QRS هو الصف الرابع، فلم يُطلب دفتره. يبيّن جدول التمويل كم مرة تسوّي كل منصة: Hyper (اسم Hyperliquid في الاستجابات) كل ساعة وCoinEx كل 8 ساعات. اضغط Ctrl+C لإيقاف المراقب.

من فحوص الأزواج الأربعة في الدرس 3 ينفّذ المراقب فجوة السعر والتحويل بنفسه، ودفتر الأوامر على Pro وMax، ويعرض الحداثة فوق الجدول. أما العقد ورسم السحب فتتحقق منهما أنت.

تدرّب

  1. شغّل المراقب

    يعرض أول سطر في المخرجات الخطة وخطوة اللقطة وهل تُفحص الدفاتر؛ قارنها بملفك الشخصي.

  2. حرّك العتبة

    اضبط MIN_SPREAD = 0.5 وانظر كم من الصفوف الجديدة يبقى فيها عمود «الرسوم» فوق الصفر.

  3. أضف مجموعة بيانات

    انسخ spot_rows لـ /arbitrage/futures-futures: صيغة الصفوف نفسها. احذف فحص الإيداع والسحب للعقود، فلا عملة تنتقل بين المنصات هناك.

  4. افحص الاستخدام

    بعد ساعة استدعِ /account/usage وقارن calls_used بالتقدير: على Trial هذا حتى 2 × 60 = 120 استدعاءً في الساعة.

  5. ابحث عن الأزواج الدائمة

    افتح monitor.csv في جدول بيانات وعُدّ كم دورة متتالية دام كل زوج منصات.

مخاطر الأتمتة، من البيانات القديمة والأخطاء إلى المفاتيح ووكلاء AI، في الدرس 5، والاستطلاع الاقتصادي بالمرشحات والضغط وETag في مقال استطلاع API دون بلوغ الحدود.

أسئلة وأجوبة

بماذا يختلف المراقب عن بوت المراجحة؟

المراقب يطبع جدولاً ويحفظ السجل؛ أما البوت فيرسل تنبيهات عن الأزواج الجديدة ويصمت عن المكررة. يشتركان في كود الطلب والتصفية، وبوت Telegram مشروح في «بوت أربيتراج العملات الرقمية بلغة Python».

هل يمكنني الاستطلاع أسرع من freshness_sec؟

لن تحصل على بيانات جديدة: خطتك تتلقى لقطة كل freshness_sec ثانية. الطلب بلا مرشحات قبل اللقطة التالية يعيد 304 مجاناً، بينما الطلب المرشَّح يستهلك استدعاءً لنفس البيانات.

لماذا يعرض عمود «الدفتر» شرطة؟

Order-book Δ متاح على Pro وMax فقط، ويطلبه المراقب لأفضل ثلاثة أزواج (BOOK_TOP). على Trial وStart تعيد نقطة النهاية 403 plan_restricted، فلا يستدعيها المراقب.