پاسخها و خطاهای 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"
}
}
| فیلد | نوع | محتوا |
|---|---|---|
success | boolean | true — درخواست موفق بود، false — خطا |
data | آرایه یا شیء | دادههای اندپوینت |
meta.count | int | تعداد آیتمها در data |
meta.updated_at | int | زمان یونیکس ساخت دادهها |
meta.freshness_sec | int | تأخیر ارائه برای پلن شما، به ثانیه |
meta.plan | string | پلن شما، در مثال pro |
استثنا تحلیل فاندینگ است: meta آن شامل count، updated_at و schema_version است و freshness_sec و plan ندارد. پوشش پاسخ در بخش قالب پاسخ مستندات توضیح داده شده و فیلدهای data در صفحه هر اندپوینت.
سه قرارداد برای همه اندپوینتها برقرار است:
- مقدار خالی
nullاست: مثلاًmax_position_usdدر DEX – Futures وقتی صرافی محدودیت حجم پوزیشن را اعلام نمیکندnullاست؛ - اسپردها و نرخها درصد هستند:
"spread_pct": 0.92یعنی 0.92%، نه 92%؛ - زمانها ثانیه یونیکس هستند:
1783802410برابر با 11 ژوئیه 2026، ساعت 20:40:10 UTC است؛ تاریخهایی که بهصورت رشته ارسال میشوند، مانندpool_created_atدر Cross-chain، در مستندات نوع رشته دارند.
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 نشانی جایگزین را.
| HTTP | error.code | معنا | چه کنیم |
|---|---|---|---|
400 | bad_request | پارامترهای درخواست نامعتبر، مثلاً volume=700 در /orderbooks/exec | پارامترها را طبق message اصلاح کنید: همان درخواست دوباره شکست میخورد |
401 | invalid_key | کلید وجود ندارد، نامعتبر یا لغوشده است، یا اشتراک API تمام شده | هدر X-API-Key و وضعیت اشتراک را در پروفایل بررسی کنید |
403 | plan_restricted | اندپوینت در پلن شما نیست | به پلنی که آن را دارد بروید یا درخواست را حذف کنید |
404 | not_found | اندپوینت یا منبع پیدا نشد: مجموعه داده، بخش، کوین، دفتر سفارش | مسیر و پارامترها را با مستندات مطابقت دهید |
410 | gone | اندپوینت بازنشسته شده است | به نشانی ذکرشده در message بروید |
429 | rate_limited | محدودیت درخواست در ثانیه رد شده، یا سهمیه دوره تمام شده | Retry-After ثانیه صبر و سرعت را کم کنید؛ اگر سهمیه تمام شده، منتظر بازنشانی بمانید یا پلن را ارتقا دهید |
429 | download_limited | حجم دانلود رد شده: 60 MB داده فشرده در هر 10 ثانیه برای هر کلید | Retry-After صبر کنید، ترافیک را با فیلترها، coin و If-None-Match کم کنید |
500 | internal_error | خطای داخلی | بعداً دوباره امتحان کنید؛ اگر ادامه یافت با X-Request-Id به پشتیبانی بنویسید |
503 | snapshot_not_ready | دادهها در حال بازسازی است یا منبع آن دوباره راهاندازی میشود | پس از Retry-After ثانیه دوباره امتحان کنید |
هدر Retry-After با 429 و 503 میآید و تعداد ثانیههای انتظار را دارد: معمولاً چند ثانیه، اما وقتی سهمیه دوره تمام شده باشد، زمان تا بازنشانی سهمیه است که میتواند چند روز باشد. خطاهای 4xx و 5xx سهمیه مصرف نمیکنند اما در محدودیت درخواست در ثانیه حساب میشوند، بنابراین تکرار زودهنگام به احتمال زیاد همان خطا را برمیگرداند. اصطلاحات فرهنگ لغت: HTTP 429 و rate limit.
X-Request-Id: چه چیزی برای پشتیبانی بفرستیم
هر پاسخ Genesis API، موفق یا ناموفق، هدر X-Request-Id با شناسه درخواست دارد. اگر خطایی تکرار میشود یا دادهها نادرست به نظر میرسند، اینها را برای پشتیبانی بفرستید:
- مقدار
X-Request-Id؛ - زمان درخواست به UTC؛
- اندپوینت با پارامترهایش، مثلاً
GET /arbitrage/spot-spot?coin=BTC؛ - وضعیت HTTP و
error.code.
کلید خود را نفرستید. اگر کلید در چت، لاگها یا کدی که دیگران میبینند افتاده، آن را در پروفایل خود دوباره صادر کنید: کلید قدیمی فوراً از کار میافتد.
ترتیب پردازش پاسخ
کد وضعیت را بررسی کنید
200—dataوmetaرا بخوانید و اگر ETag آمد ذخیره کنید.304— از دادههای پاسخ قبلی استفاده کنید.خطاهای موقت را مدیریت کنید
429و503با مکث کوتاه —Retry-Afterثانیه صبر کنید و دوباره امتحان کنید، حداکثر سه بار پشتسرهم.500— بعداً دوباره امتحان کنید.در خطاهای درخواست متوقف شوید
400،401،403،404،410و429با مکث چندساعته یا چندروزه — پارامترها، کلید یا پلن را اصلاح کنید یا منتظر بازنشانی سهمیه بمانید.سن دادهها را بررسی کنید
meta.updated_atرا با زمان فعلی مقایسه کنید: ربات که روی اسنپشات قدیمی عمل میکند اسپردهایی را میبیند که دیگر وجود ندارند.درخواست بعدی را زمانبندی کنید
زودتر از
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 برای آن کاربرد ندارد.