पहली 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 URL | https://api.genesisarbitrage.com/v1 | सर्वर और API का वर्शन |
| पाथ | /funding/rates | funding 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 | आपके पिछले रिस्पॉन्स के बाद डेटा नहीं बदला | पिछला डेटा दोबारा इस्तेमाल करें |
401 | key नहीं है, अमान्य है, रद्द है या सब्सक्रिप्शन ख़त्म है | हेडर और सब्सक्रिप्शन जांचें |
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 आपकी 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"
}
}
इस रिस्पॉन्स को ऐसे पढ़ें:
- लिफ़ाफ़ा:
successका मानtrueहै, डेटाdataमें है और सर्विस फ़ील्डmetaमें;meta.countdataमें आइटम की संख्या है, यानीcoin=BTCपर एक कॉइन, जिसके अंदरexchangesऐरे है; - प्रतिशत सादी संख्या में आते हैं:
"funding_pct": 0.01का मतलब प्रति अंतराल 0.01% है, 1% नहीं; 10,000 डॉलर की पोज़िशन पर इस rate का एक भुगतान 10,000 × 0.01 / 100 = 1 डॉलर होता है; funding_8h_pctrate को 8 घंटे पर सामान्य करता है ताकि अलग अंतराल वाले एक्सचेंज सीधे तुलना में आ सकें: Hyper हर घंटे निपटाता है, और 0.0013 × 8 = प्रति 8 घंटे 0.0104%;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 से ऊपर आता है, भले ही प्रति अंतराल उसका 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=BTC | 200 और सभी कॉइन: अनजान पैरामीटर अनदेखा हो जाता है | meta.count देखें: coin=BTC पर वह 1 होता है |
दशमलव कॉमा: min_spread=0,5 | 200, पर कोई फ़िल्टर लागू नहीं | बिंदु लगाएं: 0.5 |
टिकर की जगह पेयर: coin=BTCUSDT | 200, खाली data और meta.count 0 | कॉइन का टिकर लगाएं: BTC |
पैरामीटर का टाइपो इनमें सबसे चालाक है: कोई एरर नहीं आता, फिर भी स्क्रिप्ट को एक कॉइन की जगह पूरा डेटा मिलता है और उस पर एक कॉल खर्च होती है। नया फ़िल्टर जोड़ने के बाद meta.count की तुलना अपनी अपेक्षा से करें।
खुद आज़माएं
बिना key के रिक्वेस्ट भेजें
curl -i "https://api.genesisarbitrage.com/v1/account/usage"बॉडी मेंinvalid_keyऔर "Missing X-API-Key header." के साथ401लौटाता है। हेडर मेंx-request-idढूंढें।key के साथ दोहराएं
read -sसे वेरिएबल सेट करें और/account/usageसेक्शन की रिक्वेस्ट भेजें। आपको200मिलता है और आपका प्लानdata.planमें होता है।रीसेट की तारीख़ जांचें
Python स्क्रिप्ट चलाएं और कोटा रीसेट की तारीख़ को अपनी प्रोफ़ाइल के "Genesis API" ब्लॉक की "resets …" पंक्ति से मिलाएं। key पाने के चरण Genesis API क्विक स्टार्ट में हैं।
सबसे ऊंचा rate ढूंढें
स्क्रिप्ट में दूसरा ब्लॉक जोड़ें और सबसे ऊंचे
funding_8h_pctवाला एक्सचेंज ढूंढें। उसकाfunding_pctहाथ से 8 घंटे पर सामान्य करें: rate × 8 / घंटों में अंतराल।रिक्वेस्ट जानबूझकर बिगाड़ें
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 दिखाते हैं।