Genesis Arbitrage

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

پاسخ‌ها و خطاهای Genesis API: قالب JSON، ETag و 304، کدهای HTTP

به طور خلاصه

  • پاسخ موفق Genesis API یک پوشش از success، data و meta است؛ خطا یعنی success: false به‌همراه شیء error با کد و پیام.
  • ارسال ETag قبلی در If-None-Match در صورت تغییرنکردن داده‌ها 304 بدون بدنه برمی‌گرداند و 304 سهمیه مصرف نمی‌کند.
  • 429 و 503 را پس از مکث Retry-After دوباره امتحان کنید. تکرار، 400، 401، 403، 404 و 410 را درست نمی‌کند — درخواست، کلید یا پلن را تغییر دهید.

Genesis API به هر درخواست با JSON پاسخ می‌دهد؛ قالب داده متنی که از شیءهای کلید–مقدار و آرایه‌ها ساخته می‌شود. پاسخ موفق همیشه در یک پوشش یکسان از success، data و meta می‌آید؛ خطا با کد وضعیت HTTP و شیء error می‌آید. کد وضعیت به برنامه شما می‌گوید قدم بعدی چیست: استفاده از داده‌ها، انتظار Retry-After ثانیه و تکرار، یا اصلاح درخواست.

پوشش پاسخ: success، data و meta

پاسخ کوتاه‌شده GET /arbitrage/spot-spot از مستندات (این اندپوینت در همه پلن‌ها در دسترس است):

{
  "success": true,
  "data": [
    {
      "coin": "FUEL",
      "exchange_buy": "ByBit",
      "exchange_sell": "Gate",
      "spread_pct": 0.11,
      …
    }
  ],
  "meta": {
    "count": 214,
    "updated_at": 1783802410,
    "freshness_sec": 10,
    "plan": "pro"
  }
}
فیلدنوعمحتوا
successbooleantrue — درخواست موفق بود، false — خطا
dataآرایه یا شیءداده‌های اندپوینت
meta.countintتعداد آیتم‌ها در data
meta.updated_atintزمان یونیکس ساخت داده‌ها
meta.freshness_secintتأخیر ارائه برای پلن شما، به ثانیه
meta.planstringپلن شما، در مثال pro

استثنا تحلیل فاندینگ است: meta آن شامل count، updated_at و schema_version است و freshness_sec و plan ندارد. پوشش پاسخ در بخش قالب پاسخ مستندات توضیح داده شده و فیلدهای data در صفحه هر اندپوینت.

سه قرارداد برای همه اندپوینت‌ها برقرار است:

data: آرایه‌ای از ردیف‌ها یا یک شیء

شکل data در توضیح هر اندپوینت آمده است. برای GET /arbitrage/spot-spot آرایه است: یک آیتم برای هر جفت آربیتراژ، مثل یک ردیف جدول در سایت. برای GET /account/usage یک شیء واحد با وضعیت کلید شماست:

curl "https://api.genesisarbitrage.com/v1/account/usage" \
  -H "X-API-Key: gns_live_XXXXXXXXXXXXXXXX"
{
  "success": true,
  "data": {
    "plan": "pro",
    "calls_used": 184201,
    "calls_limit": 5000000,
    "rps_limit": 5,
    "freshness_sec": 10,
    "period_resets_at": 1786492800
  },
  "meta": { … }
}

/account/usage در همه پلن‌ها در دسترس است و پلن، مصرف سهمیه و freshness_sec را نشان می‌دهد: درخواست‌های مکررتر از آن فایده‌ای ندارد. فیلدها در مصرف توضیح داده شده‌اند و اولین درخواست در شروع سریع گام‌به‌گام آمده است. کدی که با چند اندپوینت کار می‌کند باید شکل داده را صریحاً بررسی کند: در Python با isinstance(data, list).

فیلترها: اختیاری، بدون آن‌ها کل مجموعه داده

همه پارامترهای فیلتر اختیاری‌اند: درخواست بدون آن‌ها کل مجموعه داده اندپوینت را برمی‌گرداند. چند صرافی را در exchange با ویرگول جدا کنید و کوین را با نماد آن در coin بدهید:

curl -G --compressed \
  "https://api.genesisarbitrage.com/v1/arbitrage/spot-spot" \
  -d coin=BTC -d exchange=Binance,OKX -d min_spread=0.5 \
  -H "X-API-Key: gns_live_XXXXXXXXXXXXXXXX"

گزینه -G پارامترهای -d را به رشته کوئری تبدیل می‌کند: ?coin=BTC&exchange=Binance,OKX&min_spread=0.5. نام صرافی‌ها را همان‌طور بنویسید که در فیلدهای پاسخ برمی‌گردد: ByBit، Gate، MEXC. پارامترهای اندپوینت‌های آربیتراژ در راهنمای اندپوینت‌های آربیتراژ است.

سهمیه پاسخ‌ها را می‌شمارد، نه ردیف‌ها: درخواست با فیلتر یا بدون آن یک فراخوانی است. فیلتر بدنه پاسخ را کوچک می‌کند و همراه آن ترافیک و مصرف محدودیت دانلود را. همه محدودیت‌ها در راهنمای محدودیت‌های Genesis API آمده است.

فشرده‌سازی gzip

Genesis API مجموعه‌های کامل داده و پاسخ‌های بزرگ را وقتی کلاینت هدر Accept-Encoding: gzip را بفرستد با gzip فشرده ارسال می‌کند (RFC 9110، بخش 12.5.3). پاسخ کوچک ممکن است فشرده‌نشده برسد.

کتابخانه requests در Python این هدر را خودش می‌فرستد و پاسخ را باز می‌کند. curl بدون گزینه --compressed فشرده‌سازی نمی‌خواهد؛ با این گزینه می‌خواهد و باز می‌کند.

محدودیت دانلود داده‌های فشرده را می‌شمارد: حداکثر 60 MB در هر 10 ثانیه برای هر کلید، و پاسخ‌های زیر 64 KB شمرده نمی‌شوند. در صورت عبور از حد، 429 download_limited می‌گیرید.

ETag و 304: از داده‌های بدون تغییر بگذرید

ETag هدر پاسخی است با برچسب نسخه داده‌ها. کلاینت این برچسب را در هدر If-None-Match پس می‌فرستد. اگر داده‌ها تغییر نکرده باشند، سرور با 304 Not Modified و بدون بدنه پاسخ می‌دهد؛ اگر تغییر کرده باشند، 200 معمولی با داده‌های جدید و ETag جدید.

# کل مجموعه داده، بدون فیلتر: فقط هدرهای پاسخ را چاپ کن
curl -sS -D - -o /dev/null --compressed \
  "https://api.genesisarbitrage.com/v1/arbitrage/spot-spot" \
  -H "X-API-Key: gns_live_XXXXXXXXXXXXXXXX"

# تکرار با ETag پاسخ اول (مقدار نمونه)
curl -sS -D - -o /dev/null --compressed \
  "https://api.genesisarbitrage.com/v1/arbitrage/spot-spot" \
  -H "X-API-Key: gns_live_XXXXXXXXXXXXXXXX" \
  -H 'If-None-Match: W/"5d1f0c9a"'

ETag با پاسخ درخواست بدون فیلتر می‌آید و با هر اسنپ‌شات جدید داده تغییر می‌کند. پاسخ درخواست فیلترشده برای همان درخواست ساخته می‌شود و بدون ETag می‌آید؛ آنجا خود فیلتر ترافیک را کم می‌کند. ETag روی داده‌های کندتغییر بیشترین فایده را دارد: ETag خلاصه تحلیل فاندینگ تقریباً هر 15 دقیقه عوض می‌شود و پاسخ‌های 304 در محدودیت دانلود کامل آن شمرده نمی‌شوند.

پاسخ 304 سهمیه مصرف نمی‌کند اما در محدودیت درخواست در ثانیه حساب می‌شود. برچسب را دقیقاً همان‌طور که رسیده پس بفرستید: طبق RFC 9110 رشته‌ای داخل گیومه است و پیشوند W/ نشانه برچسب ضعیف است.

کدهای خطا و کار بعدی

هنگام خطا، Genesis API وضعیت HTTP متناظر و بدنه‌ای با success: false برمی‌گرداند:

{
  "success": false,
  "error": {
    "code": "rate_limited",
    "message": "Requests per second limit exceeded."
  }
}

error.code کدی ماشین‌خوان است که برنامه شما می‌تواند بر اساس آن شاخه بزند. error.message توضیح برای انسان است: برای 400 دلیل را می‌گوید و برای 410 نشانی جایگزین را.

HTTPerror.codeمعناچه کنیم
400bad_requestپارامترهای درخواست نامعتبر، مثلاً volume=700 در /orderbooks/execپارامترها را طبق message اصلاح کنید: همان درخواست دوباره شکست می‌خورد
401invalid_keyکلید وجود ندارد، نامعتبر یا لغوشده است، یا اشتراک API تمام شدههدر X-API-Key و وضعیت اشتراک را در پروفایل بررسی کنید
403plan_restrictedاندپوینت در پلن شما نیستبه پلنی که آن را دارد بروید یا درخواست را حذف کنید
404not_foundاندپوینت یا منبع پیدا نشد: مجموعه داده، بخش، کوین، دفتر سفارشمسیر و پارامترها را با مستندات مطابقت دهید
410goneاندپوینت بازنشسته شده استبه نشانی ذکرشده در message بروید
429rate_limitedمحدودیت درخواست در ثانیه رد شده، یا سهمیه دوره تمام شدهRetry-After ثانیه صبر و سرعت را کم کنید؛ اگر سهمیه تمام شده، منتظر بازنشانی بمانید یا پلن را ارتقا دهید
429download_limitedحجم دانلود رد شده: 60 MB داده فشرده در هر 10 ثانیه برای هر کلیدRetry-After صبر کنید، ترافیک را با فیلترها، coin و If-None-Match کم کنید
500internal_errorخطای داخلیبعداً دوباره امتحان کنید؛ اگر ادامه یافت با X-Request-Id به پشتیبانی بنویسید
503snapshot_not_readyداده‌ها در حال بازسازی است یا منبع آن دوباره راه‌اندازی می‌شودپس از Retry-After ثانیه دوباره امتحان کنید

هدر Retry-After با 429 و 503 می‌آید و تعداد ثانیه‌های انتظار را دارد: معمولاً چند ثانیه، اما وقتی سهمیه دوره تمام شده باشد، زمان تا بازنشانی سهمیه است که می‌تواند چند روز باشد. خطاهای 4xx و 5xx سهمیه مصرف نمی‌کنند اما در محدودیت درخواست در ثانیه حساب می‌شوند، بنابراین تکرار زودهنگام به احتمال زیاد همان خطا را برمی‌گرداند. اصطلاحات فرهنگ لغت: HTTP 429 و rate limit.

X-Request-Id: چه چیزی برای پشتیبانی بفرستیم

هر پاسخ Genesis API، موفق یا ناموفق، هدر X-Request-Id با شناسه درخواست دارد. اگر خطایی تکرار می‌شود یا داده‌ها نادرست به نظر می‌رسند، این‌ها را برای پشتیبانی بفرستید:

کلید خود را نفرستید. اگر کلید در چت، لاگ‌ها یا کدی که دیگران می‌بینند افتاده، آن را در پروفایل خود دوباره صادر کنید: کلید قدیمی فوراً از کار می‌افتد.

ترتیب پردازش پاسخ

  1. کد وضعیت را بررسی کنید

    200 — data و meta را بخوانید و اگر ETag آمد ذخیره کنید. 304 — از داده‌های پاسخ قبلی استفاده کنید.

  2. خطاهای موقت را مدیریت کنید

    429 و 503 با مکث کوتاه — Retry-After ثانیه صبر کنید و دوباره امتحان کنید، حداکثر سه بار پشت‌سرهم. 500 — بعداً دوباره امتحان کنید.

  3. در خطاهای درخواست متوقف شوید

    400، 401، 403، 404، 410 و 429 با مکث چندساعته یا چندروزه — پارامترها، کلید یا پلن را اصلاح کنید یا منتظر بازنشانی سهمیه بمانید.

  4. سن داده‌ها را بررسی کنید

    meta.updated_at را با زمان فعلی مقایسه کنید: ربات که روی اسنپ‌شات قدیمی عمل می‌کند اسپردهایی را می‌بیند که دیگر وجود ندارند.

  5. درخواست بعدی را زمان‌بندی کنید

    زودتر از meta.freshness_sec ثانیه بعد نه، و برای درخواست‌های بدون فیلتر با If-None-Match.

تابع get_json در Python

این تابع این قواعد را کنار هم می‌گذارد: آخرین ETag هر نشانی را نگه می‌دارد و با 304 داده‌های قبلی را برمی‌گرداند، با 429 و 503 منتظر Retry-After می‌ماند و حداکثر سه بار دوباره امتحان می‌کند، اما مکث‌های بیشتر از یک دقیقه را منتظر نمی‌ماند. خطاهای دیگر استثنایی با وضعیت، پیام و X-Request-Id ایجاد می‌کنند. کلید از متغیر محیطی GENESIS_API_KEY خوانده می‌شود.

import os
import time
import requests

BASE = "https://api.genesisarbitrage.com/v1"
session = requests.Session()
session.headers["X-API-Key"] = os.environ["GENESIS_API_KEY"]
cache = {}  # (مسیر، پارامترها) -> (ETag، داده‌ها)


class GenesisError(Exception):
    def __init__(self, status, text):
        super().__init__(f"{status} {text}")
        self.status = status


def get_json(path, params=None):
    key = (path, tuple(sorted((params or {}).items())))
    for attempt in range(4):  # یک درخواست و حداکثر 3 تکرار
        hdr = {"If-None-Match": cache[key][0]} if key in cache else {}
        r = session.get(BASE + path, params=params,
                        headers=hdr, timeout=15)
        if r.status_code == 304:
            return cache[key][1]  # داده‌ها تغییر نکرده‌اند
        wait = float(r.headers.get("Retry-After", 1))
        if r.status_code in (429, 503) and attempt < 3 and wait <= 60:
            time.sleep(wait)  # منتظر ساعت‌ها یا روزها نمی‌مانیم
            continue
        try:
            body = r.json()
        except ValueError:
            raise GenesisError(r.status_code, "not JSON") from None
        if r.status_code != 200 or not body.get("success"):
            err = body.get("error") or {}
            raise GenesisError(r.status_code, (
                f"{err.get('code')}: {err.get('message')}; "
                f"X-Request-Id {r.headers.get('X-Request-Id')}"))
        if "ETag" in r.headers:  # فقط در پاسخ‌های بدون فیلتر
            cache[key] = (r.headers["ETag"], body["data"])
        return body["data"]

پارامتر timeout=15 ضروری است: بدون مهلت، requests برای همیشه منتظر پاسخ می‌ماند.

درخواست با فاصله پلن شما: مجموعه کامل داده با ETag می‌آید و ردیف‌ها در کد فیلتر می‌شوند. خطاهای 4xx برنامه را متوقف می‌کنند؛ خرابی سرور تا چرخه بعد صبر می‌کند.

pause = get_json("/account/usage")["freshness_sec"]
while True:
    try:
        rows = get_json("/arbitrage/spot-spot")  # کل مجموعه داده
        top = [x for x in rows if x["spread_pct"] >= 1]
        print(len(top), "جفت با اسپرد 1% یا بیشتر")
    except GenesisError as e:
        if e.status < 500:
            raise  # 4xx: درخواست، کلید، پلن یا سهمیه
        print("خطای سرور، در چرخه بعد دوباره امتحان می‌شود:", e)
    time.sleep(pause)

پرسش و پاسخ

آیا پاسخ 304 سهمیه مصرف می‌کند؟

خیر. فقط پاسخ‌های 200 سهمیه مصرف می‌کنند. پاسخ‌های 304 و خطاهای 4xx و 5xx رایگان‌اند اما در محدودیت درخواست در ثانیه شمرده می‌شوند.

بعد از 410 چه کنم؟

اندپوینت بازنشسته شده و نشانی جایگزین در error.message است. مثلاً GET /arbitrage/predictions در 15 نوامبر 2026 بازنشسته شد و message آن به /predictions/arbitrage اشاره می‌کند. مسیر را در کد خود به‌روز کنید.

چرا بدون خطا data خالی است؟

فیلترها همه ردیف‌ها را حذف کرده‌اند: مثلاً min_spread از همه اسپردهای فعلی بالاتر است. در چنین پاسخی meta.count برابر 0 است، پس فیلتر را سبک‌تر کنید.

چرا در پاسخ ETag نیست؟

ETag با پاسخ درخواست بدون فیلتر می‌آید. پاسخ درخواستی با coin، exchange، min_spread یا فیلتر دیگر برای همان درخواست ساخته می‌شود و بدون برچسب می‌آید، پس If-None-Match برای آن کاربرد ندارد.