Data pasar kripto untuk AI agent: API, function calling, MCP, dan llms.txt
Ringkasan
- Model bahasa hanya mengenal pasar sampai batas data pelatihannya. Harga, spread, dan funding rate terkini ia peroleh lewat tool: model memilih panggilan beserta argumennya, dan kode Anda yang mengirim request ke API.
- Tool di atas API data pasar sebaiknya sempit: satu endpoint, filter sebagai parameter, beberapa baris dengan field yang penting, dan waktu data di dalam hasilnya. Definisi tool berasal dari spesifikasi OpenAPI, dan MCP menyambungkan tool yang sama ke klien mana pun yang kompatibel.
- Key tetap di server Anda, teks dari data eksternal sampai ke model hanya di dalam hasil tool, dan setiap transaksi dikonfirmasi manusia. Genesis API bersifat read-only dan menerbitkan openapi.json, llms-full.txt, serta katalog API untuk agent.
AI agent memperoleh data pasar kripto lewat tool: model menentukan data apa yang dibutuhkan, kode Anda memanggil API kripto dan mengembalikan JSON singkat berisi harga, spread, serta waktu data dibuat. Tool dihubungkan lewat function calling di API model atau lewat server MCP, dan keduanya berjalan di atas REST API biasa.
Contoh di sini memakai Genesis API, REST API read-only dengan data CEX, DEX, on-chain, dan prediction market. Untuk API kripto secara umum dan cara membandingkannya, lihat API kripto: jenis API data pasar dan cara memilihnya.
Mengapa model tidak tahu harga terkini
Model bahasa dilatih dengan teks yang dikumpulkan hingga tanggal tertentu, yaitu knowledge cutoff. Ia tidak tahu apa pun tentang listing, rate, dan harga setelah tanggal itu, dan harga BTC yang disebut dari ingatan hanyalah angka dari teks pelatihan yang tanggalnya tidak jelas. Model juga tidak tahu waktu saat ini kecuali Anda menyertakannya di request.
Untuk arbitrase, jawaban dari ingatan tidak berguna: spread antar-exchange hanya bertahan beberapa menit, dan funding rate berubah setiap periode settlement, yaitu tiap 8, 4, atau 1 jam. Angka live hanya datang dari tool: dokumentasi API di konteks mengajarkan path dan parameter kepada model, tetapi tidak berisi harga.
| Yang dibutuhkan model | Sumbernya | Contoh |
|---|---|---|
| Path, parameter, dan field API | Dokumentasi di konteks | llms-full.txt, openapi.json |
| Harga, spread, rate | Panggilan tool | GET /funding/spread?coin=TON |
| Waktu saat ini dan usia data | System prompt dan hasil tool | updated_at, age_sec |
Cara kerja function calling
Function calling adalah mode saat model mengembalikan nama tool dan argumen, bukan teks, lalu kode Anda yang menjalankan request. Contoh ilustrasi: pengguna bertanya di mana spread funding terbesar untuk TON saat ini. Panggilan dan hasilnya, secara skematis:
{
"tool_call": {
"name": "get_funding",
"arguments": { "coin": "TON" }
},
"tool_result": {
"updated_at": 1794675860,
"age_sec": 12,
"rows": [
{
"coin": "TON",
"spread_pct": 0.04,
"pair": ["Bitget", "Bybit"],
"funding_pct": [0.05, 0.01],
"interval": ["8h", "8h"]
}
]
}
}
- Aplikasi mengirim pertanyaan dan definisi tool ke model: nama, tujuan, dan skema argumen dalam JSON Schema.
- Model mengembalikan panggilan
get_fundingdengan argumen{"coin": "TON"}. - Kode Anda memvalidasi argumen, mengirim
GET /funding/spread?coin=TONdengan headerX-API-Key, lalu meringkas responsnya. - Hasilnya dikembalikan ke model, yang menjawab: Bitget dan Bybit, 0,05% dan 0,01% per 8 jam, selisih 0,04%, data berusia 12 detik.
- Jika data belum cukup, model memanggil tool berikutnya.
Model tidak melakukan request jaringan dan tidak pernah melihat API key. Nama field bergantung pada API model: di Claude API skema berada di input_schema, panggilan datang sebagai blok tool_use dan hasilnya kembali sebagai blok tool_result, sedangkan MCP menamai skema itu inputSchema. Di kedua kasus, skemanya adalah JSON Schema.
Cara merancang tool di atas API data pasar
Satu tool, satu tugas
Model memilih tool berdasarkan deskripsinya, jadi tool yang sempit bekerja lebih andal daripada call_api(path, params) yang generik. Memilih dari lima sampai tujuh tool yang dibuat untuk tugas agent lebih mudah daripada memilih dari 37 operasi di spesifikasi.
| Tool | Endpoint Genesis API | Paket |
|---|---|---|
get_spreads | /arbitrage/spot-spot | Semua |
get_funding | /funding/spread | Semua |
get_prediction_arbs | /predictions/arbitrage | Start, Pro, Max |
get_book | /orderbooks/book | Pro, Max |
Deskripsi menyebutkan kapan tool dipanggil dan satuan angkanya: di Genesis API spread dan rate dinyatakan dalam persen, jadi 0.92 berarti 0,92%.
Filter sebagai parameter, validasi di kode
Filter API seperti coin, exchange, dan min_spread menjadi parameter tool. Model mengisinya dari pertanyaan, handler memeriksanya terhadap allowlist parameter, tipe, dan nilai, dan enum mendaftar nilai yang diizinkan: untuk /orderbooks/book, market hanya spot atau futures. Model tidak pernah menyusun path request, dan skema menolak field tambahan (additionalProperties: false).
Respons yang difilter datang tanpa ETag, sehingga setiap polling berfilter yang berulang memakan satu panggilan: tidak ada 304 gratis. Jika agent membutuhkan puluhan coin, lebih murah menyimpan dataset penuh tanpa filter secara lokal dan mem-poll-nya dengan If-None-Match.
Hasil yang ringkas
Contoh ilustrasi: respons /funding/spread penuh tanpa filter mencakup 1.000 coin. Untuk coin di 10 exchange, satu baris berisi 2 + 10 + 8 × 5 = 52 nilai: coin, spread, 10 field pasangan terbaik di best, dan 5 field untuk masing-masing 8 exchange lain di others. Seluruh respons berisi 1.000 × 52 = 52.000 nilai, sedangkan jawaban tentang pasangan terbaik hanya membutuhkan 5 baris berisi 8 nilai: 5 × 8 = 40.
Definisi dan hasil tool masuk ke konteks di setiap langkah: Claude API menagihnya sebagai token input.
Waktu data dan kesegaran
Handler memasukkan updated_at, yaitu waktu pembuatan data dari meta.updated_at dalam detik unix, dan age_sec ke dalam hasil. Dengan begitu model bisa mengatakan "data berusia 12 detik" alih-alih menyajikan spread kemarin sebagai data terkini.
Kesegaran data ditentukan paket: meta.freshness_sec berkisar dari 60 dtk di Trial sampai 5 dtk di Max. Sebelum interval itu lewat, API mengembalikan snapshot yang sama, sehingga handler meng-cache respons selama freshness_sec detik. Order book punya jam sendiri: book_ts, age_sec, dan flag stale untuk book yang lebih tua dari 30 dtk.
Contoh: tool get_funding
Definisi di bawah memakai format MCP; untuk Claude API isi yang sama masuk ke input_schema. Handler menerapkan limit sendiri: API tidak punya parameter itu.
{
"name": "get_funding",
"description": "Where funding is higher or lower: best exchange pair",
"inputSchema": {
"type": "object",
"properties": {
"coin": {
"type": "string",
"description": "Coin ticker, e.g. TON"
},
"min_spread": {
"type": "number",
"minimum": 0,
"description": "Minimum spread, %: 0.05 means 0.05%"
},
"limit": {
"type": "integer",
"minimum": 1,
"maximum": 10,
"description": "How many rows to return, 5 by default"
}
},
"additionalProperties": false
}
}
Handler Python: cache selama freshness_sec, satu jeda singkat saat 429 dan 503, log tanpa key, dan hasil ringkas dengan waktu data.
import logging
import os
import time
import requests
URL = "https://api.genesisarbitrage.com/v1/funding/spread"
KEY = os.environ["GENESIS_API_KEY"] # key tetap di server
cache = {} # parameter request -> (waktu diterima, isi respons)
def get_funding(coin=None, min_spread=None, limit=5):
p = {"coin": coin and coin.upper(), "min_spread": min_spread}
p = {k: v for k, v in p.items() if v}
ck = tuple(sorted(p.items()))
got, body = cache.get(ck, (0, None))
if not body or time.time() - got >= body["meta"]["freshness_sec"]:
for attempt in range(2): # 429, 503: tunggu sebentar, satu kali coba ulang
r = requests.get(URL, params=p, timeout=10,
headers={"X-API-Key": KEY})
wait = int(r.headers.get("Retry-After", "0"))
if attempt or wait > 5 or r.status_code not in (429, 503):
break
time.sleep(wait)
logging.info("get_funding %s -> %s id=%s", p, r.status_code,
r.headers.get("X-Request-Id")) # tanpa key di log
if r.status_code != 200:
return {"error": r.status_code} # 401, 403, 429, 503
body = r.json()
cache[ck] = (time.time(), body)
t = body["meta"]["updated_at"]
top = sorted(body["data"], key=lambda x: -x["spread_pct"])
rows = [{"coin": x["coin"], "spread_pct": x["spread_pct"],
"pair": [x["best"]["exchange_1"], x["best"]["exchange_2"]],
"funding_pct": [x["best"]["funding_1_pct"],
x["best"]["funding_2_pct"]],
"interval": [x["best"]["interval_1"],
x["best"]["interval_2"]]}
for x in top[:min(max(int(limit), 1), 10)]]
return {"updated_at": t, "age_sec": int(time.time() - t),
"rows": rows}
Handler tidak menunggu jeda yang lebih dari 5 detik: setelah kuota habis, Retry-After menunjuk ke waktu reset yang bisa berhari-hari lagi. Model menerima kode status dan menjelaskan kepada pengguna apa yang terjadi: 403 berarti plan_restricted, endpoint di luar paket (error Genesis API).
OpenAPI sebagai sumber definisi tool
OpenAPI adalah standar deskripsi API HTTP yang dapat dibaca mesin: sebuah operasi dijelaskan dengan operationId, summary singkat, dan parameter beserta skemanya. Di versi 3.1, Schema Object adalah superset dari JSON Schema 2020-12 (spesifikasi OpenAPI 3.1), dan MCP membaca inputSchema sebagai JSON Schema 2020-12 secara default. Jadi parameter berpindah ke tool tanpa konversi.
Skrip ini membangun tool dari spesifikasi Genesis API: mengambil operasi yang Anda inginkan, melewati yang di luar paket Anda berdasarkan x-genesis-plans, dan membawa parameter query serta path. Header adalah tugas handler.
import requests
SPEC = "https://genesisarbitrage.com/openapi.json"
def tools_from_spec(wanted, plan):
"""wanted: operationId -> nama tool; plan: trial … max."""
spec = requests.get(SPEC, timeout=15).json()
tools, routes = [], {}
for path, item in spec["paths"].items():
op = item.get("get", {})
name = wanted.get(op.get("operationId"))
if not name or plan not in op.get("x-genesis-plans", []):
continue # tidak diinginkan atau di luar paket: 403 plan_restricted
props, required = {}, []
for prm in op.get("parameters", []):
if "$ref" in prm or prm["in"] not in ("query", "path"):
continue # handler mengirim X-API-Key, If-None-Match
props[prm["name"]] = {**prm["schema"],
"description": prm["description"]}
if prm.get("required"):
required.append(prm["name"])
tools.append({
"name": name,
"description": op["description"].split("\n\n")[0],
"inputSchema": {"type": "object", "properties": props,
"required": required,
"additionalProperties": False}})
routes[name] = path # nama tool -> path endpoint
return tools, routes
tools, routes = tools_from_spec({"getFundingSpread": "get_funding",
"getArbitrageSpotSpot": "get_spreads"},
plan="trial")
getFundingSpread menjadi tool get_funding dengan parameter coin dan min_spread. Jika semua operasi diteruskan, Trial menyisakan 11 dari 37 operasi, dan Start menyisakan 16. Dict routes menyimpan path setiap tool.
MCP: server sendiri di atas REST API
MCP (Model Context Protocol) adalah standar terbuka untuk menghubungkan aplikasi AI dengan data dan tool. Anthropic merilisnya sebagai open source pada 25 November 2024 (pengumuman Anthropic) dan pada 9 Desember 2025 menyumbangkannya ke Agentic AI Foundation, yayasan di bawah Linux Foundation (blog MCP).
Aplikasi yang menjalankan model, yaitu host, membuat satu klien MCP untuk setiap server. Server menyediakan tool, resource, dan template prompt lewat JSON-RPC 2.0: server lokal lewat stdio, server remote lewat Streamable HTTP, yang untuknya MCP merekomendasikan pengambilan token lewat OAuth (arsitektur MCP).
| Function calling | MCP | |
|---|---|---|
| Tempat tool didefinisikan | Di request ke API model | Di server; klien mengambilnya dengan tools/list |
| Siapa yang menjalankan panggilan | Kode aplikasi Anda | Server MCP, pada request tools/call |
| Tempat berfungsi | Di aplikasi tempat Anda menulis loop-nya | Di klien mana pun yang mendukung MCP |
Membungkus REST API dalam server MCP membutuhkan empat langkah:
Pilih operasinya
Ambil 3–7 operasi untuk tugas agent; susun nama tool, deskripsi, dan parameter dari OpenAPI, seperti pada skrip di atas.
Kembalikan daftar pada tools/list
Server mengembalikan
name,description, daninputSchemauntuk setiap tool.Tangani tools/call
Validasi argumen, kirim request GET dengan key dari environment server, dan kembalikan JSON ringkas dalam blok
content. Kembalikan error API denganisError: true: model memakainya untuk memperbaiki argumennya.Pilih transport
Lewat stdio, server berjalan di mesin Anda dan key tidak pernah keluar darinya. Pasang server Streamable HTTP remote di balik otorisasi, atau siapa pun yang mengetahui URL-nya akan menghabiskan kuota Anda.
SDK MCP resmi tersedia untuk 10 bahasa, dari Python dan TypeScript sampai Go dan Rust (daftar SDK).
llms.txt dan llms-full.txt
llms.txt adalah file Markdown di /llms.txt yang membantu model bahasa memakai sebuah situs. Jeremy Howard mengusulkan formatnya pada 3 September 2024 (llmstxt.org): satu-satunya bagian wajib adalah H1 berisi nama, diikuti ringkasan dalam blockquote dan bagian-bagian berisi tautan ke versi Markdown halaman.
Usulan itu tidak mendefinisikan llms-full.txt: nama tersebut dipakai untuk seluruh dokumentasi dalam satu file Markdown, dan situs dokumentasi MCP, misalnya, menerbitkannya. Model tidak perlu mengikuti tautan, karena seluruh referensi masuk ke konteksnya.
Keamanan agent
Simpan key di environment variable di server: key tidak boleh muncul di prompt, browser, atau log. Key Genesis API bersifat read-only, jadi tidak bisa menempatkan order atau menarik dana, dan kebocoran hanya merugikan kuota Anda. Ganti key yang bocor dengan Terbitkan ulang di profil Anda (penyimpanan key).
Prompt injection adalah instruksi untuk model yang disembunyikan di dalam data. Nama token ditentukan oleh pihak yang men-deploy-nya dan nama trader oleh trader itu sendiri, sehingga sebuah field bisa berisi "abaikan instruksi sebelumnya". Di Genesis API, teks eksternal datang di field title dan outcome pada prediction market, name trader, token_name on-chain, serta message_ru dan message_en pada sinyal Genesis AI+: nyatakan di system prompt bahwa hasil tool hanyalah data.
Spesifikasi MCP mewajibkan server memvalidasi input tool, menerapkan rate limit pada pemanggilan, dan membersihkan output, serta menyarankan klien mengonfirmasi operasi sensitif dan mencatat penggunaan tool (tool MCP). Catat X-Request-Id di log: dengan itu, waktu dalam UTC, endpoint, dan status, tim dukungan dapat menemukan request.
Risiko otomatisasi dibahas di pelajaran 5 kursus API kripto.
Biaya dan limit
Hanya respons 200 yang memakai kuota Genesis API; 304 dan error gratis, tetapi dihitung dalam rate limit per detik. Jika limit terlampaui, server menjawab 429 dan tidak menagih apa pun.
| Paket | Harga | Kuota dan rate | Kesegaran |
|---|---|---|---|
| Trial | $20/bulan | 500.000 panggilan, 1 req/dtk | 60 dtk |
| Start | $50/bulan | 2 juta panggilan, 2 req/dtk | 30 dtk |
| Pro | $100/bulan | 5 juta panggilan, 5 req/dtk | 10 dtk |
| Max | $200/bulan | 10 juta panggilan, 15 req/dtk | 5 dtk |
Contoh ilustrasi: 500 pertanyaan per hari dengan masing-masing 3 panggilan tool berarti 500 × 3 = 1.500 panggilan per hari dan 1.500 × 30 = 45.000 dalam 30 hari, yaitu 9% dari kuota Trial. Cache menutup pengulangan dengan parameter sama dalam freshness_sec, dan batas jumlah panggilan tool per jawaban mencegah loop menghabiskan kuota.
Polling lebih sering daripada meta.freshness_sec tidak menghasilkan snapshot baru. Polling murah dengan ETag dan retry dibahas di Cara polling API kripto tanpa terkena limit, sedangkan limit dibahas di panduan limit Genesis API. Jika agent hanya butuh aturan dan tidak membutuhkan model, bot arbitrase kripto dengan Python lebih sederhana.
Genesis API untuk AI agent
Genesis API adalah REST API dengan data Genesis Arbitrage: spread CEX dan DEX, order book, funding, open interest, cross-chain, aliran on-chain, prediction market, surebet sportsbook, dan sinyal AI. Request berupa HTTP GET dengan header X-API-Key, responsnya JSON dengan data dan meta (format respons), dan SDK tidak diperlukan.
Yang diterbitkan untuk agent:
openapi.json— OpenAPI 3.1: 37 operasi, skema respons, dan paket dix-genesis-plans;llms-full.txt— referensi lengkap dalam satu file Markdown;llms.txt— ikhtisar situs untuk model bahasa;/.well-known/api-catalog— katalog RFC 9727 yang menautkan ke spesifikasi, dokumentasi, dan halaman status.
Tidak ada server MCP resmi, WebSocket, maupun endpoint trading: agent membaca data, dan transaksi tetap di tangan manusia. Panduan pengaturan langkah demi langkah ada di Genesis API untuk AI agent.
Tanya jawab
Bisakah AI agent melakukan trading kripto sendiri?
Hanya jika Anda memberinya API trading exchange, dan itu adalah kode serta risiko Anda sendiri. Tidak lewat Genesis API: ia hanya membaca data. Spesifikasi MCP menyatakan manusia harus selalu dapat menolak panggilan tool; untuk transaksi, jadikan aturan bahwa manusia mengonfirmasi setiap order.
Paket Genesis API mana yang dibutuhkan AI agent?
Trial seharga $20 per bulan mencakup spread CEX, funding, dan open interest. Start menambahkan saham, bagian on-chain, dan arbitrase prediksi dalam mode exact dan dutch, sedangkan Pro dan Max membuka semuanya, termasuk DEX dan order book. Kecepatan reaksi bergantung pada limit per detik dan kesegaran paket; isi setiap paket ada di halaman harga Genesis API.
Di mana saya mendapatkan spesifikasi Genesis API untuk agent?
OpenAPI 3.1 ada di genesisarbitrage.com/openapi.json, dan referensi untuk model ada di genesisarbitrage.com/llms-full.txt. Agent juga dapat menemukan keduanya lewat katalog /.well-known/api-catalog.
Apakah Genesis API punya server MCP?
Tidak ada yang resmi. Anda membangun sendiri dari handler yang sama: tool MCP adalah request GET ke sebuah endpoint dengan key dari environment server. Contoh Python minimal ada di entri glosarium MCP.