Genesis Arbitrage

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

بوت أربيتراج العملات الرقمية بلغة Python: من API الفروق إلى تنبيهات Telegram

باختصار

  • بوت أربيتراج العملات الرقمية له أربع حلقات: بيانات الفروق، وفلتر للأزواج القابلة للتنفيذ، وتنبيه، وقرار بشري. الكود ينفّذ الثلاث الأولى، أما الصفقات فتجريها أنت على المنصات.
  • التنفيذ هو الجزء الصعب في الأربيتراج: نقل العملة والرسوم والانزلاق السعري والوقت. لذلك يُبقي البوت فقط على الأزواج المفتوح فيها السحب والإيداع، وفي خطتي Pro وMax يعيد حساب الفرق عبر 1,000$ من دفتر الأوامر.
  • يستعلم البوت من Genesis API بما لا يزيد عن meta.freshness_sec، وينتظر Retry-After عند 429 و503، وينبّه على الزوج الواحد مرة كل 15 دقيقة كحد أقصى. تكفي النسخة الأساسية خطة Trial بسعر 20$ شهريًا.

بوت أربيتراج العملات الرقمية برنامج يجلب وفق جدول زمني الفروق السعرية بين المنصات — أي الفجوة في سعر عملة واحدة بالنسبة المئوية — ويُبقي الأزواج التي يمكن تنفيذها فعلًا وينبّهك إليها. القرار وتنفيذ الصفقة يبقيان للإنسان. بوت كهذا لأربيتراج السبوت بين المنصات يحتاج نحو 140 سطرًا بلغة Python: الفروق تأتي من Genesis API، والرسائل تُرسل عبر Telegram Bot API.

مما يتكوّن بوت الأربيتراج

يُبنى كل بوت أربيتراج من أربع حلقات:

الحلقةما تفعلهفي هذا البوت
البياناتتجلب الأسعار والفروق بين المنصاتGenesis API، GET /arbitrage/spot-spot
الفلترتُبقي الأزواج القابلة للتنفيذحالة الإيداع والسحب، Δ دفتر الأوامر لمبلغ 1,000$
التنبيهتُبلغ عن الزوجطريقة sendMessage في Telegram Bot API
القرار والصفقةتفحص الزوج وتتداولإنسان على المنصات

جامع البيانات الخاص بك هو أبطأ حلقة في البناء: لكل منصة API خاص بها، وأسماء خاصة للرموز والشبكات، وحالات خاصة للإيداع والسحب، ويجب دمج كل ذلك في صيغة واحدة. يعيد Genesis API أزواجًا جاهزة عبر أكثر من 20 منصة CEX، منها Binance وOKX وBybit وBitget وMEXC وGate، مع الأسعار والفرق والشبكة والعقد وحالة الإيداع والسحب وأحجام التداول. حقول كل نقطة نهاية للأربيتراج في دليل نقاط نهاية الأربيتراج في Genesis API، واختيار مصدر البيانات في مقال API العملات الرقمية: الأنواع وكيف تختار.

لماذا تبقى الصفقات بيد الإنسان

إيجاد الفرق هو الجزء السهل في الأربيتراج. التنفيذ هو الجزء الصعب: أربع عقبات تقف بين سطر في استجابة API والمال في حسابك.

مثال افتراضي: يرسل البوت زوجًا بفرق 1.2%، أي 12$ على 1,000$. بعد المرور عبر دفاتر الأوامر لمبلغ 1,000$ يتبقى 0.8%، أي 8$. رسم المتداول (taker) 0.1% على الشراء وعلى البيع يكلّف نحو 2$، وسحب العملة يكلّف 3$.

الكود الذي يشتري العملة ويسحبها بنفسه يحوّل كل إخفاق من هذه إلى صفقة لم يراجعها أحد. لهذا يرسل هذا البوت إشارة: يفحص بنفسه السحب والإيداع والفرق بعد دفاتر الأوامر، ويتحقق الإنسان من العقد والرسوم ومسار التحويل قبل التداول. على أي حال لا يستطيع Genesis API التداول: فهو يقرأ البيانات فقط ولا يضع أوامر. الفحص اليدوي خطوة بخطوة للزوج في مقال الأربيتراج بين منصات العملات الرقمية.

ما الذي تحتاجه

python3 --version   # Python 3.10 or newer is required
python3 -m pip install requests

export GENESIS_API_KEY="gns_live_XXXXXXXXXXXXXXXX"
export TG_BOT_TOKEN="123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11"

# after /start in the bot chat, find "chat":{"id":...} in the reply
curl "https://api.telegram.org/bot$TG_BOT_TOKEN/getUpdates"

export TG_CHAT_ID="123456789"

تبقى المتغيرات المضبوطة بـ export حتى تغلق الطرفية. بحسب وثائق Telegram، يمنح الرمز تحكمًا كاملًا بالبوت، ويمنح المفتاح الوصول إلى خطتك، لذلك يعيش كلاهما في متغيرات البيئة فقط: لا يدخلان الكود ولا المستودع.

كود البوت خطوة بخطوة

الكتل السبع أدناه هي bot.py كاملًا: احفظها في ملف واحد بهذا الترتيب. العتبات في الإعدادات قيم مؤقتة؛ اضبطها وفق رسومك وحجم صفقتك.

1. الإعدادات

import os
import time

import requests

API = "https://api.genesisarbitrage.com/v1"
TG = "https://api.telegram.org/bot" + os.environ["TG_BOT_TOKEN"]
CHAT_ID = os.environ["TG_CHAT_ID"]

MIN_SPREAD = 1.0      # فرق الصف من 1%
MIN_VOLUME = 50_000   # حجم 24 ساعة في المنصتين من 50,000$
MIN_EXEC = 0.5        # الفرق بعد دفاتر الأوامر لمبلغ 1,000$ من 0.5%
TOP = 5               # أزواج في الدورة، كحد أقصى
REPEAT_SEC = 15 * 60  # الزوج الواحد مرة كل 15 دقيقة كحد أقصى
RECHECK_SEC = 5 * 60  # الزوج الذي التهمه الدفتر ينتظر 5 دقائق

api = requests.Session()
api.headers["X-API-Key"] = os.environ["GENESIS_API_KEY"]
cache = {}       # الطلب -> (ETag، الاستجابة)
wait_until = {}  # الزوج -> الوقت الذي يبقى حتى حلوله صامتًا

يسافر المفتاح في الترويسة X-API-Key مع كل طلب يمرّ عبر جلسة api ولا يدخل الرابط أبدًا. يُسقط MIN_VOLUME الأزواج التي يقل حجم 24 ساعة فيها عن 50,000$ في أي من المنصتين. يحفظ cache قيم ETag للاستجابات، ويحفظ wait_until الوقت الذي يبقى البوت حتى حلوله صامتًا بشأن الزوج.

2. استدعاء Genesis API: Retry-After وETag

def get(path, params=None):
    """GET إلى Genesis API مع إعادة المحاولة عبر Retry-After وETag."""
    key = (path, tuple(sorted((params or {}).items())))
    for _ in range(4):  # طلب واحد وحتى ثلاث إعادات
        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:  # اللقطة لم تتغير
            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"Quota exhausted: wait {wait} s")
            time.sleep(wait)
            continue
        r.raise_for_status()  # 400 و401 و403: إعادة المحاولة لن تفيد
        body = r.json()
        if "ETag" in r.headers:  # ETag تحمله مجموعات البيانات الكاملة فقط
            cache[key] = (r.headers["ETag"], body)
        return body
    raise RuntimeError("Genesis API is busy, retrying next pass")

يعود 429 عند تجاوز حد المعدل في الثانية أو حجم التنزيل، ويعود 503 أثناء إعادة بناء البيانات. كلاهما يحمل Retry-After، وتنتظر get عدد الثواني الذي يطلبه الخادم. تعيد الحصة المستنفدة أيضًا 429، لكن مع Retry-After يساوي وقت إعادة التعيين، وقد يبعد أيامًا، ولذلك يتوقف البوت. أما 400 و401 و403 فلن تزول بإعادة المحاولة، لذا ترفعها raise_for_status. كل الحدود في دليل حدود Genesis API.

3. الفروق وتصفية الأزواج

def candidates():
    """أزواج Spot – Spot التي يمكن فعلًا نقل عملتها."""
    body = get("/arbitrage/spot-spot",
               {"min_spread": MIN_SPREAD, "min_volume": MIN_VOLUME})
    # السحب مفتوح في منصة الشراء، والإيداع في منصة البيع
    rows = [x for x in body["data"]
            if x["withdraw_enabled_buy"] and x["deposit_enabled_sell"]]
    rows.sort(key=lambda x: x["spread_pct"], reverse=True)
    return rows, body["meta"]["freshness_sec"]

يرشّح min_spread وmin_volume الصفوف على الخادم. لا توجد معاملات لأعلام الإيداع والسحب، لذلك يفحصها الكود: يمكن نقل العملة إذا كان السحب مفتوحًا في منصة الشراء (withdraw_enabled_buy) والإيداع في منصة البيع (deposit_enabled_sell). الحقول التي يستخدمها البوت، في صف من وثائق Spot — Spot:

{
  "coin": "FUEL",
  "exchange_buy": "ByBit",
  "exchange_sell": "Gate",
  "spread_pct": 0.11,
  "network": "ETH",
  "contract": "0x675B68AA4d9c2d3BB3F0397048e62E6B7192079c",
  "withdraw_enabled_buy": true,
  "deposit_enabled_sell": true,
  "volume_24h_buy": 17652.64,
  "volume_24h_sell": 12512.51,
  "trade_url_buy": "https://www.bybit.com/trade/spot/FUEL/USDT",
  "trade_url_sell": "https://www.gate.io/trade/FUEL_USDT",
  …
}

هذا الصف لن يجتاز فلاتر البوت: فرق 0.11% وأحجام أقل من 50,000$. يضع البوت الشبكة والعقد في الرسالة لتطابقهما مع صفحتي السحب والإيداع في المنصتين.

4. فحص دفتر الأوامر بقيمة 1,000$

def exec_spread(row):
    """الفرق بعد دفاتر الأوامر لمبلغ 1,000$. Pro وMax فقط."""
    body = get("/orderbooks/spreads/spot-spot",
               {"coin": row["coin"], "volume": 1000})
    for x in body["data"]:
        od = x["order_delta"]
        if (x["exchange_buy"] == row["exchange_buy"]
                and x["exchange_sell"] == row["exchange_sell"]
                and od["status"] == "ok"):
            return od["spread_pct"]
    return None  # no_book أو exhausted أو اختفى الزوج

تعيد نقطة النهاية صفوف العملة من مجموعة بيانات Spot – Spot مع كائن order_delta — أي Δ دفتر الأوامر، الفرق بعد المرور عبر دفاتر الأوامر: الشراء عبر أوامر البيع (asks) في منصة الشراء، والبيع في أوامر الشراء (bids) في منصة البيع. تأخذ الدالة الصف ذا المنصتين نفسيهما وقيمة order_delta.spread_pct عندما تكون status هي ok؛ ويعني no_book أنه لا يوجد دفتر، وexhausted أن الدفتر نفد قبل بلوغ 1,000$. تتأخر الدفاتر عن المنصة بين 5 و20 ثانية؛ الحقول موصوفة في وثائق Δ دفتر الأوامر ودليل نقاط نهاية دفتر الأوامر.

هذه الخطوة موجودة في Pro وMax فقط؛ وفي Trial وStart تعيد نقطة النهاية 403 plan_restricted. يقرأ البوت خطتك عند البدء ويتخطى الفحص هناك: تذكر الرسالة أن دفتر الأوامر لم يُفحص، وتنظر أنت إلى العمق في منصة التداول بنفسك.

5. رسالة Telegram

def message(row, ex):
    buy, sell = row["exchange_buy"], row["exchange_sell"]
    if ex is None:
        book = "دفتر الأوامر لم يُفحص (Trial أو Start)"
    else:
        book = f"بعد دفاتر الأوامر لمبلغ 1,000$: {ex:.2f}%"
    return "\n".join([
        f'{row["coin"]}: {buy} → {sell}',
        f'الفرق {row["spread_pct"]}%، {book}',
        f'الشبكة {row["network"]}، العقد {row["contract"] or "—"}',
        f'شراء: {row["trade_url_buy"]}',
        f'بيع: {row["trade_url_sell"]}',
    ])


def send(text):
    """Telegram Bot API sendMessage؛ عند 429 ننتظر retry_after."""
    for _ in range(3):
        r = requests.post(TG + "/sendMessage", timeout=15, json={
            "chat_id": CHAT_ID, "text": text,
            "link_preview_options": {"is_disabled": True}})
        if r.status_code != 429:
            r.raise_for_status()  # 400 أو 401: محادثة أو رمز خاطئ
            return
        wait = r.json().get("parameters", {}).get("retry_after", 5)
        time.sleep(wait)  # حد الإغراق في Telegram
    raise RuntimeError("Telegram did not accept the message")

تأخذ sendMessage المعاملين chat_id وtext بطول من 1 إلى 4096 حرفًا، ويذهب الطلب إلى https://api.telegram.org/bot<token>/sendMessage (وثائق Telegram Bot API). يعطّل link_preview_options مع is_disabled معاينة الروابط. عند حد الإغراق يعيد Telegram الرمز 429 ويضع مدة الانتظار بالثواني في parameters.retry_after. وفي محادثة واحدة يطلب Telegram من البوتات ألا ترسل أكثر من رسالة في الثانية (الأسئلة الشائعة لمطوري البوتات).

تبدو الرسالة هكذا، كمثال افتراضي:

XYZ: MEXC → Gate
الفرق 1.4%، بعد دفاتر الأوامر لمبلغ 1,000$: 0.62%
الشبكة ETH، العقد 0x…
شراء: https://…
بيع: https://…

6. منع التكرار: زوج واحد كل 15 دقيقة

def scan(books):
    """دورة واحدة: الفروق، دفاتر الأوامر، الرسائل."""
    rows, pause = candidates()
    done = 0
    for row in rows:
        key = (row["coin"], row["exchange_buy"], row["exchange_sell"])
        if time.time() < wait_until.get(key, 0):
            continue  # نُبّه عليه سابقًا، أو التهم الدفتر الفرق
        if done == TOP:
            break
        done += 1
        ex = exec_spread(row) if books else None
        ok = not books or (ex is not None and ex >= MIN_EXEC)
        if ok:
            send(message(row, ex))
        # صمت 15 دقيقة بعد التنبيه، و5 إذا كان الدفتر ضعيفًا
        hold = REPEAT_SEC if ok else RECHECK_SEC
        wait_until[key] = time.time() + hold
        time.sleep(1)  # طلب ورسالة واحدة في الثانية كحد أقصى
    return pause

الزوج هو الثلاثية: العملة ومنصة الشراء ومنصة البيع. بعد التنبيه يصمت البوت عنه 15 دقيقة، حتى لو بقي الفرق. وإذا التهم الدفتر الفرق يعود البوت إلى الزوج بعد 5 دقائق، فلا يكلّف فحص دفتر الأوامر استدعاءً في كل دورة. تأخذ الدورة حتى خمسة أزواج بأوسع الفروق وتتوقف ثانية بعد كل زوج: وهذا يُبقي البوت ضمن نصيحة Telegram وضمن حد الثانية في أي خطة. القاموس يعيش في الذاكرة، لذلك قد تتكرر الأزواج الجديدة بعد إعادة التشغيل.

7. الحلقة: توقف لا يقل عن freshness_sec

def main():
    usage = get("/account/usage")["data"]  # لا يستهلك الحصة
    books = usage["plan"] in ("pro", "max")
    pause = usage["freshness_sec"]
    print("Plan", usage["plan"], "| polling every", pause, "s",
          "| order books:", "yes" if books else "no")
    while True:
        try:
            pause = scan(books)
        except requests.HTTPError as e:
            if e.response.status_code < 500:
                raise  # المفتاح أو الخطة أو الرمز: إعادة المحاولة لن تفيد
            print("Server error, retrying:", e)
        except (requests.RequestException, RuntimeError) as e:
            print("No response, retrying:", e)
        time.sleep(pause)  # لا أكثر من meta.freshness_sec


if __name__ == "__main__":
    main()

عند البدء يستدعي البوت /account/usage: لا يستهلك الطلب الحصة ويعيد خطتك وfreshness_sec. هذه حداثة البيانات، أي الفاصل الذي تحصل فيه خطتك على لقطة جديدة: 60 ثانية في Trial و30 في Start و10 في Pro و5 في Max. بعد ذلك تأتي مدة التوقف من meta.freshness_sec، لأن الاستعلام الأسرع يعيد اللقطة نفسها. أعطال الشبكة وأخطاء 5xx تنتظر الدورة التالية، أما بقية أخطاء 4xx — مفتاح خاطئ أو اشتراك منتهٍ أو خطة بلا نقطة النهاية أو رمز أو chat_id خاطئ — فتوقف البوت. رموز الأخطاء في استجابات Genesis API وأخطاؤه، ومراقب الفروق دون Telegram يُبنى في درس مراقب الفروق والتمويل بلغة Python.

كيف تشغّله وتتحقق منه

python3 bot.py
# Plan trial | polling every 60 s | order books: no
  1. انتظر الدورة الأولى

    تصل الرسائل عندما يكون في السوق أزواج فوق عتباتك. إن لم تصل أي رسالة خلال بضع دقائق، فخفّض MIN_SPREAD وMIN_VOLUME لبعض الوقت: يُظهر ذلك أن السلسلة من API إلى Telegram تعمل.

  2. قارن زوجًا بالجدول

    افتح Spot – Spot على الموقع: العملة نفسها وزوج المنصات نفسه في الجدول. قد تختلف الأرقام قليلًا، لأن API يقدّم اللقطة بتأخير خطتك.

  3. تحقق من منع التكرار

    يجب ألا يصل الزوج نفسه مجددًا خلال 15 دقيقة.

  4. راقب استهلاك الاستدعاءات

    انظر إلى الحقل calls_used في /account/usage أو سطر «الاستدعاءات المستخدمة» في ملفك الشخصي: في Trial بلا فحص دفاتر الأوامر يستهلك البوت نحو 1,440 استدعاءً يوميًا.

  5. اترك البوت يعمل

    يشغّل nohup python3 bot.py >> bot.log 2>&1 & البوت في الخلفية؛ اضبط متغيرات البيئة في جلسة الطرفية نفسها.

أي خطة من Genesis API يحتاجها البوت

الدورة هي استدعاء واحد لـ /arbitrage/spot-spot، إضافة إلى ما يصل إلى خمسة استدعاءات لـ /orderbooks/spreads/spot-spot في Pro وMax؛ ولا تستهلك الحصة إلا استجابات 200. الحد الأعلى لـ 30 يومًا: (1 + الفحوص في الدورة) × 86,400 / التوقف × 30.

الخطةالاستعلامفحص دفتر الأوامر بقيمة 1,000$الاستدعاءات في 30 يومًا
Trial، 20$/شهركل 60 ثلا43,200 من 500,000
Start، 50$/شهركل 30 ثلا86,400 من 2M
Pro، 100$/شهركل 10 ثنعمحتى 1,555,200 من 5M
Max، 200$/شهركل 5 ثنعمحتى 3,110,400 من 10M

في Trial يساوي ذلك 86,400 / 60 × 30 = 43,200 استدعاء، أي 8.64% من الحصة. وفي Pro، في أسوأ الحالات حيث تفحص كل دورة خمسة دفاتر، يبلغ 6 × 86,400 / 10 × 30 = 1,555,200 استدعاء، أي 31.1% من الحصة. قواعد الحصة في قسم الخطط والحدود من الوثائق.

مخاطر بوت الأربيتراج

دون كود: تنبيهات Genesis Arbitrage في Telegram

إن كنت لا تريد كتابة بوتك الخاص وتشغيله، فإن تنبيهات Telegram في Genesis Arbitrage ترسل لك الأزواج. تنشئ بوتًا في @BotFather وتلصق رمزه في الموقع وتختار فئات مثل Spot - Spot وDEX - Futures وCrosschain وأربيتراج التمويل. تحدد الفلاتر أدنى فرق والمنصات والشبكات وحالة الإيداع/السحب وفرق الأوامر، ويحد «وقت التكرار (دقائق)» من عودة الزوج الواحد. يعمل البوت الشخصي في خطة Pro على الموقع، بمعزل عن خطط Genesis API؛ الإعداد في دليل إشعارات Telegram.

أسئلة وأجوبة

هل يستطيع البوت التداول وحده؟

ليس عبر Genesis API: فالـ API يقدّم البيانات فقط ولا يضع أوامر. يُضاف التداول عبر API المنصات نفسها بمفاتيح التداول، وهذا كود منفصل وعلى مسؤوليتك: فالفرق القديم أو السحب المغلق يتحول إلى صفقة لم يراجعها أحد.

كم يكلّف بوت كهذا؟

الكود مجاني، وكذلك رسائل البوت إلى مستخدمي Telegram. أنت تدفع مقابل البيانات: يبدأ Genesis API من 20$ شهريًا في Trial، ويبدأ فحص دفتر الأوامر من Pro بسعر 100$. وتحتاج أيضًا حاسوبًا أو خادمًا يعمل على مدار الساعة.

أي خطة من Genesis API أحتاج؟

تكفي Trial للبوت الأساسي: /arbitrage/spot-spot متاح في كل خطة، مع لقطة جديدة كل 60 ثانية. تحدّث Start البيانات كل 30 ثانية. أما فحص Δ دفتر الأوامر بقيمة 1,000$ فيعمل في Pro وMax فقط.

لماذا أرسل البوت زوجًا لم يبق فيه فرق على المنصة؟

تصل البيانات بتأخير خطتك، ويُغلق المتداولون الآخرون الفجوة أيضًا. كما يُحسب فرق الصف من آخر الصفقات، بينما لا يمكنك الشراء إلا عند سعر ask ولا البيع إلا عند سعر bid. تحقق من الأسعار ودفتر الأوامر في منصة التداول قبل الصفقة.

هل يمكنني نشر البوت على GitHub؟

نعم: تسمح الشروط ببناء بوتاتك الخاصة على Genesis API، والقيد الوحيد هو إعادة بيع البيانات الخام كما هي. أبقِ المفتاح والرمز خارج المستودع. إذا وصل المفتاح إلى كود عام فاضغط «إعادة الإصدار» في ملفك الشخصي، وأمر /token في @BotFather يستبدل رمز البوت.