Genesis Arbitrage

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

مانیتور اسپرد و فاندینگ با Python

به طور خلاصه

  • مانیتور برنامه‌ای کنسولی است: هر meta.freshness_sec ثانیه دیتاست‌های کامل /arbitrage/spot-spot و /funding/spread را می‌گیرد، ردیف‌ها را با آستانه‌ها فیلتر می‌کند، جدول چاپ می‌کند و به فایل CSV اضافه می‌کند.
  • هر دو دیتاست بدون فیلتر درخواست می‌شوند، پس ETag دارند: تکرار با If-None-Match پیش از اسنپ‌شات بعدی 304 می‌دهد و سهمیه مصرف نمی‌شود. روی 429 و 503 کلاینت Retry-After ثانیه صبر می‌کند.
  • آنچه پس از کارمزد تیکر فرضی 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 آمده است.

برنامهٔ پولینگ: endpointها، بسامد و مصرف فراخوانی

درخواستچه می‌دهدکِی
/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            # کارمزد تیکر فرضی برای هر پا، %
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):
    """آنچه پس از دو کارمزد تیکر می‌ماند، تقریباً، %"""
    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"  # جفت از دیتاست خارج شده

کارمزد تیکر فرضی 0.1% برای خرید و 0.1% برای فروش اسپرد را حدود 0.2 واحد درصد کم می‌کند: جفتی با 1.62% می‌شود 1.62 − 2 × 0.1 = 1.42%. کارمزد صرافی‌های خودتان را در FEE بگذارید (میکر و تیکر). کارمزد برداشت در پاسخ‌های 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\n دارند، یک \r اضافه در فایل می‌ماند.

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

چطور اجرا کنیم و خروجی را بخوانیم

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 این endpoint پاسخ 403 plan_restricted می‌دهد، پس مانیتور آن را صدا نمی‌زند.