Genesis Arbitrage

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

اولین درخواست 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 URLhttps://api.genesisarbitrage.com/v1سرور و نسخه API
مسیر/funding/ratesendpoint نرخ‌های فاندینگ
پارامترها?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کلید وجود ندارد، نامعتبر یا ابطال‌شده است یا اشتراک تمام شدههدر و اشتراک را بررسی کنید
403endpoint در تعرفه شما نیست (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"
  }
}

این پاسخ را این‌طور بخوانید:

همه فیلدها در بخش نرخ‌های فاندینگ مستندات هستند. بلوک بعدی اسکریپت را ادامه می‌دهد: 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 یا بدون /v1404مسیر را با مستندات مقایسه کنید
غلط تایپی در نام پارامتر: coins=BTC200 و همه ارزها: پارامتر ناشناخته نادیده گرفته می‌شودmeta.count را ببینید: با coin=BTC برابر 1 است
ویرگول اعشاری: min_spread=0,5200 بدون اعمال فیلتراز نقطه استفاده کنید: 0.5
جفت به‌جای نماد: coin=BTCUSDT200، data خالی و meta.count برابر 0از نماد ارز استفاده کنید: BTC

غلط تایپی در پارامتر موذی‌ترین آن‌هاست: خطایی در کار نیست، اما اسکریپت به‌جای یک ارز کل داده را می‌گیرد و یک فراخوانی برایش خرج می‌کند. بعد از افزودن یک فیلتر جدید، meta.count را با مقدار مورد انتظار مقایسه کنید.

خودتان امتحان کنید

  1. درخواست را بدون کلید بفرستید

    curl -i "https://api.genesisarbitrage.com/v1/account/usage" کد 401 را با invalid_key و "Missing X-API-Key header." در بدنه برمی‌گرداند. x-request-id را میان هدرها پیدا کنید.

  2. با کلید تکرار کنید

    متغیر را با read -s تنظیم کنید و درخواست بخش /account/usage را بفرستید. 200 می‌گیرید و تعرفه شما در data.plan است.

  3. تاریخ صفر شدن را بررسی کنید

    اسکریپت Python را اجرا کنید و تاریخ صفر شدن سهمیه را با خط «resets …» در بلوک «Genesis API» پروفایل خود مقایسه کنید. گرفتن کلید گام‌به‌گام در شروع سریع Genesis API آمده است.

  4. بالاترین نرخ را پیدا کنید

    بلوک دوم را به اسکریپت اضافه کنید و صرافی با بیشترین funding_8h_pct را پیدا کنید. funding_pct آن را دستی به 8 ساعت نرمال کنید: نرخ × 8 / فاصله به ساعت.

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

    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 را نشان می‌دهند.