اولین درخواست API: HTTP، هدرها و JSON
به طور خلاصه
- درخواست HTTP به یک API از یک متد، یک آدرس ساختهشده از base URL، مسیر و پارامترها، و هدرها تشکیل میشود. کلید Genesis API فقط در هدر
X-API-Keyقرار میگیرد. - کد وضعیت گام بعدی را مشخص میکند:
200یعنی داده را بخوانید،304یعنی چیزی تغییر نکرده،401و403یعنی کلید و تعرفه را بررسی کنید،429و503یعنی بهاندازهRetry-Afterثانیه صبر کنید. - پاسخ Genesis API یک پوشش از
success،dataوmetaاست. درصدها به شکل عدد ساده میرسند (0.01یعنی 0.01%) و زمان به ثانیه unix است. - اشتباههای رایج مبتدیان: کلید در URL، متغیر محیطی خالی و غلط تایپی در مسیر یا نام پارامتر. غلط تایپی در پارامتر هیچ خطایی نمیدهد: بهجای داده فیلترشده کل داده را میگیرید.
برای فراخوانی یک API، برنامه شما یک درخواست HTTP شامل متد، آدرس و هدرها میفرستد و سرور یک کد وضعیت، هدرهای خودش و یک بدنه برمیگرداند که در Genesis API به شکل JSON است. درخواست را میتوانید با curl از ترمینال یا با کد در هر زبانی که کلاینت HTTP دارد بفرستید. اولین درخواست زیر کلید را با /account/usage بررسی میکند و دومی نرخهای فاندینگ BTC را از /funding/rates میگیرد. اینکه API چیست و با آن چه چیزهایی را میتوان خودکار کرد در درس 1 آمده است.
ساختار یک درخواست
این درخواست نرخهای فاندینگ BTC است، همانطور که curl به سرور میفرستد و پرچم -v آن را در خطهای شروعشده با > نشان میدهد (کلید با یک نگهدار جایگزین شده است):
> GET /v1/funding/rates?coin=BTC HTTP/1.1
> Host: api.genesisarbitrage.com
> User-Agent: curl/8.7.1
> Accept: */*
> X-API-Key: gns_live_XXXXXXXXXXXXXXXX
| بخش | در مثال | معنا |
|---|---|---|
| متد | GET | خواندن داده؛ هر endpoint در Genesis API از نوع GET است |
| Base URL | https://api.genesisarbitrage.com/v1 | سرور و نسخه API |
| مسیر | /funding/rates | endpoint نرخهای فاندینگ |
| پارامترها | ?coin=BTC | فیلتر: فقط BTC |
| هدر | X-API-Key | کلیدی که سرور با آن حساب و تعرفه شما را شناسایی میکند |
پارامترها بعد از ? به شکل جفتهای name=value میآیند که با & به هم وصل میشوند: ?coin=BTC&exchange=Binance,OKX. فیلترهای Genesis API اختیاریاند، پس بدون coin همین endpoint همه ارزها را برمیگرداند. اعداد اعشاری با نقطه نوشته میشوند، نه با ویرگول: min_spread=0.5.
هدرها خطهایی به شکل name: value هستند که همراه آدرس میروند. نام هدرها به بزرگی و کوچکی حروف حساس نیست (RFC 9110، بخش 5.1): X-API-Key و x-api-key یک هدرند و x-request-id با حروف کوچک در خروجی curl همان X-Request-Id است. Genesis API کلید را فقط در X-API-Key میپذیرد.
کدهای وضعیت
خط اول پاسخ کد وضعیت را دارد و برنامه شما بر اساس آن تصمیم میگیرد چه کند:
| کد | معنا | چه کنید |
|---|---|---|
200 | درخواست انجام شد، داده در بدنه است | data و meta را بخوانید |
304 | داده از آخرین پاسخ شما تغییر نکرده | از داده قبلی استفاده کنید |
401 | کلید وجود ندارد، نامعتبر یا ابطالشده است یا اشتراک تمام شده | هدر و اشتراک را بررسی کنید |
403 | endpoint در تعرفه شما نیست (plan_restricted) | تعرفه را عوض کنید یا درخواست را کنار بگذارید |
429 | از حد درخواست، دانلود یا سهمیه گذشتهاید | Retry-After ثانیه صبر کنید |
503 | داده در حال بازسازی است (snapshot_not_ready) | بعد از Retry-After ثانیه دوباره تلاش کنید |
فقط 200 از سهمیه شما مصرف میکند: 304 و خطاها رایگاناند، اما در حد درخواست در ثانیه شمرده میشوند. 304 فقط به درخواستی برمیگردد که هدر If-None-Match دارد؛ این هدر و کدهای 400، 404، 410 و 500 در پاسخها و خطاهای Genesis API توضیح داده شدهاند. اینکه چرا تلاش دوباره بعد از 429 به مکث نیاز دارد، در مدخل واژهنامه HTTP 429 Too Many Requests آمده است.
اولین درخواست: /account/usage
/account/usage وضعیت کلید شما را نشان میدهد: تعرفه، سهمیه مصرفشده و محدودیتها. این endpoint در همه تعرفهها در دسترس است و یک فراخوانی مصرف نمیکند، برای همین اولین درخواست شما به آن میرود. ابتدا کلید را در یک متغیر محیطی بگذارید، بعد درخواست را بفرستید:
# کلید را بچسبانید و Enter بزنید: روی صفحه نمایش داده نمیشود
read -s GENESIS_API_KEY
export GENESIS_API_KEY
curl -i "https://api.genesisarbitrage.com/v1/account/usage" \
-H "X-API-Key: $GENESIS_API_KEY"
پرچم -i خط وضعیت و هدرها را پیش از بدنه چاپ میکند. بدنه پاسخ، یک نمونه توضیحی برای تعرفه Trial:
{
"success": true,
"data": {
"plan": "trial",
"calls_used": 0,
"calls_limit": 500000,
"rps_limit": 1,
"freshness_sec": 60,
"period_resets_at": 1796463000
},
"meta": {
"count": 1,
"updated_at": 1794730811,
"freshness_sec": 60,
"plan": "trial"
}
}
plan تعرفه شماست و calls_used از calls_limit مصرف سهمیه در دوره 30 روزه است. در مثال مقدار 0 است چون هنوز درخواست دیگری فرستاده نشده و خود /account/usage فراخوانی مصرف نمیکند. rps_limit تعداد درخواست در ثانیه است، freshness_sec هر چند ثانیه یکبار داده تعرفه شما بهروز میشود و period_resets_at زمان صفر شدن سهمیه است. فیلدها در بخش مصرف مستندات شرح داده شدهاند.
میان هدرها X-Request-Id را پیدا کنید، یعنی شناسه درخواست که بهجای کلید برای پشتیبانی میفرستید، و X-RateLimit-Remaining را، یعنی تعداد درخواستهای باقیمانده در پنجره فعلی محدودیت.
همین درخواست در Python
اسکریپتی برای Python 3.10+ با کتابخانه requests کلید را از همان متغیر محیطی میخواند:
import os
from datetime import datetime, timezone
import requests
BASE = "https://api.genesisarbitrage.com/v1"
key = os.environ["GENESIS_API_KEY"] # اگر تنظیم نشده باشد KeyError
r = requests.get(
BASE + "/account/usage",
headers={"X-API-Key": key},
timeout=10, # بدون timeout، requests ممکن است تا ابد منتظر بماند
)
body = r.json()
if r.status_code != 200 or not body.get("success"):
err = body.get("error") or {}
raise SystemExit(f"{r.status_code} {err.get('code')}")
usage = body["data"]
ts = usage["period_resets_at"]
resets = datetime.fromtimestamp(ts, timezone.utc)
print("plan:", usage["plan"])
print("calls:", usage["calls_used"], "of", usage["calls_limit"])
print("quota resets:", resets.strftime("%Y-%m-%d %H:%M UTC"))
print("X-Request-Id:", r.headers.get("X-Request-Id"))
os.environ["GENESIS_API_KEY"] اگر متغیر تنظیم نشده باشد اسکریپت را متوقف میکند، که بهتر از فرستادن درخواست بدون کلید و گرفتن 401 است. r.headers به بزرگی و کوچکی حروف حساس نیست، پس X-Request-Id حتی وقتی سرور x-request-id بفرستد پیدا میشود.
period_resets_at زمان unix است: تعداد ثانیهها از 1 ژانویه 1970، ساعت 00:00 UTC. datetime.fromtimestamp(ts, timezone.utc) آن را به تاریخ تبدیل میکند: 1796463000 برابر است با 5 دسامبر 2026، ساعت 09:30 UTC.
درخواست دوم: نرخهای فاندینگ BTC
فاندینگ پرداخت دورهای بین طرفهای لانگ و شورت در قرارداد آتی دائمی است و صرافیها آن را هر 8، 4 یا 1 ساعت تسویه میکنند. /funding/rates نرخها را در همه صرافیها برمیگرداند و پارامتر coin آن را به یک ارز محدود میکند. پاسخ GET /funding/rates?coin=BTC، یک نمونه توضیحی با دو صرافی از فهرست:
{
"success": true,
"data": [
{
"coin": "BTC",
"exchanges": [
{
"exchange": "Bitget",
"funding_pct": 0.01,
"funding_8h_pct": 0.01,
"next_payout": "00:00",
"interval": "8h",
"price": 96021.5,
"trade_url": "https://www.bitget.com/futures/usdt/BTCUSDT"
},
{
"exchange": "Hyper",
"funding_pct": 0.0013,
"funding_8h_pct": 0.0104,
"next_payout": null,
"interval": "1h",
"price": 96030.0,
"trade_url": "https://app.hyperliquid.xyz/trade/BTC"
},
…
]
}
],
"meta": {
"count": 1,
"updated_at": 1794675861,
"freshness_sec": 60,
"plan": "trial"
}
}
این پاسخ را اینطور بخوانید:
- پوشش:
successبرابرtrueاست، داده درdataقرار دارد و فیلدهای سرویسی درmeta؛meta.countتعداد آیتمهایdataاست، یعنی باcoin=BTCیک ارز، و درون آن آرایهexchangesقرار دارد؛ - درصدها به شکل عدد ساده میرسند:
"funding_pct": 0.01یعنی 0.01% در هر دوره، نه 1%؛ روی پوزیشن 10,000 دلاری، یک پرداخت با این نرخ برابر است با 10,000 × 0.01 / 100 = 1 دلار؛ funding_8h_pctنرخ را به 8 ساعت نرمال میکند تا صرافیهایی با دورههای متفاوت مستقیم قابل مقایسه باشند: Hyper هر ساعت تسویه میکند و 0.0013 × 8 = 0.0104% در هر 8 ساعت؛next_payoutزمان پرداخت بعدی به UTC و به شکل رشته "HH:MM" است وnullیعنی داده وجود ندارد، نه صفر؛meta.updated_atزمان unix ساخته شدن اسنپشات است: 1794675861 برابر است با 14 نوامبر 2026، ساعت 17:04:21 UTC؛ در Trial اسنپشات هر 60 ثانیه بهروز میشود.
همه فیلدها در بخش نرخهای فاندینگ مستندات هستند. بلوک بعدی اسکریپت را ادامه میدهد: BASE، key و importها از قبل در آن هستند.
r = requests.get(
BASE + "/funding/rates",
headers={"X-API-Key": key},
params={"coin": "BTC"}, # requests آدرس ?coin=BTC را میسازد
timeout=10,
)
r.raise_for_status() # روی 4xx و 5xx استثنا میاندازد
body = r.json()
if not body["data"]:
raise SystemExit("ارز در دادهها نیست: نماد را بررسی کنید")
ts = body["meta"]["updated_at"]
snap = datetime.fromtimestamp(ts, timezone.utc)
print("snapshot from", snap.strftime("%Y-%m-%d %H:%M:%S UTC"))
rows = body["data"][0]["exchanges"]
rows.sort(key=lambda e: e["funding_8h_pct"], reverse=True)
for e in rows:
print(f'{e["exchange"]:<8} {e["funding_pct"]:>7}% '
f'per {e["interval"] or "?"}, '
f'{e["funding_8h_pct"]:>7}% per 8h')
برای پاسخ نمونه، اسکریپت این را چاپ میکند:
snapshot from 2026-11-14 17:04:21 UTC
Hyper 0.0013% per 1h, 0.0104% per 8h
Bitget 0.01% per 8h, 0.01% per 8h
Hyper بالاتر از Bitget قرار میگیرد، با اینکه نرخ آن در هر دوره حدود 0.01 / 0.0013 ≈ 7.7 برابر کمتر است. بدون نرمالسازی به 8 ساعت، این مقایسه غلط درمیآید.
اشتباههای رایج مبتدیان
| اشتباه | پاسخ سرور | راه اصلاح |
|---|---|---|
کلید در URL: ?api_key=… | 401 و "Missing X-API-Key header." | کلید را فقط در هدر X-API-Key بفرستید |
| متغیر کلید خالی | 401 با همان متن: curl هدر خالی را حذف میکند | طول را بررسی کنید: echo ${#GENESIS_API_KEY} |
غلط تایپی در مسیر: /v1/funding/rate یا بدون /v1 | 404 | مسیر را با مستندات مقایسه کنید |
غلط تایپی در نام پارامتر: coins=BTC | 200 و همه ارزها: پارامتر ناشناخته نادیده گرفته میشود | meta.count را ببینید: با coin=BTC برابر 1 است |
ویرگول اعشاری: min_spread=0,5 | 200 بدون اعمال فیلتر | از نقطه استفاده کنید: 0.5 |
جفت بهجای نماد: coin=BTCUSDT | 200، data خالی و meta.count برابر 0 | از نماد ارز استفاده کنید: BTC |
غلط تایپی در پارامتر موذیترین آنهاست: خطایی در کار نیست، اما اسکریپت بهجای یک ارز کل داده را میگیرد و یک فراخوانی برایش خرج میکند. بعد از افزودن یک فیلتر جدید، meta.count را با مقدار مورد انتظار مقایسه کنید.
خودتان امتحان کنید
درخواست را بدون کلید بفرستید
curl -i "https://api.genesisarbitrage.com/v1/account/usage"کد401را باinvalid_keyو "Missing X-API-Key header." در بدنه برمیگرداند.x-request-idرا میان هدرها پیدا کنید.با کلید تکرار کنید
متغیر را با
read -sتنظیم کنید و درخواست بخش/account/usageرا بفرستید.200میگیرید و تعرفه شما درdata.planاست.تاریخ صفر شدن را بررسی کنید
اسکریپت Python را اجرا کنید و تاریخ صفر شدن سهمیه را با خط «resets …» در بلوک «Genesis API» پروفایل خود مقایسه کنید. گرفتن کلید گامبهگام در شروع سریع Genesis API آمده است.
بالاترین نرخ را پیدا کنید
بلوک دوم را به اسکریپت اضافه کنید و صرافی با بیشترین
funding_8h_pctرا پیدا کنید.funding_pctآن را دستی به 8 ساعت نرمال کنید: نرخ × 8 / فاصله به ساعت.درخواست را عمداً خراب کنید
coinرا بهcoinsتغییر دهید وmeta.countرا مقایسه کنید، بعدsرا از/funding/ratesحذف کنید و کد وضعیت را ببینید.
اینکه کدام endpointها به تصمیمهای مربوط به اسپردها، دفترهای سفارش و فاندینگ خدمت میکنند، موضوع درس 3 است.
پرسش و پاسخ
آیا میتوانم API را از مرورگر فراخوانی کنم؟
فقط آدرسهایی که کلید نمیخواهند: https://api.genesisarbitrage.com/health در مرورگر باز میشود و {"ok":true} نشان میدهد. نوار آدرس نمیتواند هدر X-API-Key اضافه کند، پس درخواستهای کلیددار از طریق curl، اسکریپت یا فرم «امتحان درخواست» در مستندات انجام میشوند. هرگز کلید را در کد وبسایت یا افزونه قرار ندهید: هر کس سورس صفحه را باز کند آن را میبیند.
پرچم -i در curl با -v چه فرقی دارد؟
-i خط وضعیت و هدرهای پاسخ را پیش از بدنه چاپ میکند. -v خود درخواست را هم نشان میدهد: خطهای با > آنچه به سرور رفته و خطهای با < آنچه برگشته است.
بدون Python چطور زمان unix را به تاریخ تبدیل کنم؟
در macOS دستور date -u -r 1796463000 و در Linux دستور date -u -d @1796463000 را اجرا کنید. برای این عدد هر دو 5 دسامبر 2026، ساعت 09:30 UTC را نشان میدهند.