Genesis Arbitrage

Genesis Arbitrage · · 17 دقیقه مطالعه

ربات آربیتراژ ارز دیجیتال با Python: از API اسپرد تا هشدار تلگرام

به طور خلاصه

  • ربات آربیتراژ ارز دیجیتال چهار حلقه دارد: داده اسپرد، فیلتر جفت‌های قابل اجرا، هشدار و تصمیم انسان. کد سه حلقه اول را انجام می‌دهد و معامله را خودتان در صرافی‌ها انجام می‌دهید.
  • سخت‌ترین بخش آربیتراژ اجراست: انتقال کوین، کارمزدها، لغزش قیمت و زمان. به همین دلیل ربات فقط جفت‌هایی را نگه می‌دارد که برداشت و واریز در آن‌ها باز است و در Pro و Max اسپرد را از میان 1,000 دلار دفتر سفارش دوباره حساب می‌کند.
  • ربات بیشتر از meta.freshness_sec از Genesis API پرسش نمی‌کند، در 429 و 503 منتظر Retry-After می‌ماند و درباره هر جفت حداکثر هر 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، همراه با قیمت‌ها، اسپرد، شبکه، قرارداد، وضعیت واریز و برداشت و حجم‌ها. فیلدهای هر endpoint آربیتراژ در راهنمای endpointهای آربیتراژ Genesis API آمده و انتخاب منبع داده در API ارز دیجیتال: انواع و نحوه انتخاب بررسی شده است.

چرا معامله‌ها با انسان می‌ماند

پیدا کردن اسپرد بخش آسان آربیتراژ است. اجرا بخش سخت است: چهار مانع میان یک ردیف در پاسخ API و پول در حساب شما قرار دارد.

مثال فرضی: ربات جفتی با اسپرد 1.2% می‌فرستد که روی 1,000 دلار برابر 12 دلار است. پس از عبور از دفترهای سفارش برای 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 می‌گذرد حرکت می‌کند و هرگز وارد URL نمی‌شود. 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 وقتی برمی‌گردد که از rate limit در ثانیه یا از حجم دانلود فراتر بروید و 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 یا جفت دیگر نیست

این endpoint ردیف‌های کوین را از مجموعه‌داده Spot – Spot همراه با شیء order_delta برمی‌گرداند — Δ دفتر سفارش، یعنی اسپرد پس از عبور از دفترهای سفارش: خرید از میان askهای صرافی خرید و فروش به bidهای صرافی فروش. تابع ردیفی با همان صرافی‌ها را برمی‌دارد و order_delta.spread_pct آن را وقتی status برابر ok است برمی‌گرداند؛ no_book یعنی دفتر وجود ندارد و exhausted یعنی دفتر پیش از 1,000 دلار تمام شد. دفترها 5 تا 20 ثانیه از صرافی عقب‌اند؛ فیلدها در مستندات Δ دفتر سفارش و راهنمای endpointهای دفتر سفارش توضیح داده شده‌اند.

این مرحله فقط در Pro و Max وجود دارد؛ در Trial و Start این endpoint پاسخ 403 plan_restricted می‌دهد. ربات هنگام شروع پلن شما را می‌خواند و بررسی را آنجا رد می‌کند: در پیام نوشته می‌شود که دفتر سفارش بررسی نشده و عمق را خودتان در ترمینال صرافی می‌بینید.

5. پیام تلگرام

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)  # flood control در 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 پیش‌نمایش پیوندها را خاموش می‌کند. در flood control، 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 — کلید نادرست، اشتراک منقضی، پلن بدون آن endpoint، توکن یا 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

اگر نمی‌خواهید ربات خودتان را بنویسید و اجرا کنید، هشدارهای تلگرام Genesis Arbitrage جفت‌ها را برایتان می‌فرستند. در @BotFather ربات می‌سازید، توکنش را در سایت می‌گذارید و دسته‌هایی مثل Spot - Spot، DEX - Futures، Crosschain و آربیتراژ فاندینگ را انتخاب می‌کنید. فیلترها حداقل اسپرد، صرافی‌ها و شبکه‌ها، وضعیت واریز/برداشت و اسپرد سفارش را تعیین می‌کنند و «زمان تا تکرار (دقیقه)» تعیین می‌کند هر جفت هر چند وقت برگردد. ربات شخصی روی پلن Pro سایت اجرا می‌شود، جدا از پلن‌های Genesis API؛ راه‌اندازی در راهنمای اعلان‌های تلگرام آمده است.

پرسش و پاسخ

آیا ربات می‌تواند خودش معامله کند؟

از طریق 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 توکن ربات را عوض می‌کند.