محدودیتهای 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,000 | 1 | 60 ثانیه |
| Start، 50$ در ماه | 2,000,000 | 2 | 30 ثانیه |
| Pro، 100$ در ماه | 5,000,000 | 5 | 10 ثانیه |
| Max، 200$ در ماه | 10,000,000 | 15 | 5 ثانیه |
تازگی داده فاصلهای است که پلن شما اسنپشات جدید میگیرد: در 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-Limit | 5 | محدودیت درخواست در ثانیه برای پلن شما |
X-RateLimit-Remaining | 4 | درخواستهای باقیمانده در پنجره فعلی |
X-RateLimit-Reset | 1785200001 | زمان unix بازنشانی پنجره |
X-Quota-Limit | 5000000 | سهمیه فراخوانی برای دوره 30 روزه |
X-Quota-Remaining | 4815799 | فراخوانیهای باقیمانده در دوره |
X-Quota-Reset | 1786492800 | زمان unix بازنشانی سهمیه |
Retry-After | 1 | ثانیههای انتظار پیش از تلاش دوباره، در 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": { … }
}
| فیلد | نوع | معنی |
|---|---|---|
plan | string | پلن: trial، start، pro یا max |
calls_used | int | فراخوانیهای مصرفشده در دوره فعلی |
calls_limit | int | سهمیه فراخوانی در هر دوره |
rps_limit | int | محدودیت درخواست در ثانیه |
freshness_sec | int | تأخیر داده، بر حسب ثانیه |
period_resets_at | int | زمان 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 ثانیه و شبانهروزی نظرسنجی میکند.
- درخواست در ثانیه: 3 / 10 = 0.3 بهطور میانگین. اگر هر سه با هم ارسال شوند، در یک ثانیه میافتند و Trial و Start برای اضافهها
429برمیگردانند. - فراخوانی در روز: 86,400 / 10 = 8,640 نظرسنجی، 8,640 × 3 = 25,920 فراخوانی.
- فراخوانی در 30 روز: 25,920 × 30 = 777,600. این بیشتر از سهمیه Trial یعنی 500,000 است؛ در Start برابر 777,600 / 2,000,000 = 38.88% سهمیه است.
- تازگی: در Start اسنپشات هر 30 ثانیه بهروز میشود، یعنی 86,400 / 30 = 2,880 بار در روز. داده جدید از 2,880 × 3 × 30 = 259,200 فراخوانی میآید و 777,600 − 259,200 = 518,400 فراخوانی دیگر همان چیز را برمیگرداند.
همین ربات با نظرسنجی در تازگی هر پلن:
| تازگی و نظرسنجی | فراخوانی در 30 روز | پلن | سهم از سهمیه |
|---|---|---|---|
| هر 60 ثانیه | 129,600 | Trial | 26% |
| هر 30 ثانیه | 259,200 | Start | 13% |
| هر 10 ثانیه | 777,600 | Pro | 16% |
| هر 5 ثانیه | 1,555,200 | Max | 16% |
نظرسنجی هر 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)
تغییر و تمدید پلن
- پلن جدید بلافاصله پس از پرداخت اعمال میشود: محدودیتها و تازگی جدید، سهمیه از صفر شروع میشود و باقیمانده پلن قبلی از بین میرود. سایت پیش از پرداخت به شما هشدار میدهد.
- تمدید همان پلن به مدت آن روز اضافه میکند و سهمیه را بازنشانی نمیکند: دوره 30 روزه فعلی ادامه مییابد.
- با تغییر یا تمدید پلن کلید شما همان میماند، پس برنامههایتان نیازی به بهروزرسانی ندارند.
- تخفیف دوره روی قیمت ماهانه اعمال میشود: Pro برای 6 ماه $100 × 0.8 × 6 = $480 به جای $600 است و برای 3 ماه $100 × 0.9 × 3 = $270.
نحوه دریافت و نگهداری کلید در راهنمای کلید Genesis API آمده است.
پرسش و پاسخ
اگر سهمیه زود تمام شود چه میشود؟
سرور تا بازنشانی سهمیه 429 rate_limited را همراه با Retry-After برمیگرداند و چیزی کسر نمیکند. منتظر دوره جدید بمانید یا پلن بالاتر بخرید: فوراً اعمال میشود و سهمیه تازه دارد.
آیا پاسخهای 304 و خطاها در محدودیتها شمرده میشوند؟
در سهمیه نه: فقط 200 از آن کم میکند. اما در محدودیت درخواست در ثانیه شمرده میشوند: پاسخهای 304 و خطاها جایگاههایی از پنجره یکثانیهای را میگیرند.
چطور سهمیه باقیمانده را بدون مصرف فراخوانی ببینم؟
X-Quota-Remaining را در پاسخ داده بخوانید یا /account/usage را فراخوانی کنید: این درخواست فراخوانی مصرف نمیکند. خط «Calls used» در پروفایل شما هم مصرف را نشان میدهد.
آیا با چند کلید میشود محدودیت را دور زد؟
خیر. هر حساب یک کلید دارد، محدودیتها برای هر کلید شمرده میشوند و تغییر IP آنها را عوض نمیکند. باز کردن چند حساب برای دور زدن محدودیتها قوانین را نقض میکند؛ اگر بیشتر لازم دارید، به پلن بالاتر بروید.