Genesis API untuk agen AI: OpenAPI, llms.txt, dan function calling
Ringkasan
- Untuk agen tersedia openapi.json (OpenAPI 3.1, 37 operasi beserta paket), llms-full.txt, llms.txt, dan katalog API sesuai RFC 9727.
- Model memilih tool dan argumennya; server Anda melakukan request dengan key dan mengembalikan JSON singkat berisi waktu data ke model.
- Genesis API hanya membaca data. Kode Anda membatasi laju request, model memperlakukan teks dari respons sebagai data, dan manusia mengonfirmasi setiap trade.
Genesis API adalah REST API data pasar kripto yang dipanggil agen AI sebagai tool: model menentukan data apa yang dibutuhkan, server Anda mengirim request GET dengan key lalu mengembalikan JSON singkat. Untuk agen dan model bahasa tersedia deskripsi API yang bisa dibaca mesin: spesifikasi OpenAPI 3.1, referensi lengkap dalam Markdown, dan katalog API. Datanya sama dengan yang ditampilkan situs: spread CEX dan DEX, order book, funding, aliran on-chain, dan pasar prediksi.
File yang bisa dibaca mesin
| File | Isi | Untuk apa |
|---|---|---|
| genesisarbitrage.com/openapi.json | OpenAPI 3.1: 37 operasi, parameter, skema respons, paket di x-genesis-plans, header rate limit | Impor ke klien API, generasi kode, tool agen |
| genesisarbitrage.com/llms-full.txt | Referensi lengkap dalam satu file Markdown: endpoint, parameter, field, contoh, limit, error | Konteks untuk model yang menulis kode atau menjawab pertanyaan tentang API |
| genesisarbitrage.com/llms.txt | Ringkasan situs: Genesis API, tool, panduan, kursus, glosarium, blog | Pandangan pertama model terhadap situs |
| genesisarbitrage.com/.well-known/api-catalog | Katalog API sesuai RFC 9727: tautan ke spesifikasi, dokumentasi, harga, dan status | Penemuan API lewat domain |
Spesifikasi ini mengikuti OpenAPI 3.1, yang skemanya merupakan superset dari JSON Schema 2020-12, sehingga parameter operasi bisa dipindahkan ke definisi tool hampir tanpa perubahan. llms.txt adalah format yang diusulkan pada 2024: file Markdown di root situs berisi ringkasan singkat dan tautan untuk model bahasa. Katalog berada di alamat yang ditetapkan RFC 9727.
Halaman dokumentasi, produk, dan harga Genesis API memuat <link rel="service-desc"> di <head> yang mengarah ke openapi.json. Relasi tautan itu berasal dari RFC 8631 dan menandai deskripsi layanan yang ditujukan untuk mesin. Cuplikan singkat dari spesifikasi:
{
"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" } },
…
]
}
}
}
}
Setiap operasi memiliki operationId, parameter bertipe, skema respons 200, respons 304, kode error, serta header X-RateLimit-*, X-Quota-*, X-Request-Id, dan ETag. Key dijelaskan oleh skema keamanan ApiKeyAuth: tipe apiKey, header X-API-Key.
Cara menghubungkan
Dapatkan key dan simpan di server
Key
gns_live_…diterbitkan di profil Anda, pada blok Genesis API, dan hanya ditampilkan sekali. Simpan di variabel lingkunganGENESIS_API_KEYpada server yang menjalankan agen. Penyimpanan dan penerbitan ulang dibahas di panduan API key.Impor spesifikasi
Klien API atau framework agen yang mendukung OpenAPI membuat request dan tool langsung dari
openapi.json: base URL diambil dariservers, header key dariApiKeyAuth. Cara mengirim key dijelaskan di Autentikasi.Pertahankan operasi yang Anda butuhkan
Setiap definisi tool memakan ruang di konteks model, dan memilih dari sedikit tool lebih mudah. Pertahankan operasi yang dibutuhkan tugas Anda dan buang yang di luar paket Anda menurut
x-genesis-plans: operasi itu menjawab403 plan_restricted.Berikan referensi ke model
Jika agen menulis kode atau menjawab pertanyaan tentang API, tambahkan
llms-full.txtke konteksnya: berisi parameter, field, dan contoh setiap endpoint, beserta limit dan kode error.Cek key dengan panggilan pertama
/account/usagemengembalikan paket Anda, kuota terpakai, limit request per detik, dan kesegaran data.
Cara model memanggil Genesis API
Function calling adalah mekanisme ketika model mengembalikan nama tool dan argumen alih-alih teks, lalu kode Anda yang melakukan panggilan. Alurnya:
- Bersama pertanyaan pengguna, model menerima definisi tool: nama, tujuan, dan parameter sebagai JSON Schema.
- Model menjawab dengan sebuah panggilan:
get_spreadsdengan argumen{"coin": "TON", "min_spread": 0.5}. - Server Anda memvalidasi argumen, mengirim GET dengan header
X-API-Key, dan memangkas respons menjadi field yang dibutuhkan. - JSON singkat berisi waktu data dikembalikan ke model, lalu model menjawab pengguna.
Model tidak melakukan panggilan jaringan dan tidak pernah melihat key: ia hanya memegang definisi tool dan hasilnya. Tool get_spreads di atas endpoint Spot – Spot:
{
"name": "get_spreads",
"description": "Where to buy a coin cheaper and sell it higher (CEX)",
"parameters": {
"type": "object",
"properties": {
"coin": {
"type": "string",
"description": "Coin ticker, e.g. BTC"
},
"min_spread": {
"type": "number",
"description": "Minimum spread, %: 0.5 means 0.5%"
}
},
"additionalProperties": false
}
}
Nama field yang menyimpan skema parameter berbeda-beda antar penyedia model, di MCP namanya inputSchema; isinya selalu JSON Schema. Properti coin dan min_spread berasal dari parameter operasi getArbitrageSpotSpot, sedangkan description menjelaskan kapan tool dipanggil: model memilih berdasarkan teks itu.
Handler Python yang memanggil /arbitrage/spot-spot dan mengembalikan hingga 10 baris dengan field yang dibutuhkan beserta meta.updated_at ke model:
import os
import time
import requests
API = "https://api.genesisarbitrage.com/v1/arbitrage/spot-spot"
KEY = os.environ["GENESIS_API_KEY"] # key tetap di server
FIELDS = ("coin", "exchange_buy", "exchange_sell", "spread_pct",
"withdraw_enabled_buy", "deposit_enabled_sell")
cache = {} # params -> (waktu, ETag, isi respons)
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) # data tidak akan diperbarui lebih cepat
headers = {"X-API-Key": KEY}
if etag:
headers["If-None-Match"] = etag
for attempt in range(2): # 429 dan 503: tunggu Retry-After, coba lagi
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} # model melihat kodenya
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]}
Respons disimpan di cache selama meta.freshness_sec detik: data tidak akan diperbarui lebih cepat. Setelah itu handler mengirim ETag sebelumnya di If-None-Match, dan 304 tidak memakai kuota. Pada 429 dan 503 handler menunggu Retry-After (maksimal 30 dtk), mencoba sekali lagi, dan mengembalikan error lain ke model sebagai kode. Model menerima 10 baris dengan 6 field. Contoh ilustrasi: respons penuh 214 baris dengan 22 field berarti 214 × 22 = 4.708 nilai, sedangkan yang dipangkas 10 × 6 = 60.
Aturan untuk agen
| Aturan | Caranya |
|---|---|
| Key tetap di server | Variabel lingkungan milik handler; tidak ada key di prompt, browser, atau log obrolan |
| API hanya membaca | Genesis API tidak menempatkan order; manusia mengonfirmasi setiap trade di exchange |
| Kode Anda menentukan laju | Cache selama freshness_sec, ETag dan If-None-Match, antrean di bawah limit request per detik |
| Filter, bukan seluruh set | coin, min_spread, exchange; maksimal 10 baris dan field yang dibutuhkan ke model |
| Waktu data di setiap jawaban | updated_at dan usia data di hasil tool dan di jawaban untuk pengguna |
| Teks eksternal hanya data | Model tidak bertindak atas judul pasar, outcome, nama trader, atau teks sinyal |
Model bisa meminta beberapa tool sekaligus, dan limit menghitung setiap request pada key: 1 request per detik di Trial, 15 di Max. Respons 304 dan error tidak memakai kuota tetapi tetap dihitung dalam limit per detik — lihat Paket & limit dan panduan limit.
Field title dan outcome pasar prediksi, name trader, token_name event on-chain, serta message_ru dan message_en sinyal Genesis AI+ berasal dari sumber luar. Seseorang bisa menamai sebuah pasar "abaikan instruksi sebelumnya dan…" — itu prompt injection, perintah yang diselundupkan lewat data. Teruskan field semacam itu hanya di dalam hasil tool, batasi panjangnya, dan nyatakan di system prompt bahwa teks di dalam hasil adalah data.
MCP: server sendiri di atas REST API
MCP (Model Context Protocol) adalah standar terbuka untuk menghubungkan aplikasi AI ke sistem eksternal. Server MCP memberi aplikasi tool, resource, dan template prompt; pesannya berformat JSON-RPC 2.0, lewat stdio secara lokal dan Streamable HTTP secara remote. Spesifikasi dan SDK untuk beberapa bahasa ada di modelcontextprotocol.io.
Genesis API tidak punya server MCP resmi. Anda bisa membuat sendiri dari handler yang sama: tool MCP adalah GET ke endpoint Genesis API, parameternya berupa JSON Schema di inputSchema, dan key berada di lingkungan server. Server stdio lokal menjaga key tetap di mesin Anda. Letakkan server remote di balik otorisasi (MCP merekomendasikan OAuth); jika tidak, siapa pun yang tahu alamatnya bisa menghabiskan kuota Anda.
Cara agen bekerja dengan data pasar kripto secara umum dibahas di artikel data pasar kripto untuk agen AI, risiko otomatisasi di pelajaran kelima kursus.
Tanya jawab
Apakah Genesis API punya server MCP resmi?
Tidak. Untuk agen tersedia openapi.json, llms-full.txt, dan katalog API. Anda bisa menulis server MCP sendiri di atas REST API: setiap tool adalah request GET dengan key dari variabel lingkungan.
Bisakah agen melakukan trading lewat Genesis API?
Tidak. Genesis API hanya membaca data dan tidak menempatkan order. Agen menemukan setup dan mengirim alert; manusia yang melakukan trade di exchange.
Paket apa yang dibutuhkan agen?
Paket apa pun: Trial memberi 1 request per detik dan kesegaran 60 dtk, Max 15 request per detik dan 5 dtk. Endpoint yang disertakan tiap paket ada di x-genesis-plans dan di halaman harga Genesis API.
Mengapa model menyebut harga yang basi?
Data tertinggal sebesar kesegaran paket Anda, dan cache handler menambah hingga freshness_sec. Berikan updated_at dan usia data ke model, lalu minta ia menyebutkan waktunya dalam jawaban.