Yapay zekâ ajanları için kripto piyasa verisi: API, fonksiyon çağırma, MCP ve llms.txt
Kısaca
- Dil modeli piyasayı yalnızca eğitim verisinin kesim tarihine kadar bilir. Güncel fiyat, spread ve fonlama oranını araçlar üzerinden alır: çağrıyı ve argümanlarını model seçer, API isteğini sizin kodunuz yapar.
- Piyasa verisi API'sinin üzerindeki araç dar olmalıdır: tek endpoint, parametre olarak filtreler, önemli alanları içeren birkaç satır ve sonuçta verinin zaman damgası. Araç tanımları OpenAPI spesifikasyonundan gelir, MCP ise aynı araçları uyumlu her istemciye bağlar.
- Anahtar sunucunuzda kalır, dış verideki metin modele yalnızca araç sonuçlarının içinde ulaşır ve her işlemi bir insan onaylar. Genesis API salt okunurdur ve ajanlar için openapi.json, llms-full.txt ile bir API kataloğu yayımlar.
Yapay zekâ ajanı kripto piyasa verisini araçlar üzerinden alır: model hangi veriye ihtiyaç duyduğuna karar verir, sizin kodunuz bir kripto API'sini çağırır ve fiyatları, spreadleri ile verinin oluşturulma zamanını içeren kısa bir JSON döndürür. Araçlar ya modelin API'sindeki fonksiyon çağırma ya da bir MCP sunucusu aracılığıyla bağlanır; ikisi de sıradan bir REST API'nin üzerinde çalışır.
Örneklerde, CEX, DEX, zincir üstü ve tahmin piyasası verilerini sunan salt okunur bir REST API olan Genesis API kullanılıyor. Kripto API'leri ve nasıl karşılaştırılacakları için bkz. Kripto API: piyasa verisi API türleri ve seçim.
Model neden güncel fiyatları bilmez
Dil modeli, belirli bir tarihe, yani bilgi kesim tarihine kadar toplanan metinlerle eğitilir. Bu tarihten sonraki listelemeler, oranlar ve fiyatlar hakkında hiçbir şey bilmez; hafızadan aktarılan bir BTC fiyatı, tarihi belirsiz bir eğitim metninden gelen bir sayıdır. İstekte iletmediğiniz sürece model güncel saati de bilmez.
Arbitraj için hafızadan verilen cevap işe yaramaz: borsalar arasındaki spread dakikalarca yaşar, fonlama oranı ise her uzlaşma döneminde, yani 8, 4 veya 1 saatte bir değişir. Canlı sayılar yalnızca bir araçtan gelir: bağlamdaki API dokümanı modele yolları ve parametreleri öğretir, ama fiyat içermez.
| Modelin ihtiyacı | Nereden gelir | Örnek |
|---|---|---|
| API yolları, parametreler ve alanlar | Bağlamdaki doküman | llms-full.txt, openapi.json |
| Fiyatlar, spreadler, oranlar | Araç çağrısı | GET /funding/spread?coin=TON |
| Güncel saat ve verinin yaşı | Sistem istemi ve araç sonucu | updated_at, age_sec |
Fonksiyon çağırma nasıl çalışır
Fonksiyon çağırma, modelin metin yerine bir araç adı ve argümanlar döndürdüğü, isteği ise kodunuzun çalıştırdığı moddur. Açıklayıcı örnek: kullanıcı, TON için şu anda en büyük fonlama spread'inin nerede olduğunu soruyor. Çağrı ve sonuç, şematik olarak:
{
"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"]
}
]
}
}
- Uygulama modele soruyu ve araç tanımlarını gönderir: ad, amaç ve JSON Schema ile yazılmış bir argüman şeması.
- Model,
{"coin": "TON"}argümanlarıyla birget_fundingçağrısı döndürür. - Kodunuz argümanları doğrular,
X-API-KeybaşlığıylaGET /funding/spread?coin=TONisteğini gönderir ve yanıtı kısaltır. - Sonuç modele geri gider; model şöyle yanıtlar: Bitget ve Bybit, 8 saat için %0,05 ve %0,01, fark %0,04, veri 12 saniyelik.
- Veri yetmezse model bir sonraki aracı çağırır.
Model ağ isteği yapmaz ve API anahtarını hiçbir zaman görmez. Alan adları modelin API'sine bağlıdır: Claude API'de şema input_schema içinde durur, çağrı tool_use bloğu olarak gelir ve sonuç tool_result bloğu olarak geri döner; MCP ise şemaya inputSchema der. Her iki durumda da şema JSON Schema'dır.
Piyasa verisi API'sinin üzerinde araçlar nasıl tasarlanır
Bir araç, bir iş
Model aracı açıklamasına göre seçer, bu yüzden dar araçlar genel bir call_api(path, params) aracından daha güvenilir çalışır. Ajanın görevleri için hazırlanmış beş ila yedi araç arasından seçmek, spesifikasyondaki 37 operasyon arasından seçmekten kolaydır.
| Araç | Genesis API endpoint'i | Planlar |
|---|---|---|
get_spreads | /arbitrage/spot-spot | Tümü |
get_funding | /funding/spread | Tümü |
get_prediction_arbs | /predictions/arbitrage | Start, Pro, Max |
get_book | /orderbooks/book | Pro, Max |
Açıklama, aracın ne zaman çağrılacağını ve sayıların hangi birimde olduğunu söyler: Genesis API'de spread ve oranlar yüzde cinsindendir, yani 0.92 %0,92 demektir.
Filtreler parametre olarak, doğrulama kodda
coin, exchange ve min_spread gibi API filtreleri araç parametrelerine dönüşür. Model bunları sorudan doldurur, işleyici ise parametreleri, türleri ve değerleri izin listesine göre kontrol eder; enum izin verilen değerleri listeler: /orderbooks/book için market yalnızca spot veya futures olabilir. Model istek yolunu hiçbir zaman kendisi oluşturmaz, şema da fazla alanları reddeder (additionalProperties: false).
Filtrelenmiş yanıt ETag olmadan gelir; bu yüzden filtreli her tekrar sorgusu bir çağrıya mal olur: ücretsiz 304 yoktur. Ajanın onlarca coine ihtiyacı varsa, filtresiz tam veri setini yerelde tutup If-None-Match ile sorgulamak daha ucuzdur.
Kompakt sonuçlar
Açıklayıcı örnek: filtresiz tam /funding/spread yanıtı 1.000 coini kapsar. 10 borsadaki bir coin için bir satırda 2 + 10 + 8 × 5 = 52 değer bulunur: coin, spread, best içinde en iyi çiftin 10 alanı ve others içinde diğer 8 borsanın her biri için 5 alan. Yanıtın tamamı 1.000 × 52 = 52.000 değerdir; en iyi çiftlerle ilgili bir cevap ise 8 değerlik 5 satır gerektirir: 5 × 8 = 40.
Araç tanımları ve sonuçları her adımda bağlama girer: Claude API bunları girdi token'ı olarak faturalandırır.
Verinin zamanı ve tazeliği
İşleyici, sonuca updated_at (meta.updated_at içindeki verinin oluşturulma zamanı, unix saniyesi) ve age_sec değerlerini koyar. Böylece model, dünkü spread'i güncelmiş gibi sunmak yerine "veri 12 saniyelik" diyebilir.
Veri tazeliğini plan belirler: meta.freshness_sec Trial'da 60 sn'den Max'te 5 sn'ye kadar değişir. Bu süre dolmadan API aynı anlık görüntüyü döndürür; bu yüzden işleyici yanıtı freshness_sec saniye boyunca önbellekte tutar. Emir defterlerinin kendi saati vardır: book_ts, age_sec ve 30 saniyeden eski defterler için bir stale bayrağı.
Örnek: get_funding aracı
Aşağıdaki tanım MCP biçimindedir; Claude API için aynı içerik input_schema içine girer. limit değerini işleyici kendisi uygular: API'de böyle bir parametre yoktur.
{
"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
}
}
Python işleyicisi: freshness_sec için önbellek, 429 ve 503 durumunda tek bir kısa bekleme, anahtarsız günlük ve veri zamanı içeren kompakt bir sonuç.
import logging
import os
import time
import requests
URL = "https://api.genesisarbitrage.com/v1/funding/spread"
KEY = os.environ["GENESIS_API_KEY"] # anahtar sunucuda kalır
cache = {} # istek parametreleri -> (alınma zamanı, yanıt gövdesi)
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: kısa bekleme, bir tekrar
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")) # günlükte anahtar yok
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}
İşleyici 5 saniyeden uzun beklemeleri beklemez: kota bittiğinde Retry-After sıfırlanmaya işaret eder ve bu günler sonra olabilir. Model durum kodunu alır ve kullanıcıya ne olduğunu söyler: 403, plan_restricted demektir, yani endpoint plan dışındadır (Genesis API hataları).
Araç tanımlarının kaynağı olarak OpenAPI
OpenAPI, HTTP API'lerinin makine tarafından okunabilir tanımı için bir standarttır: bir operasyon operationId, kısa bir summary ve şemalı parametrelerle tanımlanır. 3.1 sürümünde Schema Object, JSON Schema 2020-12'nin bir üst kümesidir (OpenAPI 3.1 spesifikasyonu), MCP de inputSchema değerini varsayılan olarak JSON Schema 2020-12 diye okur. Bu yüzden parametreler dönüştürme olmadan araca geçer.
Betik, Genesis API spesifikasyonundan araçlar üretir: istediğiniz operasyonları alır, planınızın dışında kalanları x-genesis-plans ile atlar ve query ile path parametrelerini aktarır. Başlıklar işleyicinin işidir.
import requests
SPEC = "https://genesisarbitrage.com/openapi.json"
def tools_from_spec(wanted, plan):
"""wanted: operationId -> araç adı; 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 # istenmeyen veya plan dışı: 403 plan_restricted
props, required = {}, []
for prm in op.get("parameters", []):
if "$ref" in prm or prm["in"] not in ("query", "path"):
continue # işleyici X-API-Key ve If-None-Match gönderir
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 # araç adı -> endpoint yolu
return tools, routes
tools, routes = tools_from_spec({"getFundingSpread": "get_funding",
"getArbitrageSpotSpot": "get_spreads"},
plan="trial")
getFundingSpread, coin ve min_spread parametreli bir get_funding aracına dönüşür. Her operasyonu geçirirseniz Trial 37 operasyondan 11'ini, Start 16'sını tutar. routes sözlüğü her aracın yolunu saklar.
MCP: REST API'nin üzerinde kendi sunucunuz
MCP (Model Context Protocol), yapay zekâ uygulamalarını veri ve araçlara bağlamak için açık bir standarttır. Anthropic onu 25 Kasım 2024'te açık kaynak yaptı (Anthropic duyurusu) ve 9 Aralık 2025'te Linux Foundation bünyesindeki bir vakıf olan Agentic AI Foundation'a bağışladı (MCP blogu).
Modelin bulunduğu uygulama, yani host, her sunucu için bir MCP istemcisi oluşturur. Sunucu araçları, kaynakları ve istem şablonlarını JSON-RPC 2.0 üzerinden sunar: yerel sunucu stdio, uzak sunucu Streamable HTTP üzerinden; uzak sunucu için MCP, token'ların OAuth ile alınmasını önerir (MCP mimarisi).
| Fonksiyon çağırma | MCP | |
|---|---|---|
| Araçlar nerede tanımlanır | Model API'sine giden istekte | Sunucuda; istemci bunları tools/list ile alır |
| Çağrıyı kim çalıştırır | Uygulama kodunuz | MCP sunucusu, tools/call isteğinde |
| Nerede çalışır | Döngüyü yazdığınız uygulamada | MCP destekleyen her istemcide |
Bir REST API'yi MCP sunucusuna sarmak dört adım sürer:
Operasyonları seçin
Ajanın görevi için 3–7 operasyon alın; araç adlarını, açıklamalarını ve parametrelerini yukarıdaki betikteki gibi OpenAPI'den üretin.
tools/list için listeyi döndürün
Sunucu her araç için
name,descriptionveinputSchemadöndürür.tools/call isteğini işleyin
Argümanları doğrulayın, sunucu ortamındaki anahtarla bir GET isteği yapın ve kompakt JSON'u bir
contentbloğunda döndürün. API hatasınıisError: trueile döndürün: model bunu argümanlarını düzeltmek için kullanır.Taşıma yöntemini seçin
stdio üzerinde sunucu sizin makinenizde çalışır ve anahtar oradan hiç çıkmaz. Uzak bir Streamable HTTP sunucusunu yetkilendirmenin arkasına koyun; aksi halde URL'yi öğrenen herkes kotanızı harcar.
Resmî MCP SDK'ları, Python ve TypeScript'ten Go ve Rust'a kadar 10 dil için mevcuttur (SDK listesi).
llms.txt ve llms-full.txt
llms.txt, /llms.txt adresinde bulunan ve dil modellerinin bir siteyi kullanmasına yardım eden bir Markdown dosyasıdır. Biçimi Jeremy Howard 3 Eylül 2024'te önerdi (llmstxt.org): tek zorunlu kısım, ad içeren bir H1'dir; ardından bir alıntı bloğundaki özet ve sayfaların Markdown sürümlerine bağlantı veren bölümler gelir.
Öneri llms-full.txt'yi tanımlamaz: bu ad, tüm bir dokümantasyonu tek Markdown dosyasında toplamak için kullanılıyor ve örneğin MCP dokümantasyon sitesi bunu yayımlıyor. Modelin bağlantıları izlemesi gerekmez; referansın tamamı bağlamına girer.
Ajan güvenliği
Anahtarı sunucuda bir ortam değişkeninde tutun: istemlerde, tarayıcılarda veya günlüklerde görünmemelidir. Genesis API anahtarı salt okunurdur; emir veremez ve para çekemez, sızması size kotaya mal olur. Sızan anahtarı profilinizdeki Yeniden oluştur ile değiştirin (anahtar saklama).
Prompt injection, verinin içine gizlenmiş modele yönelik bir talimattır. Bir token'ın adını onu dağıtan, bir trader'ın adını ise trader belirler; bu yüzden bir alan "önceki talimatları yok say" içerebilir. Genesis API'de dış metin, tahmin piyasalarının title ve outcome alanlarında, trader name alanında, zincir üstü token_name alanında ve Genesis AI+ sinyallerinin message_ru ile message_en alanlarında gelir: sistem isteminde araç sonuçlarının yalnızca veri olduğunu belirtin.
MCP spesifikasyonu, sunucuların araç girdilerini doğrulamasını, çağrılara rate limit uygulamasını ve çıktıları temizlemesini şart koşar; istemcilere ise hassas işlemleri onaylamalarını ve araç kullanımını günlüğe kaydetmelerini önerir (MCP araçları). X-Request-Id değerini günlüğe yazın: bununla, UTC saatiyle, endpoint'le ve durumla birlikte destek ekibi isteği bulabilir.
Otomasyonun riskleri Kripto API kursunun 5. dersinde ele alınıyor.
Maliyetler ve limitler
Genesis API kotasını yalnızca 200 yanıtı tüketir; 304 ve hatalar ücretsizdir, ancak saniyelik rate limit hesabına girer. Limitler aşıldığında sunucu 429 döndürür ve ücret almaz.
| Plan | Fiyat | Kota ve hız | Tazelik |
|---|---|---|---|
| Trial | $20/ay | 500.000 çağrı, 1 istek/sn | 60 sn |
| Start | $50/ay | 2M çağrı, 2 istek/sn | 30 sn |
| Pro | $100/ay | 5M çağrı, 5 istek/sn | 10 sn |
| Max | $200/ay | 10M çağrı, 15 istek/sn | 5 sn |
Açıklayıcı örnek: günde her biri 3 araç çağrısı içeren 500 soru, günde 500 × 3 = 1.500 çağrı eder; 30 günde 1.500 × 30 = 45.000, yani Trial kotasının %9'u. Önbellek, freshness_sec içinde aynı parametrelerle gelen tekrarları karşılar; cevap başına araç çağrısı sınırı da bir döngünün kotayı tüketmesini önler.
meta.freshness_sec süresinden daha sık sorgulamak yeni bir anlık görüntü getirmez. ETag ile ucuz sorgulama ve tekrar denemeler Kripto API'si limitlere takılmadan nasıl sorgulanır yazısında, limitler ise Genesis API limitleri rehberinde anlatılıyor. Ajanın yalnızca kurallara ihtiyacı varsa ve model gerekmiyorsa, Python ile kripto arbitraj botu daha basittir.
Yapay zekâ ajanları için Genesis API
Genesis API, Genesis Arbitrage verilerine REST erişimidir: CEX ve DEX spreadleri, emir defterleri, fonlama, açık pozisyon, zincirler arası, zincir üstü akışlar, tahmin piyasaları, spor bahisi surebet'leri ve AI sinyalleri. İstekler X-API-Key başlıklı HTTP GET'tir, yanıtlar data ve meta içeren JSON'dur (yanıt formatı), SDK gerekmez.
Ajanlar için yayımlananlar:
openapi.json— OpenAPI 3.1: 37 operasyon, yanıt şemaları vex-genesis-plansiçinde planlar;llms-full.txt— tek Markdown dosyasında tam referans;llms.txt— dil modelleri için site özeti;/.well-known/api-catalog— spesifikasyona, dokümantasyona ve durum sayfasına bağlantı veren bir RFC 9727 kataloğu.
Resmî bir MCP sunucusu, WebSocket ve işlem endpoint'leri yoktur: ajan veriyi okur, işlemler insanda kalır. Adım adım kurulum Yapay zekâ ajanları için Genesis API rehberindedir.
Sorular ve cevaplar
Yapay zekâ ajanı kriptoda kendi başına işlem yapabilir mi?
Yalnızca ona bir borsa işlem API'si verirseniz; bu sizin kodunuz ve sizin riskinizdir. Genesis API üzerinden olmaz: o yalnızca veri okur. MCP spesifikasyonu, bir insanın araç çağrısını her zaman reddedebilmesi gerektiğini söyler; işlemler için her emrin bir insan tarafından onaylanmasını kural haline getirin.
Yapay zekâ ajanı için hangi Genesis API planı gerekir?
Ayda $20'lık Trial; CEX spreadlerini, fonlama oranını ve açık pozisyonu kapsar. Start; hisse senetlerini, zincir üstü bölümleri ve exact ile dutch modlarında tahmin arbitrajını ekler; Pro ve Max ise DEX ile emir defterleri dahil her şeyi açar. Tepki hızı saniyelik limite ve planın tazeliğine bağlıdır; plan içerikleri Genesis API fiyatları sayfasında.
Ajan için Genesis API spesifikasyonunu nereden alırım?
OpenAPI 3.1 genesisarbitrage.com/openapi.json adresinde, model için referans ise genesisarbitrage.com/llms-full.txt adresindedir. Ajan her ikisini /.well-known/api-catalog kataloğu üzerinden de bulabilir.
Genesis API'nin MCP sunucusu var mı?
Resmî olan yok. Kendinizinkini aynı işleyicilerden oluşturursunuz: bir MCP aracı, sunucu ortamındaki anahtarla bir endpoint'e yapılan GET isteğidir. Minimal bir Python örneği MCP sözlük maddesindedir.