Genesis Arbitrage

Genesis Arbitrage · · 10 मिनट में पढ़ें

पहली API रिक्वेस्ट: HTTP, हेडर और JSON

संक्षेप में

  • API को भेजी गई HTTP रिक्वेस्ट में एक मेथड, base URL, पाथ और पैरामीटर से बना पता, और हेडर होते हैं। Genesis API key सिर्फ़ X-API-Key हेडर में जाती है।
  • स्टेटस कोड बताता है कि आगे क्या करना है: 200 का मतलब डेटा पढ़ें, 304 का मतलब कुछ नहीं बदला, 401 और 403 का मतलब key और प्लान जांचें, 429 और 503 का मतलब Retry-After सेकंड रुकें।
  • Genesis API का रिस्पॉन्स success, data और meta वाला लिफ़ाफ़ा है। प्रतिशत सादी संख्या में आते हैं (0.01 यानी 0.01%) और समय unix सेकंड में आता है।
  • शुरुआती लोगों की आम गलतियां: URL में key, खाली एनवायरनमेंट वेरिएबल, और पाथ या पैरामीटर के नाम में टाइपो। पैरामीटर का टाइपो कोई एरर नहीं देता: फ़िल्टर किए गए डेटा की जगह पूरा डेटा मिलता है।

API कॉल करने के लिए आपका प्रोग्राम मेथड, पते और हेडर वाली HTTP रिक्वेस्ट भेजता है, और सर्वर स्टेटस कोड, अपने हेडर और एक बॉडी लौटाता है, जो Genesis API में JSON होती है। रिक्वेस्ट टर्मिनल से curl के साथ या HTTP क्लाइंट वाली किसी भी भाषा के कोड से भेजी जा सकती है। नीचे की पहली रिक्वेस्ट /account/usage से key जांचती है, और दूसरी /funding/rates से BTC के funding rate लाती है। API क्या है और उससे क्या ऑटोमेट किया जा सकता है, यह पाठ 1 में है।

रिक्वेस्ट की बनावट

यह BTC के funding rate की रिक्वेस्ट है, जैसी curl सर्वर को भेजता है और -v फ़्लैग > से शुरू होने वाली पंक्तियों में दिखाता है (key की जगह प्लेसहोल्डर है):

> 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डेटा पढ़ना; Genesis API का हर endpoint GET है
Base URLhttps://api.genesisarbitrage.com/v1सर्वर और API का वर्शन
पाथ/funding/ratesfunding rate का endpoint
पैरामीटर?coin=BTCफ़िल्टर: सिर्फ़ BTC
हेडरX-API-Keyवह 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 एक ही हेडर हैं, और curl के आउटपुट में छोटे अक्षरों वाला x-request-id वही X-Request-Id है। Genesis API key सिर्फ़ X-API-Key में स्वीकार करता है।

स्टेटस कोड

रिस्पॉन्स की पहली पंक्ति में स्टेटस कोड होता है, और आपका प्रोग्राम उसी के आधार पर तय करता है कि आगे क्या करना है:

कोडमतलबक्या करें
200रिक्वेस्ट पूरी हुई, डेटा बॉडी में हैdata और meta पढ़ें
304आपके पिछले रिस्पॉन्स के बाद डेटा नहीं बदलापिछला डेटा दोबारा इस्तेमाल करें
401key नहीं है, अमान्य है, रद्द है या सब्सक्रिप्शन ख़त्म हैहेडर और सब्सक्रिप्शन जांचें
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 आपकी key की स्थिति दिखाता है: प्लान, इस्तेमाल हुआ कोटा और सीमाएं। यह हर प्लान में उपलब्ध है और कोई कॉल नहीं खर्चता, इसलिए आपकी पहली रिक्वेस्ट यहीं जाती है। पहले key को एनवायरनमेंट वेरिएबल में रखें, फिर रिक्वेस्ट भेजें:

# key चिपकाएं और 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_limit में से calls_used 30 दिन की अवधि का कोटा इस्तेमाल है। उदाहरण में 0 है क्योंकि अभी कोई और रिक्वेस्ट नहीं भेजी गई, और /account/usage खुद कोई कॉल नहीं खर्चता। rps_limit प्रति सेकंड रिक्वेस्ट है, freshness_sec बताता है कि आपके प्लान का डेटा कितने सेकंड में अपडेट होता है, और period_resets_at वह समय है जब कोटा रीसेट होता है। फ़ील्ड उपयोग डॉक्स सेक्शन में वर्णित हैं।

हेडर में X-Request-Id ढूंढें, जो रिक्वेस्ट की ID है और जिसे आप key की जगह सपोर्ट को भेजते हैं, और X-RateLimit-Remaining, जो मौजूदा रेट-लिमिट विंडो में बची रिक्वेस्ट की संख्या है।

वही रिक्वेस्ट Python में

requests लाइब्रेरी वाली Python 3.10+ की स्क्रिप्ट उसी एनवायरनमेंट वेरिएबल से key पढ़ती है:

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"] स्क्रिप्ट रोक देता है, जो बिना 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 के funding rate

Funding perpetual futures कॉन्ट्रैक्ट पर long और short के बीच होने वाला आवधिक भुगतान है, और एक्सचेंज इसे हर 8, 4 या 1 घंटे में निपटाते हैं। /funding/rates सभी एक्सचेंज के rate लौटाता है, और 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 से ऊपर आता है, भले ही प्रति अंतराल उसका rate 0.01 / 0.0013 ≈ 7.7 गुना कम है। 8 घंटे पर सामान्य किए बिना यह तुलना गलत निकलती है।

शुरुआती लोगों की आम गलतियां

गलतीसर्वर क्या लौटाता हैकैसे ठीक करें
URL में key: ?api_key=…401 और "Missing X-API-Key header."key सिर्फ़ X-API-Key हेडर में भेजें
key वाला वेरिएबल खालीउसी टेक्स्ट के साथ 401: curl खाली हेडर छोड़ देता हैलंबाई जांचें: echo ${#GENESIS_API_KEY}
पाथ में टाइपो: /v1/funding/rate या /v1 के बिना404पाथ को डॉक्स से मिलाएं
पैरामीटर के नाम में टाइपो: coins=BTC200 और सभी कॉइन: अनजान पैरामीटर अनदेखा हो जाता हैmeta.count देखें: coin=BTC पर वह 1 होता है
दशमलव कॉमा: min_spread=0,5200, पर कोई फ़िल्टर लागू नहींबिंदु लगाएं: 0.5
टिकर की जगह पेयर: coin=BTCUSDT200, खाली data और meta.count 0कॉइन का टिकर लगाएं: BTC

पैरामीटर का टाइपो इनमें सबसे चालाक है: कोई एरर नहीं आता, फिर भी स्क्रिप्ट को एक कॉइन की जगह पूरा डेटा मिलता है और उस पर एक कॉल खर्च होती है। नया फ़िल्टर जोड़ने के बाद meta.count की तुलना अपनी अपेक्षा से करें।

खुद आज़माएं

  1. बिना key के रिक्वेस्ट भेजें

    curl -i "https://api.genesisarbitrage.com/v1/account/usage" बॉडी में invalid_key और "Missing X-API-Key header." के साथ 401 लौटाता है। हेडर में x-request-id ढूंढें।

  2. key के साथ दोहराएं

    read -s से वेरिएबल सेट करें और /account/usage सेक्शन की रिक्वेस्ट भेजें। आपको 200 मिलता है और आपका प्लान data.plan में होता है।

  3. रीसेट की तारीख़ जांचें

    Python स्क्रिप्ट चलाएं और कोटा रीसेट की तारीख़ को अपनी प्रोफ़ाइल के "Genesis API" ब्लॉक की "resets …" पंक्ति से मिलाएं। key पाने के चरण Genesis API क्विक स्टार्ट में हैं।

  4. सबसे ऊंचा rate ढूंढें

    स्क्रिप्ट में दूसरा ब्लॉक जोड़ें और सबसे ऊंचे funding_8h_pct वाला एक्सचेंज ढूंढें। उसका funding_pct हाथ से 8 घंटे पर सामान्य करें: rate × 8 / घंटों में अंतराल।

  5. रिक्वेस्ट जानबूझकर बिगाड़ें

    coin को coins कर दें और meta.count की तुलना करें, फिर /funding/rates से s हटाएं और स्टेटस कोड देखें।

स्प्रेड, order book और funding पर फ़ैसलों के लिए कौन से endpoint काम आते हैं, यह पाठ 3 का विषय है।

सवाल और जवाब

क्या मैं API को ब्राउज़र से कॉल कर सकता हूं?

सिर्फ़ वे पते जिन्हें key नहीं चाहिए: https://api.genesisarbitrage.com/health ब्राउज़र में खुलता है और {"ok":true} दिखाता है। एड्रेस बार X-API-Key हेडर नहीं जोड़ सकता, इसलिए key वाली रिक्वेस्ट curl, स्क्रिप्ट या डॉक्स के "आज़माएं" फ़ॉर्म से जाती हैं। key को कभी वेबसाइट या एक्सटेंशन के कोड में न डालें: पेज का सोर्स खोलने वाला कोई भी उसे देख लेगा।

curl में -i और -v में क्या फ़र्क है?

-i बॉडी से पहले स्टेटस लाइन और रिस्पॉन्स हेडर छापता है। -v रिक्वेस्ट भी दिखाता है: > वाली पंक्तियां वह हैं जो सर्वर को गया, और < वाली वह जो लौटा।

Python के बिना unix समय को तारीख़ में कैसे बदलूं?

macOS पर date -u -r 1796463000 चलाएं; Linux पर date -u -d @1796463000। इस संख्या के लिए दोनों 5 दिसंबर 2026, 09:30 UTC दिखाते हैं।