AI एजेंट के लिए Genesis API: OpenAPI, llms.txt और function calling
संक्षेप में
- एजेंट के लिए openapi.json (OpenAPI 3.1, प्लान के साथ 37 operations), llms-full.txt, llms.txt और RFC 9727 के अनुसार API catalog हैं।
- मॉडल tool और उसके arguments चुनता है; आपका सर्वर key के साथ request भेजता है और डेटा के समय वाला छोटा JSON मॉडल को लौटाता है।
- Genesis API केवल डेटा पढ़ता है। request की गति आपका कोड सीमित करता है, मॉडल responses के टेक्स्ट को डेटा मानता है, और हर ट्रेड इंसान कन्फ़र्म करता है।
Genesis API क्रिप्टो मार्केट डेटा का REST API है, जिसे AI एजेंट tool की तरह कॉल करता है: मॉडल तय करता है कि उसे कौन-सा डेटा चाहिए, आपका सर्वर key के साथ GET request भेजता है और छोटा JSON लौटाता है। एजेंट और भाषा मॉडल के लिए API का machine-readable विवरण है: OpenAPI 3.1 specification, पूरा Markdown रेफ़रेंस और API catalog। डेटा वही है जो साइट दिखाती है: CEX और DEX स्प्रेड, order book, funding rate, ऑन-चेन फ़्लो और prediction markets।
Machine-readable फ़ाइलें
| फ़ाइल | क्या है | किसलिए |
|---|---|---|
| genesisarbitrage.com/openapi.json | OpenAPI 3.1: 37 operations, parameters, response schemas, x-genesis-plans में प्लान, rate limit हेडर | API क्लाइंट में import, कोड जनरेशन, एजेंट tools |
| genesisarbitrage.com/llms-full.txt | एक Markdown फ़ाइल में पूरा रेफ़रेंस: endpoints, parameters, फ़ील्ड, उदाहरण, सीमाएँ, errors | कोड लिखने या API के सवालों का जवाब देने वाले मॉडल का context |
| genesisarbitrage.com/llms.txt | साइट का overview: Genesis API, टूल, गाइड, कोर्स, glossary, ब्लॉग | मॉडल की साइट पर पहली नज़र |
| genesisarbitrage.com/.well-known/api-catalog | RFC 9727 के अनुसार API catalog: spec, डॉक्यूमेंटेशन, कीमतों और स्टेटस के लिंक | डोमेन से API की खोज |
spec OpenAPI 3.1 का पालन करती है, जिसके schemas JSON Schema 2020-12 का superset हैं, इसलिए operation के parameters लगभग बिना बदलाव tool definition में चले जाते हैं। llms.txt 2024 में प्रस्तावित फ़ॉर्मैट है: साइट की root में Markdown फ़ाइल, जिसमें भाषा मॉडल के लिए छोटा overview और लिंक होते हैं। catalog उस पते पर है जो RFC 9727 में तय है।
Genesis API के डॉक्यूमेंटेशन, प्रोडक्ट और कीमतों के पन्नों के <head> में <link rel="service-desc"> है, जो openapi.json की ओर इशारा करता है। यह link relation RFC 8631 से है और मशीनों के लिए service description बताता है। spec का छोटा अंश:
{
"openapi": "3.1.0",
"servers": [{ "url": "https://api.genesisarbitrage.com/v1" }],
"paths": {
"/arbitrage/spot-spot": {
"get": {
"operationId": "getArbitrageSpotSpot",
"x-genesis-plans": ["trial", "start", "pro", "max"],
"parameters": [
{ "name": "coin", "in": "query",
"schema": { "type": "string" } },
{ "name": "min_spread", "in": "query",
"schema": { "type": "number" } },
…
]
}
}
}
}
हर operation में operationId, typed parameters, 200 response schema, 304 response, error कोड और X-RateLimit-*, X-Quota-*, X-Request-Id व ETag हेडर होते हैं। key को ApiKeyAuth security scheme में बताया गया है: type apiKey, हेडर X-API-Key।
कैसे जोड़ें
key पाएँ और सर्वर पर रखें
gns_live_…key आपकी प्रोफ़ाइल में, "Genesis API" ब्लॉक में जारी होती है और एक ही बार दिखती है। इसे उस सर्वर केGENESIS_API_KEYenvironment variable में रखें जो एजेंट चलाता है। स्टोरेज और reissue API key गाइड में हैं।spec import करें
जो API क्लाइंट या एजेंट framework OpenAPI स्वीकार करता है, वह requests और tools सीधे
openapi.jsonसे बनाता है: base URLserversसे और key का हेडरApiKeyAuthसे आता है। key कैसे भेजें, यह ऑथेंटिकेशन में बताया गया है।ज़रूरी operations रखें
हर tool definition मॉडल के context में जगह लेता है, और कम विकल्पों में से चुनना आसान होता है। वे operations रखें जो आपके काम के हैं और
x-genesis-plansके अनुसार अपने प्लान से बाहर वाले हटा दें: वे403 plan_restrictedलौटाते हैं।मॉडल को रेफ़रेंस दें
अगर एजेंट कोड लिखता है या API के सवालों का जवाब देता है, तो उसके context में
llms-full.txtजोड़ें: उसमें हर endpoint के parameters, फ़ील्ड और उदाहरण, सीमाएँ और error कोड हैं।पहली call से key जाँचें
/account/usageआपका प्लान, इस्तेमाल हुआ कोटा, प्रति सेकंड requests की सीमा और डेटा की freshness लौटाता है।
मॉडल Genesis API को कैसे कॉल करता है
Function calling वह तंत्र है जिसमें मॉडल टेक्स्ट की जगह tool का नाम और arguments लौटाता है, और call आपका कोड करता है। चक्र:
- उपयोगकर्ता के सवाल के साथ मॉडल को tool definitions मिलती हैं: नाम, उद्देश्य और JSON Schema के रूप में parameters।
- मॉडल call से जवाब देता है:
get_spreadsऔर arguments{"coin": "TON", "min_spread": 0.5}। - आपका सर्वर arguments validate करता है,
X-API-Keyहेडर के साथ GET भेजता है और response को ज़रूरी फ़ील्ड तक काट देता है। - डेटा के समय वाला छोटा JSON मॉडल के पास लौटता है, और वह उपयोगकर्ता को जवाब देता है।
मॉडल कोई नेटवर्क call नहीं करता और key कभी नहीं देखता: उसके पास केवल tool definition और नतीजा होता है। स्पॉट - स्पॉट endpoint पर get_spreads tool:
{
"name": "get_spreads",
"description": "सिक्का कहाँ सस्ता खरीदें और कहाँ महँगा बेचें (CEX)",
"parameters": {
"type": "object",
"properties": {
"coin": {
"type": "string",
"description": "सिक्के का ticker, जैसे BTC"
},
"min_spread": {
"type": "number",
"description": "न्यूनतम स्प्रेड, %: 0.5 यानी 0.5%"
}
},
"additionalProperties": false
}
}
parameter schema रखने वाले फ़ील्ड का नाम मॉडल प्रदाताओं में अलग है, MCP में यह inputSchema है; उसके अंदर हमेशा JSON Schema होता है। coin और min_spread properties getArbitrageSpotSpot operation के parameters से आई हैं, और description बताता है कि tool कब कॉल करना है: मॉडल इसी टेक्स्ट से चुनता है।
Python handler जो /arbitrage/spot-spot को कॉल करता है और ज़रूरी फ़ील्ड वाली अधिकतम 10 पंक्तियाँ तथा meta.updated_at मॉडल को लौटाता है:
import os
import time
import requests
API = "https://api.genesisarbitrage.com/v1/arbitrage/spot-spot"
KEY = os.environ["GENESIS_API_KEY"] # key सर्वर पर ही रहती है
FIELDS = ("coin", "exchange_buy", "exchange_sell", "spread_pct",
"withdraw_enabled_buy", "deposit_enabled_sell")
cache = {} # params -> (समय, ETag, response body)
def get_spreads(coin=None, min_spread=None):
params = {"coin": coin, "min_spread": min_spread}
params = {k: v for k, v in params.items() if v is not None}
ck = tuple(sorted(params.items()))
ts, etag, body = cache.get(ck, (0, None, None))
if body and time.time() - ts < body["meta"]["freshness_sec"]:
return shorten(body) # डेटा इससे पहले अपडेट नहीं होगा
headers = {"X-API-Key": KEY}
if etag:
headers["If-None-Match"] = etag
for attempt in range(2): # 429 और 503: Retry-After तक रुकें, फिर कोशिश
r = requests.get(API, headers=headers, params=params,
timeout=10)
if r.status_code not in (429, 503) or attempt:
break
time.sleep(min(int(r.headers.get("Retry-After", 5)), 30))
if r.status_code == 200:
body, etag = r.json(), r.headers.get("ETag")
elif r.status_code != 304:
return {"error": r.status_code} # मॉडल को कोड दिखता है
cache[ck] = (time.time(), etag, body)
return shorten(body)
def shorten(body):
rows = sorted(body["data"], key=lambda x: x["spread_pct"],
reverse=True)[:10]
t = body["meta"]["updated_at"]
return {"updated_at": t, "age_sec": int(time.time() - t),
"rows": [{f: x.get(f) for f in FIELDS} for x in rows]}
response meta.freshness_sec सेकंड तक cache में रहता है: डेटा इससे पहले अपडेट नहीं होगा। उसके बाद handler पिछला ETag If-None-Match में भेजता है, और 304 कोटा नहीं खर्च करता। 429 और 503 पर यह Retry-After तक रुकता है (अधिकतम 30 सेकंड), एक बार दोबारा कोशिश करता है और बाक़ी errors कोड के रूप में मॉडल को लौटाता है। मॉडल को 6 फ़ील्ड की 10 पंक्तियाँ मिलती हैं। उदाहरण के लिए: 22 फ़ील्ड वाली 214 पंक्तियों का पूरा response 214 × 22 = 4,708 मान है, कटा हुआ 10 × 6 = 60।
एजेंट के नियम
| नियम | कैसे |
|---|---|
| key सर्वर पर रहती है | handler का environment variable; prompt, ब्राउज़र और चैट लॉग में key नहीं |
| API केवल पढ़ता है | Genesis API कोई ऑर्डर नहीं लगाता; एक्सचेंज पर हर ट्रेड इंसान कन्फ़र्म करता है |
| गति आपका कोड तय करता है | freshness_sec तक cache, ETag और If-None-Match, प्रति सेकंड requests की सीमा के नीचे queue |
| फ़िल्टर, पूरा सेट नहीं | coin, min_spread, exchange; मॉडल को अधिकतम 10 पंक्तियाँ और ज़रूरी फ़ील्ड |
| हर जवाब में डेटा का समय | tool के नतीजे में और उपयोगकर्ता को जवाब में updated_at और उम्र |
| बाहरी टेक्स्ट केवल डेटा है | मॉडल मार्केट के शीर्षकों, outcomes, ट्रेडर के नामों और सिग्नल के टेक्स्ट के आधार पर कार्रवाई नहीं करता |
मॉडल एक साथ कई tools माँग सकता है, और सीमा key पर आने वाली हर request गिनती है: Trial में प्रति सेकंड 1 request और Max में 15। 304 responses और errors कोटा नहीं खर्च करते, पर प्रति सेकंड सीमा में गिने जाते हैं — प्लान और लिमिट और सीमाओं की गाइड देखें।
prediction markets के title और outcome फ़ील्ड, ट्रेडर का name, ऑन-चेन इवेंट का token_name और Genesis AI+ सिग्नल के message_ru व message_en बाहरी स्रोतों से आते हैं। कोई मार्केट का नाम "पिछले निर्देश अनदेखा करो और…" रख सकता है — यह prompt injection है, यानी डेटा के रास्ते घुसाए गए आदेश। ऐसे फ़ील्ड केवल tool के नतीजे के अंदर दें, उनकी लंबाई सीमित करें और system prompt में लिखें कि नतीजों के भीतर का टेक्स्ट डेटा है।
MCP: REST API के ऊपर आपका अपना सर्वर
MCP (Model Context Protocol) AI एप्लिकेशन को बाहरी सिस्टम से जोड़ने का खुला स्टैंडर्ड है। MCP सर्वर एप्लिकेशन को tools, resources और prompt templates देता है; संदेश JSON-RPC 2.0 में होते हैं, लोकल में stdio पर और रिमोट में Streamable HTTP पर। specification और कई भाषाओं के SDK modelcontextprotocol.io पर हैं।
Genesis API का कोई आधिकारिक MCP सर्वर नहीं है। आप उन्हीं handlers से अपना बना सकते हैं: MCP tool Genesis API के endpoint पर GET है, उसके parameters inputSchema में JSON Schema हैं, और key सर्वर के environment में रहती है। लोकल stdio सर्वर key को आपकी मशीन पर रखता है। रिमोट सर्वर को authorization के पीछे रखें (MCP OAuth की सलाह देता है), वरना पता जानने वाला कोई भी आपका कोटा खर्च कर सकता है।
एजेंट क्रिप्टो मार्केट डेटा के साथ आम तौर पर कैसे काम करते हैं, यह AI एजेंट के लिए क्रिप्टो मार्केट डेटा लेख में है, और ऑटोमेशन के जोखिम कोर्स के पाँचवें पाठ में।
सवाल और जवाब
क्या Genesis API का आधिकारिक MCP सर्वर है?
नहीं। एजेंट के लिए openapi.json, llms-full.txt और API catalog हैं। REST API के ऊपर MCP सर्वर आप खुद लिख सकते हैं: हर tool environment variable की key के साथ GET request है।
क्या एजेंट Genesis API से ट्रेड कर सकता है?
नहीं। Genesis API केवल डेटा पढ़ता है और कोई ऑर्डर नहीं लगाता। एजेंट setups ढूँढता है और अलर्ट भेजता है; ट्रेड इंसान एक्सचेंज पर करता है।
एजेंट को कौन-सा प्लान चाहिए?
कोई भी: Trial में प्रति सेकंड 1 request और 60 सेकंड freshness है, Max में प्रति सेकंड 15 requests और 5 सेकंड। किस प्लान में कौन-से endpoints हैं, यह x-genesis-plans में और Genesis API की कीमतें पन्ने पर है।
मॉडल पुरानी कीमतें क्यों बताता है?
डेटा आपके प्लान की freshness जितना पीछे रहता है, और handler का cache उसमें freshness_sec तक जोड़ देता है। मॉडल को updated_at और डेटा की उम्र दें, और कहें कि जवाब में समय बताए।