Genesis Arbitrage

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

ریسک‌های خودکارسازی: داده، خطاها، کلیدها و هوش مصنوعی

به طور خلاصه

  • داده را پیش از هر هشدار بررسی کنید: سن اسنپ‌شات (زمان فعلی منهای meta.updated_at)، پرچم stale در دفتر سفارش، اسپرد در بهترین قیمت‌ها و قرارداد مشترک در هر دو صرافی جفت.
  • 503 یعنی داده نیست، اما data خالی با 200 یعنی چیزی با فیلتر نخواند. ربات این دو را از هم تشخیص می‌دهد و پس از سه چرخه بدون داده خرابی را گزارش می‌کند.
  • کد در حالت‌های مرزی می‌شکند: تلاش مجدد بدون مکث به 429 می‌خورد، null در مقایسه Python را از کار می‌اندازد، تقسیم بر صفر در JavaScript Infinity و هشدار کاذب می‌دهد و زمان محلی به‌جای UTC پرداخت فاندینگ را ساعت‌ها جابه‌جا می‌کند.
  • کلید Genesis API فقط‌خواندنی است، پس نشت آن سهمیه شما را می‌سوزاند. کلید صرافی با حق برداشت به پول شما آسیب می‌زند و ربات معاملاتی به این حق نیاز ندارد.
  • مدل هوش مصنوعی اعداد را قاطی می‌کند و ممکن است دستوری پنهان در متن دیگران را اجرا کند: کد اعداد را در پیام می‌گذارد، فیلدهای بیرونی به‌عنوان داده به مدل می‌رسند، کد سقف معامله را اعمال می‌کند و انسان هر سفارش را تأیید می‌کند.

ریسک‌های ربات معاملاتی روی API ارز دیجیتال چهار گروه‌اند: داده کهنه است یا اسپردی را نشان می‌دهد که وجود ندارد؛ کد در حالت مرزی در حلقه می‌افتد یا می‌شکند؛ کلید نشت می‌کند؛ مدل هوش مصنوعی عددی را اشتباه می‌گیرد یا فرمان دیگری را اجرا می‌کند. برای هر ریسک یک بررسی در کد یا یک قاعده کاری هست و همه در مانیتور درس 4 هم جا می‌شوند.

ریسک‌های داده

اسنپ‌شات کهنه

اسنپ‌شات Genesis API در meta.updated_at ساخته می‌شود و پلن شما آن را هر meta.freshness_sec ثانیه تازه می‌کند: 60 در Trial، 30 در Start، 10 در Pro و 5 در Max. سن اسنپ‌شات یعنی زمان فعلی منهای meta.updated_at، یعنی همان تازگی داده. یک یا دو بازهٔ پلن عادی است؛ بیش از سه بازه یعنی اسنپ‌شات گیر کرده است.

مثال فرضی: در Pro آستانه 3 × 10 = 30 ثانیه است. پاسخی در 1783802470 می‌رسد و meta.updated_at = 1783802410 است: سن 1783802470 − 1783802410 = 60 ثانیه است و ربات از آن هیچ هشداری نمی‌فرستد. تأخیر کامل از صرافی تا کد شما حتی بیشتر است و سن با ساعت سرور شما سنجیده می‌شود، پس آن را با NTP همگام نگه دارید.

دفتر سفارش و پلتفرم‌های پیش‌بینی

دفتر سفارش ساعت خودش را دارد: /orderbooks/book مقادیر book_ts و age_sec و پرچم stale را برمی‌گرداند که وقتی دفتر از 30 ثانیه قدیمی‌تر باشد true است. دفترها 5 تا 20 ثانیه از صرافی عقب‌ترند. در Order-book Δ مقدار order_delta.status را ببینید: ok یعنی محاسبه شده، no_book یعنی دفتر نیست و exhausted یعنی دفتر نتوانسته حجم را پر کند.

برای بازارهای پیش‌بینی /predictions/platforms هست: جفت‌هایی را که پلتفرمی با mode = down، پلتفرمی با quotes_at قدیمی یا بوکمیکری با ok = false دارند کنار بگذارید.

پاسخ خالی هنگام 503

فهرست خالی و نبودن داده دو وضعیت متفاوت‌اند. 200 با meta.count = 0 یعنی هیچ ردیفی با فیلتر نخواند. 503 snapshot_not_ready یعنی داده در حال بازسازی است: ممکن است بازار جفت داشته باشد و شما پس از Retry-After ثانیه دوباره تلاش می‌کنید.

تابع fetch مقدار (data, meta) را برمی‌گرداند، یا None وقتی داده نیست. 429 و 503 را پس از Retry-After دوباره امتحان می‌کند، خطاهای دیگر 5xx و قطعی شبکه را پس از مکث‌های 5 و 10 و 20 ثانیه، و روی بقیه می‌ایستد.

import os
import time

import requests

BASE = "https://api.genesisarbitrage.com/v1"
HEADERS = {"X-API-Key": os.environ["GENESIS_API_KEY"]}


def fetch(path, params=None, tries=4):
    """(data, meta)، یا None: یعنی داده نیست، نه اینکه «جفتی نیست»."""
    for attempt in range(tries):
        try:
            r = requests.get(BASE + path, headers=HEADERS,
                             params=params, timeout=15)
            code = r.status_code
        except requests.RequestException:
            code = 0  # خطای شبکه یا تایم‌اوت: بعد از مکث دوباره تلاش کنید
        if code == 200:
            body = r.json()
            return body["data"], body["meta"]
        wait = 5 * 2 ** attempt  # 5، 10، 20 ثانیه: مکث بیشتر می‌شود
        if code in (429, 503):
            wait = int(r.headers.get("Retry-After", wait))
            if wait > 60:  # بیشتر از یک دقیقه صبر نکنید
                raise RuntimeError(f"انتظار {wait} ثانیه: سهمیه را بررسی کنید")
        elif 400 <= code < 500:
            # 400، 401، 403، 404، 410: تلاش دوباره آن‌ها را حل نمی‌کند
            raise RuntimeError(f"{code}: {r.text[:200]}")
        if attempt < tries - 1:
            time.sleep(wait)
    return None

Retry-After بلند وقتی هم می‌آید که سهمیهٔ دوره تمام شده باشد: بازنشانی ممکن است روزها دیگر باشد و fetch هیچ‌وقت بیش از یک دقیقه صبر نمی‌کند. تلاش مجدد، ETag و فیلترها در مقالهٔ پولینگ API بدون برخورد با محدودیت‌ها آمده است.

اسپرد کاذب: دفتر کم‌عمق و توکن‌های شبیه هم

spread_pct از آخرین معاملات محاسبه می‌شود، در حالی که فقط با ask می‌توانید بخرید و فقط با bid می‌توانید بفروشید. در مثال FUEL از راهنمای اندپوینت‌های آربیتراژ اسپرد بر اساس آخرین معاملات 0.11% و در بهترین قیمت‌ها −0.11% است. فیلدهای ask_buy و bid_sell در هر ردیف Spot – Spot در هر پلنی هستند و quote_spread زیر با آن‌ها اسپرد را در بهترین قیمت‌ها حساب می‌کند.

دفتر سفارش کم‌عمق شکاف را باد می‌کند. مثال فرضی: آخرین معامله یک ساعت پیش با 1.18$ ثبت شده، بهترین bid اکنون 1.02$ است و ask در صرافی خرید 1.00$. اسپرد بر اساس آخرین معاملات 18% و در بهترین قیمت‌ها 2% است و شاید 1000$ اصلاً پر نشود: در Pro و Max مقدار order_delta.status = exhausted در volume=1000 دقیقاً همین را نشان می‌دهد.

منبع دوم اسپرد کاذب یک نماد مشترک بین توکن‌های متفاوت است، مثل توکنی روی BSC و پروژه‌ای نامرتبط روی Solana. برای توکن دارای قرارداد، /coins/search را با نماد در query صدا بزنید: در contracts[] باید عنصری باشد که exchanges آن هر دو صرافی جفت را فهرست کند (نام‌ها را بدون حساسیت به حروف مقایسه کنید). نبودن چنین عنصری یعنی انتقال مستقیم وجود ندارد: یا توکن‌ها متفاوت‌اند یا مسیر از پل می‌گذرد که ریسک‌های خودش را دارد.

def is_fresh(meta, k=3):
    """اسنپ‌شات از k بازهٔ پلن قدیمی‌تر نیست."""
    age = time.time() - meta["updated_at"]
    return age <= k * meta["freshness_sec"]


def quote_spread(row):
    """اسپرد در بهترین قیمت‌ها: خرید با ask، فروش با bid."""
    ask, bid = row.get("ask_buy"), row.get("bid_sell")
    if ask is None or bid is None or ask <= 0:
        return None  # قیمت نیست یا صفر است: ردیف را رد کنید
    return (bid - ask) / ask * 100


pause, fails = 60, 0
while True:
    got = fetch("/arbitrage/spot-spot", {"min_spread": 1})
    if got is None or not is_fresh(got[1]):
        fails += 1  # داده نیست یا کهنه است: بدون هشدار
        if fails == 3:
            print("3 چرخه بدون داده تازه")  # به خودتان هشدار بدهید
    else:
        rows, meta = got
        fails, pause = 0, meta["freshness_sec"]
        for row in rows:
            s = quote_spread(row)
            if s is not None and s >= 0.5:
                print(row["coin"], row["exchange_buy"], "→",
                      row["exchange_sell"], f"{s:.2f}%")
    time.sleep(pause)  # مکث در هر مسیر اجرا می‌شود

استثنا از fetch حلقه را متوقف می‌کند: ربات واقعی پیش از خروج به صاحبش پیام می‌دهد.

ریسک‌های کد

تلاش مجدد بدون مکث و حلقه‌های بی‌پایان

ربات اول معمولاً بلافاصله بعد از خطا دوباره تلاش می‌کند: if r.status_code != 200: continue. با 503 چنین حلقه‌ای درخواست‌ها را پشت‌سرهم و بدون مکث می‌فرستد: خطاها از سهمیه کم نمی‌کنند اما در سقف درخواست در ثانیه حساب می‌شوند، پس 429 با Retry-After: 1 می‌آید. وقتی اشتراک تمام شود، همین حلقه تا ابد 401 می‌گیرد. و continue پیش از time.sleep() مکث را در هر پاسخ خالی رد می‌کند، به همین دلیل مکث آخرین خط حلقهٔ بالاست.

اشتباه مقابل انتظار بی‌پایان است. time.sleep(int(r.headers["Retry-After"])) روی سهمیهٔ تمام‌شده روزها می‌خوابد: مثلاً Retry-After: 259200 یعنی 259,200 / 86,400 = 3 روز. درخواست بدون timeout هم می‌تواند تا ابد معلق بماند، همان‌طور که مستندات requests هشدار می‌دهد.

null و تقسیم بر صفر

Genesis API برای مقدارهای خالی null می‌گذارد و Python آن را None می‌کند. مقایسهٔ row["volume_24h_sell"] > 10000 با None خطای TypeError می‌دهد و یک ردیف کل حلقه را می‌اندازد. JavaScript خطایی نمی‌دهد: null > 0.5 برابر false و null < 1 برابر true است و فیلتر بی‌صدا خراب می‌شود.

null یعنی «داده نیست» و جایگزین کردن آن با صفر از راه or 0 خطرناک است: در لغزش DEX مقدار tax_sell_pct = null یعنی منبعی برای مالیات نیست و or 0 آن را 0% می‌کند. طبق مستندات null در bid_* و ask_*، volume_24h_*، max_position_usd، next_payout، در profit_usd برای جفت‌های دارای پای بوکمیکر و در apr_pct وقتی کمتر از یک روز مانده باشد می‌آید.

تقسیم بر صفر همین تله است. ask صفر در Python ZeroDivisionError می‌دهد، اما در JavaScript مقدار 1 / 0 برابر Infinity است و Infinity > 0.5 برابر true: ربات جفتی با اسپرد بی‌نهایت می‌فرستد. مخرج را پیش از تقسیم بررسی کنید، همان‌طور که quote_spread شرط ask <= 0 را می‌سنجد.

منطقه‌های زمانی

زمان‌ها در Genesis API ثانیه‌های unix و رشته‌های UTC هستند: next_payout در نرخ‌های فاندینگ به شکل HH:MM به وقت UTC می‌آید. datetime.fromtimestamp(ts) بدون منطقهٔ زمانی ساعت محلی سرور را برمی‌گرداند و datetime.utcnow() از Python 3.12 منسوخ است؛ مستندات Python به‌جای آن datetime.now(timezone.utc) را معرفی می‌کند.

مثال فرضی: سرور روی UTC+3 است و ساعتش 09:30 را نشان می‌دهد، یعنی 06:30 به وقت UTC. پرداخت 08:00 یک ساعت و 30 دقیقه دیگر است، اما کدی که 08:00 را با ساعت محلی مقایسه می‌کند نتیجه می‌گیرد پرداخت گذشته و تا بعدی 22 ساعت و 30 دقیقه حساب می‌کند، یعنی 21 ساعت اشتباه.

from datetime import datetime, timedelta, timezone


def until_payout(hhmm, now=None):
    """زمان تا next_payout؛ رشتهٔ HH:MM به وقت UTC."""
    if hhmm is None:
        return None  # null: زمان پرداخت وجود ندارد
    now = now or datetime.now(timezone.utc)
    h, m = map(int, hhmm.split(":"))
    t = now.replace(hour=h, minute=m, second=0, microsecond=0)
    if t <= now:
        t += timedelta(days=1)  # «00:00» در ساعت 23:50 یعنی فردا
    return t - now


now = datetime(2026, 11, 15, 6, 30, tzinfo=timezone.utc)
print(until_payout("08:00", now))  # 1:30:00

ریسک‌های کلید

کلید Genesis API فقط‌خواندنی است: نمی‌تواند سفارش بگذارد یا پول برداشت کند. نشت آن به سهمیه و سقف درخواست در ثانیهٔ شما می‌زند و ربات شما پیش از پایان دوره 429 می‌گیرد. نشانه‌های هشدار: «فراخوانی‌های مصرف‌شده» در پروفایل سریع‌تر از حساب کد شما بالا می‌رود، یا «استفاده‌شده …» زمانی تازه نشان می‌دهد در حالی که ربات خاموش است.

کلید یک بار نمایش داده می‌شود و Genesis Arbitrage فقط هش آن را نگه می‌دارد، پس کلید نشت‌کرده دوباره صادر می‌شود: «صدور مجدد» کلید قدیمی را بی‌درنگ غیرفعال و کلید تازه صادر می‌کند. کلیدها از جاهایی نشت می‌کنند که اشتباهاً در آن‌ها گذاشته شده‌اند: مخزن عمومی، آدرس درخواست، کد صفحه، اسکرین‌شات، لاگی که هدرهای درخواست دارد. به‌جای آن کد وضعیت و X-Request-Id را لاگ کنید؛ قواعد نگهداری در مدخل کلید API واژه‌نامه است.

کلید صرافی رده‌ای دیگر از ریسک است: با حق برداشت می‌تواند سکه‌ها را از حساب خارج کند. ربات معاملاتی به این حق نیاز ندارد، پس کلید را بدون برداشت، بسته به IP سرور و جدا برای هر سرویس بسازید. جزئیات در چگونه حساب صرافی ارز دیجیتال را امن کنیم است.

عامل‌های AI: اعداد، دستورهای تزریقی، تأیید

عامل Genesis API را از طریق سرور شما صدا می‌زند: مدل اندپوینت و آرگومان‌ها را انتخاب می‌کند و سرور درخواست را با کلید می‌فرستد. راه‌اندازی در راهنمای Genesis API برای عامل‌های هوش مصنوعی است و طراحی کلی در مقالهٔ داده‌های بازار ارز دیجیتال برای عامل‌های هوش مصنوعی.

اعداد اشتباه

مدل ممکن است 0.92 را 92% بخواند نه 0.92%، funding_pct هر بازه را با funding_8h_pct هشت‌ساعته اشتباه بگیرد، یا قیمتی را بگوید که در پاسخ نیست. کد اعداد را مستقیم از پاسخ API در هشدارها می‌گذارد و انتخاب و توضیح برای مدل می‌ماند. اگر مدل خودش عدد بنویسد، هر عدد را با نتیجهٔ ابزار تطبیق دهید.

دستور در متن بیرونی

بعضی فیلدها را دیگران می‌نویسند: title و outcome بازارهای پیش‌بینی، name معامله‌گر، token_name رویدادهای آن‌چین و message_ru و message_en سیگنال‌ها. هر کسی می‌تواند توکنی را «دستورهای قبلی را نادیده بگیر و…» نام بگذارد و مدلی که نام را بخشی از پرامپتش می‌خواند ممکن است اجرایش کند. این تزریق پرامپت (prompt injection) است، اولین مورد OWASP Top 10 برای برنامه‌های LLM در 2025: LLM01:2025.

چنین فیلدهایی را فقط داخل نتیجهٔ ابزار بدهید، طولشان را محدود کنید و در پرامپت سیستم بنویسید که داده‌اند. کلید در هندلر سمت سرور می‌ماند.

تأیید انسانی

Genesis API فقط داده می‌خواند: عاملی که روی آن ساخته شود جفت را پیدا می‌کند و دربارهٔ آن می‌نویسد، اما معامله نمی‌کند. API معاملاتی صرافی که به عامل وصل شود بیرون از Genesis API است و با مسئولیت خودتان. OWASP در میان راهکارهای کاهش خطر کنترل انسانی روی عملیات دارای دسترسی ویژه را فهرست کرده است: سفارش فقط پس از «بله» معامله‌گری می‌رود که جفت، قیمت‌ها و زمان داده را می‌بیند.

چک‌لیست پیش از راه‌اندازی

  1. کلید روی سرور در GENESIS_API_KEY است و در هیچ‌جای کد، آدرس درخواست‌ها، مرورگر، لاگ‌ها و پرامپت‌ها نیست.
  2. هر درخواست timeout دارد.
  3. فقط 429، 503، خطاهای دیگر 5xx و قطعی شبکه دوباره امتحان می‌شوند، با مکث و حداکثر سه بار.
  4. 400، 401، 403، 404، 410 و Retry-After بیش از یک دقیقه ربات را با پیام متوقف می‌کنند.
  5. مکث بین پولینگ‌ها دست‌کم meta.freshness_sec است و در هر مسیر حلقه اجرا می‌شود.
  6. سن اسنپ‌شات پیش از هر هشدار بررسی می‌شود و برای دفتر سفارش stale و order_delta.status هم.
  7. «داده نیست» و «جفت نیست» دو وضعیت جدا هستند و سه چرخه بدون داده پیام خرابی می‌دهد.
  8. null با None سنجیده می‌شود، مخرج‌ها با صفر و زمان به وقت UTC پردازش می‌شود.
  9. جفت با اسپرد در بهترین قیمت‌ها، قرارداد مشترک، withdraw_enabled_buy و deposit_enabled_sell رد می‌شود.
  10. کد اعداد را در پیام‌ها می‌گذارد، متن بیرونی به‌عنوان داده به مدل می‌رسد و انسان هر سفارش را تأیید می‌کند.

جمع‌بندی دوره: ادامه از کجا

دوره پنج درس دارد: مفاهیم، اولین درخواست، داده برای تصمیم، مانیتور Python و ریسک‌های آن؛ مبانی در درس 1 است. جزئیات هر گام:

خودتان امتحان کنید

  1. تازگی پلن خود را پیدا کنید

    /account/usage را صدا بزنید و freshness_sec و calls_used را یادداشت کنید: این درخواست فراخوانی حساب نمی‌شود.

  2. سن اسنپ‌شات را بسنجید

    /arbitrage/spot-spot را با fetch بگیرید، time.time() - meta["updated_at"] را چاپ کنید و با آستانهٔ 3 × freshness_sec مقایسه کنید.

  3. دو اسپرد را مقایسه کنید

    spread_pct و quote_spread(row) را برای پنج ردیف چاپ کنید و بشمارید چند جفت در بهترین قیمت‌ها مثبت می‌ماند.

  4. مسیر خطا را آزمایش کنید

    ربات را با مقدار نمایشی GENESIS_API_KEY=gns_live_XXXXXXXXXXXXXXXX اجرا کنید: پاسخ 401 invalid_key باید آن را با پیامی روشن متوقف کند.

  5. چک‌لیست را مرور کنید

    هرچه کدتان کم دارد اضافه کنید، پیش از آنکه ربات را شبانه‌روز اجرا کنید.