Genesis Arbitrage

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

محدودیت‌های Genesis API: سهمیه فراخوانی، درخواست در ثانیه، تازگی داده و خطاهای 429

به طور خلاصه

  • پلن شما سهمیه فراخوانی در هر 30 روز (از 500K در Trial تا 10M در Max)، محدودیت درخواست در ثانیه (از 1 تا 15) و تازگی داده (از 60 تا 5 ثانیه) را تعیین می‌کند.
  • فقط پاسخ 200 از سهمیه کم می‌کند. پاسخ‌های 304 و خطاها رایگان‌اند، اما یک جایگاه از محدودیت درخواست در ثانیه را می‌گیرند؛ با عبور از هر محدودیت سرور 429 برمی‌گرداند و چیزی کسر نمی‌کند.
  • نظرسنجی سریع‌تر از meta.freshness_sec داده تازه‌ای نمی‌آورد: پلن شما در هر آن بازه یک اسنپ‌شات تازه می‌گیرد و If-None-Match درخواست‌های اضافه را به پاسخ‌های رایگان 304 تبدیل می‌کند.

محدودیت‌های Genesis API چهار سقف برای هر کلید هستند: سهمیه فراخوانی در یک دوره 30 روزه، rate limit بر حسب درخواست در ثانیه، تازگی داده و حجم دانلود. سه مورد اول را پلن شما تعیین می‌کند؛ حجم دانلود برای همه یکسان است: 60 MB داده فشرده در هر 10 ثانیه. با عبور از هر محدودیت سرور خطای 429 برمی‌گرداند و چیزی کسر نمی‌کند.

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

پلنفراخوانی در 30 روزدرخواست در ثانیهتازگی
Trial، 20$ در ماه500,000160 ثانیه
Start، 50$ در ماه2,000,000230 ثانیه
Pro، 100$ در ماه5,000,000510 ثانیه
Max، 200$ در ماه10,000,000155 ثانیه

تازگی داده فاصله‌ای است که پلن شما اسنپ‌شات جدید می‌گیرد: در Trial هر 60 ثانیه و در Max هر 5 ثانیه. پاسخ‌ها آن را در فیلد meta.freshness_sec دارند. پرداخت 3 ماهه 10% و 6 ماهه 20% صرفه‌جویی دارد. مقایسه پلن‌ها در صفحه تعرفه‌های Genesis API است و قواعد در بخش پلن‌ها و محدودیت‌ها مستندات.

چه چیزی از سهمیه کم می‌کند

یک فراخوانی یعنی پاسخ 200. پاسخ‌های 304 (داده تغییر نکرده) و خطاهای 4xx و 5xx از سهمیه کم نمی‌کنند، اما در محدودیت درخواست در ثانیه شمرده می‌شوند. درخواست به /account/usage فراخوانی مصرف نمی‌کند.

سهمیه برای یک دوره 30 روزه است، نه ماه تقویمی. زمان بازنشانی در هدر X-Quota-Reset، فیلد period_resets_at و خط «resets …» در پروفایل شما آمده است. وقتی سهمیه تمام شود، سرور 429 rate_limited می‌دهد و Retry-After تعداد ثانیه‌های باقی‌مانده تا بازنشانی را نشان می‌دهد که می‌تواند چند روز باشد.

هدرهای rate limit

پاسخ یک اندپوینت داده، وضعیت محدودیت‌های شما را دارد (مقادیر نمونه):

هدرمثالچه نشان می‌دهد
X-RateLimit-Limit5محدودیت درخواست در ثانیه برای پلن شما
X-RateLimit-Remaining4درخواست‌های باقی‌مانده در پنجره فعلی
X-RateLimit-Reset1785200001زمان unix بازنشانی پنجره
X-Quota-Limit5000000سهمیه فراخوانی برای دوره 30 روزه
X-Quota-Remaining4815799فراخوانی‌های باقی‌مانده در دوره
X-Quota-Reset1786492800زمان unix بازنشانی سهمیه
Retry-After1ثانیه‌های انتظار پیش از تلاش دوباره، در 429 و 503

پنجره درخواست در ثانیه یک ثانیه است، پس در پاسخ عادی X-RateLimit-Reset به آغاز ثانیه بعد اشاره می‌کند. سهمیه باقی‌مانده در مثال: 5,000,000 − 184,201 = 4,815,799 فراخوانی، همان اعدادی که /account/usage برمی‌گرداند.

اندپوینت /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": { … }
}
فیلدنوعمعنی
planstringپلن: trial، start، pro یا max
calls_usedintفراخوانی‌های مصرف‌شده در دوره فعلی
calls_limitintسهمیه فراخوانی در هر دوره
rps_limitintمحدودیت درخواست در ثانیه
freshness_secintتأخیر داده، بر حسب ثانیه
period_resets_atintزمان unix بازنشانی سهمیه

این اندپوینت در همه پلن‌ها در دسترس است و در بخش مصرف توضیح داده شده. هنگام راه‌اندازی ربات آن را فراخوانی کنید تا پیش از شروع نظرسنجی، پلن و سهمیه باقی‌مانده را بررسی کنید.

خطاهای 429: rate_limited و download_limited

پاسخچه زمانی می‌آیدچه باید کرد
429 rate_limitedدرخواست در ثانیه بیش از حد مجاز پلنتا Retry-After صبر کنید و درخواست‌ها را از هم فاصله دهید
429 rate_limitedسهمیه دوره تمام شدهمنتظر بازنشانی بمانید یا پلن را عوض کنید
429 rate_limitedدانلود کامل تحلیل فاندینگ زودتر از حد مجازبا coin یک برش بگیرید یا If-None-Match بفرستید
429 download_limitedبیش از 60 MB داده فشرده در 10 ثانیهتا Retry-After صبر کنید و درخواست را با فیلتر محدود کنید

کد وضعیت 429 Too Many Requests در RFC 6585 تعریف شده و در آن Retry-After اختیاری است. Genesis API آن را با هر 429 می‌فرستد و همیشه بر حسب ثانیه.

پاسخ‌های زیر 64 KB در حجم دانلود شمرده نمی‌شوند و نظرسنجی همه مجموعه‌داده‌ها با تازگی پلن شما با فاصله زیاد در محدودیت جا می‌شود. دانلود کامل تحلیل فاندینگ بدون coin محدودیت خودش را دارد: /funding/analytics/summary و /funding/analytics/recent هر 60 ثانیه یک بار، /funding/analytics/daily هر 300 ثانیه یک بار برای هر کلید. درخواست‌های دارای coin و پاسخ‌های 304 محدود نیستند؛ جزئیات در بخش تحلیل فاندینگ است.

دسترسی بر اساس پلن و 403 plan_restricted

پلنچه چیزی باز است
Trialآربیتراژ CEX (Spot – Spot، Spot – Futures، Futures – Futures)، نرخ فاندینگ و اسپرد فاندینگ، Fair – Last، CEX Pumps – Dumps، اوپن اینترست، سیگنال‌های AI، جست‌وجوی کوین، /account/usage
Startهمه موارد Trial، به‌علاوه سهام /arbitrage/stocks، بخش‌های آن‌چین /onchain/{section}، آربیتراژ پیش‌بینی در حالت‌های exact و dutch، وضعیت پلتفرم‌ها
Pro و Maxهمه اندپوینت‌ها: DEX – Spot، DEX – Futures، Crosschain، DEX Dumps، دفتر سفارش، تحلیل فاندینگ، تحلیل بازارهای پیش‌بینی، پول هوشمند، معاملات، تریدرها، حالت‌های llm و sport، سواپ‌های DEX، تحلیل OnChain و کوین

اندپوینت خارج از پلن شما 403 برمی‌گرداند، همچنین درخواست mode=sport به /predictions/arbitrage در Start:

{
  "success": false,
  "error": {
    "code": "plan_restricted",
    "message": "This endpoint is not included in your plan."
  }
}

403 از سهمیه کم نمی‌کند. تلاش دوباره بی‌فایده است: فقط پلن بالاتر دسترسی را باز می‌کند.

چگونه پلن را برای بار کاری خود انتخاب کنیم

مثال نمونه: رباتی سه اندپوینت /arbitrage/spot-spot، /funding/spread و /market/open-interest را هر 10 ثانیه و شبانه‌روزی نظرسنجی می‌کند.

همین ربات با نظرسنجی در تازگی هر پلن:

تازگی و نظرسنجیفراخوانی در 30 روزپلنسهم از سهمیه
هر 60 ثانیه129,600Trial26%
هر 30 ثانیه259,200Start13%
هر 10 ثانیه777,600Pro16%
هر 5 ثانیه1,555,200Max16%

نظرسنجی هر 10 ثانیه از Pro به بالا منطقی است: 777,600 / 5,000,000 = 15.552% سهمیه، و محدودیت 5 درخواست در ثانیه ارسال هر سه با هم را پوشش می‌دهد. اگر ربات با داده 30 ثانیه‌ای کنار بیاید، Start با نظرسنجی هر 30 ثانیه 259,200 / 2,000,000 = 12.96% سهمیه مصرف می‌کند.

نظرسنجی بدون فراخوانی هدررفته: ETag و Retry-After

پلن شما هر meta.freshness_sec ثانیه یک اسنپ‌شات جدید می‌گیرد و نظرسنجی سریع‌تر همان اسنپ‌شات را با همان meta.updated_at برمی‌گرداند. بدون هدر If-None-Match چنین پاسخی 200 و یک فراخوانی مصرف‌شده است. با آن، سرور 304 بدون بدنه می‌دهد: سهمیه دست‌نخورده می‌ماند، اما یک جایگاه از محدودیت در ثانیه گرفته می‌شود.

ETag در هر پاسخ نمی‌آید. مجموعه‌داده‌های کامل آن را برمی‌گردانند، یعنی درخواست‌های بدون فیلتر، مانند /funding/spread در مثال زیر. پاسخ فیلترشده (coin، min_spread و غیره) ETag ندارد و هر نظرسنجی یک فراخوانی خرج می‌کند: فیلتر ترافیک را کم می‌کند و ETag سهمیه را. تلاش دوباره و فشرده‌سازی در نظرسنجی بهینه از API و در راهنمای پاسخ‌ها و خطاها آمده است.

import os
import time

import requests

URL = "https://api.genesisarbitrage.com/v1/funding/spread"
KEY = os.environ["GENESIS_API_KEY"]
etag, pause = None, 30

while True:
    headers = {"X-API-Key": KEY}
    if etag:
        headers["If-None-Match"] = etag
    r = requests.get(URL, headers=headers, timeout=15)
    if r.status_code in (429, 500, 503):
        wait = int(r.headers.get("Retry-After", "5"))
        if wait > 600:  # سهمیه تمام شده، همین‌جا متوقف می‌شویم
            raise SystemExit(f"Quota used up, resets in {wait} s")
        time.sleep(wait)
        continue
    r.raise_for_status()  # تلاش دوباره 401 یا 403 را درست نمی‌کند
    left = r.headers.get("X-Quota-Remaining")  # ممکن است نباشد
    if left is not None and int(left) < 10_000:
        print("Quota running low:", left)
    if r.status_code == 200:  # در 304 داده تغییر نکرده است
        etag = r.headers.get("ETag")
        body = r.json()
        pause = body["meta"].get("freshness_sec", pause)
        print(body["meta"]["count"], "coins in the response")
    time.sleep(pause)

تغییر و تمدید پلن

نحوه دریافت و نگهداری کلید در راهنمای کلید Genesis API آمده است.

پرسش و پاسخ

اگر سهمیه زود تمام شود چه می‌شود؟

سرور تا بازنشانی سهمیه 429 rate_limited را همراه با Retry-After برمی‌گرداند و چیزی کسر نمی‌کند. منتظر دوره جدید بمانید یا پلن بالاتر بخرید: فوراً اعمال می‌شود و سهمیه تازه دارد.

آیا پاسخ‌های 304 و خطاها در محدودیت‌ها شمرده می‌شوند؟

در سهمیه نه: فقط 200 از آن کم می‌کند. اما در محدودیت درخواست در ثانیه شمرده می‌شوند: پاسخ‌های 304 و خطاها جایگاه‌هایی از پنجره یک‌ثانیه‌ای را می‌گیرند.

چطور سهمیه باقی‌مانده را بدون مصرف فراخوانی ببینم؟

X-Quota-Remaining را در پاسخ داده بخوانید یا /account/usage را فراخوانی کنید: این درخواست فراخوانی مصرف نمی‌کند. خط «Calls used» در پروفایل شما هم مصرف را نشان می‌دهد.

آیا با چند کلید می‌شود محدودیت را دور زد؟

خیر. هر حساب یک کلید دارد، محدودیت‌ها برای هر کلید شمرده می‌شوند و تغییر IP آن‌ها را عوض نمی‌کند. باز کردن چند حساب برای دور زدن محدودیت‌ها قوانین را نقض می‌کند؛ اگر بیشتر لازم دارید، به پلن بالاتر بروید.