Genesis Arbitrage

Genesis Arbitrage · · 10 dk okuma

Yapay zekâ ajanları için Genesis API: OpenAPI, llms.txt ve function calling

Kısaca

  • Ajanlar için openapi.json (OpenAPI 3.1, planlarıyla 37 işlem), llms-full.txt, llms.txt ve RFC 9727'ye göre bir API kataloğu var.
  • Model bir araç ve argümanlarını seçer; sunucunuz anahtarlı isteği yapar ve modele veri zamanı içeren kısa bir JSON döndürür.
  • Genesis API yalnızca veri okur. İstek hızını kodunuz sınırlar, model yanıtlardaki metni veri olarak ele alır, her işlemi bir insan onaylar.

Genesis API, yapay zekâ ajanının araç olarak çağırdığı bir kripto piyasa verisi REST API'sidir: model hangi veriye ihtiyacı olduğuna karar verir, sunucunuz anahtarla bir GET isteği yapar ve kısa bir JSON döndürür. Ajanlar ve dil modelleri için API'nin makine tarafından okunabilir bir tanımı vardır: OpenAPI 3.1 şeması, Markdown biçiminde tam bir başvuru ve bir API kataloğu. Veriler sitenin gösterdiğiyle aynıdır: CEX ve DEX spread'leri, emir defterleri, fonlama, zincir üstü akışlar ve tahmin piyasaları.

Makine tarafından okunabilir dosyalar

DosyaİçeriğiNe için
genesisarbitrage.com/openapi.jsonOpenAPI 3.1: 37 işlem, parametreler, yanıt şemaları, x-genesis-plans içinde planlar, rate limit başlıklarıAPI istemcisine aktarma, kod üretimi, ajan araçları
genesisarbitrage.com/llms-full.txtTam başvuru tek bir Markdown dosyasında: endpoint'ler, parametreler, alanlar, örnekler, limitler, hatalarKod yazan veya API sorularını yanıtlayan model için bağlam
genesisarbitrage.com/llms.txtSite özeti: Genesis API, araçlar, rehber, kurs, sözlük, blogModelin siteye ilk bakışı
genesisarbitrage.com/.well-known/api-catalogRFC 9727'ye göre API kataloğu: şemaya, dokümantasyona, fiyatlara ve duruma bağlantılarAlan adı üzerinden API keşfi

Şema OpenAPI 3.1 standardına uyar; bu standardın şemaları JSON Schema 2020-12'nin üst kümesidir, bu yüzden işlem parametreleri araç tanımına neredeyse değişmeden aktarılır. llms.txt, 2024'te önerilen bir biçimdir: sitenin kökünde, dil modelleri için kısa bir özet ve bağlantılar içeren bir Markdown dosyası. Katalog, RFC 9727 ile tanımlanan adreste durur.

Genesis API dokümantasyon, ürün ve fiyat sayfalarının <head> bölümünde openapi.json dosyasına işaret eden <link rel="service-desc"> bulunur. Bu bağlantı ilişkisi RFC 8631 standardından gelir ve makineler için hazırlanmış bir servis tanımını işaretler. Şemadan kısaltılmış bir alıntı:

{
  "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" } },
          …
        ]
      }
    }
  }
}

Her işlemde bir operationId, tiplenmiş parametreler, bir 200 yanıt şeması, bir 304 yanıtı, hata kodları ile X-RateLimit-*, X-Quota-*, X-Request-Id ve ETag başlıkları vardır. Anahtar ApiKeyAuth güvenlik şemasıyla tanımlanır: tür apiKey, başlık X-API-Key.

Nasıl bağlanılır

  1. Anahtarı alın ve sunucuda saklayın

    gns_live_… anahtarı profilinizde, Genesis API bloğunda verilir ve yalnızca bir kez gösterilir. Anahtarı, ajanı çalıştıran sunucuda GENESIS_API_KEY ortam değişkeninde saklayın. Saklama ve yeniden oluşturma API anahtarı rehberinde anlatılıyor.

  2. Şemayı içe aktarın

    OpenAPI kabul eden bir API istemcisi veya ajan çerçevesi, istekleri ve araçları doğrudan openapi.json dosyasından üretir: temel URL servers alanından, anahtar başlığı ApiKeyAuth üzerinden gelir. Anahtarın nasıl gönderildiği Kimlik doğrulama bölümünde açıklanıyor.

  3. İhtiyacınız olan işlemleri bırakın

    Her araç tanımı modelin bağlamında yer kaplar ve birkaç araç arasından seçmek daha kolaydır. Görevinizin gerektirdiği işlemleri bırakın, x-genesis-plans uyarınca planınızın dışında kalanları çıkarın: bunlar 403 plan_restricted döndürür.

  4. Modele başvuruyu verin

    Ajan kod yazıyorsa veya API hakkındaki soruları yanıtlıyorsa bağlamına llms-full.txt ekleyin: her endpoint'in parametrelerini, alanlarını ve örneklerini, limitleri ve hata kodlarını içerir.

  5. Anahtarı ilk çağrıyla doğrulayın

    /account/usage planınızı, kullanılan kotayı, saniyedeki istek limitini ve verinin tazeliğini döndürür.

Model Genesis API'yi nasıl çağırır

Function calling, modelin metin yerine bir araç adı ve argümanlar döndürdüğü, çağrıyı ise kodunuzun yaptığı mekanizmadır. Döngü şöyle işler:

  1. Model, kullanıcının sorusuyla birlikte araç tanımlarını alır: ad, amaç ve JSON Schema olarak parametreler.
  2. Model bir çağrıyla yanıt verir: get_spreads aracı, {"coin": "TON", "min_spread": 0.5} argümanlarıyla.
  3. Sunucunuz argümanları doğrular, X-API-Key başlığıyla bir GET yapar ve yanıtı ihtiyaç duyduğunuz alanlara kırpar.
  4. Veri zamanını içeren kısa bir JSON modele geri döner ve model kullanıcıyı yanıtlar.

Model ağ çağrısı yapmaz ve anahtarı hiç görmez: elinde yalnızca araç tanımı ve sonuç vardır. Spot – Spot endpoint'i üzerinde bir get_spreads aracı:

{
  "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
  }
}

Parametre şemasını tutan alanın adı model sağlayıcılarına göre değişir, MCP'de inputSchema'dır; içeride her zaman JSON Schema bulunur. coin ve min_spread özellikleri getArbitrageSpotSpot işleminin parametrelerinden gelir, description ise aracın ne zaman çağrılacağını söyler: model bu metne göre seçer.

/arbitrage/spot-spot endpoint'ini çağıran ve modele gerekli alanlarla en fazla 10 satırı ve meta.updated_at değerini döndüren bir Python işleyicisi:

import os
import time

import requests

API = "https://api.genesisarbitrage.com/v1/arbitrage/spot-spot"
KEY = os.environ["GENESIS_API_KEY"]  # anahtar sunucuda kalır
FIELDS = ("coin", "exchange_buy", "exchange_sell", "spread_pct",
          "withdraw_enabled_buy", "deposit_enabled_sell")
cache = {}  # parametreler -> (zaman, ETag, yanıt gövdesi)


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)  # veri bundan önce güncellenmez
    headers = {"X-API-Key": KEY}
    if etag:
        headers["If-None-Match"] = etag
    for attempt in range(2):  # 429 ve 503: Retry-After kadar bekle, yeniden dene
        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 kodu görür
    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]}

Yanıt meta.freshness_sec saniye boyunca önbellekte kalır: veri bundan önce güncellenmez. Sonrasında işleyici önceki ETag değerini If-None-Match içinde gönderir ve 304 kotadan düşmez. 429 ve 503 durumunda Retry-After kadar bekler (en fazla 30 sn), bir kez yeniden dener, diğer hataları modele kod olarak döndürür. Model 6 alanlı 10 satır alır. Açıklayıcı bir örnek: 22 alanlı 214 satırlık tam bir yanıt 214 × 22 = 4.708 değerdir, kırpılmış olan 10 × 6 = 60.

Ajan için kurallar

KuralNasıl
Anahtar sunucuda kalırİşleyicinin ortam değişkeni; anahtar prompt'ta, tarayıcıda veya sohbet günlüklerinde yer almaz
API yalnızca okurGenesis API emir vermez; her borsa işlemini bir insan onaylar
Hızı kodunuz belirlerfreshness_sec süresince önbellek, ETag ve If-None-Match, saniyedeki istek limitinin altında bir kuyruk
Tüm küme değil, filtrelercoin, min_spread, exchange; modele en fazla 10 satır ve gerekli alanlar
Her yanıtta veri zamanıAraç sonucunda ve kullanıcıya verilen yanıtta updated_at ve veri yaşı
Dış metin yalnızca veridirModel piyasa başlıklarına, sonuçlara, trader adlarına veya sinyal metinlerine göre hareket etmez

Model aynı anda birkaç araç isteyebilir ve limit, anahtardaki her isteği sayar: Trial'da saniyede 1, Max'te 15 istek. 304 yanıtları ve hatalar kotadan düşmez ama saniyedeki limite sayılır — bkz. Planlar ve limitler ve limitler rehberi.

Tahmin piyasalarının title ve outcome alanları, trader name değeri, zincir üstü olayların token_name alanı ve Genesis AI+ sinyallerinin message_ru ile message_en alanları dış kaynaklardan gelir. Biri bir piyasaya "önceki talimatları yok say ve…" adını verebilir — bu, verinin içine gizlenmiş komutlarla yapılan prompt injection saldırısıdır. Bu alanları yalnızca araç sonucunun içinde iletin, uzunluklarını sınırlayın ve sistem prompt'unda sonuçlardaki metnin veri olduğunu belirtin.

MCP: REST API'nin üzerinde kendi sunucunuz

MCP (Model Context Protocol), yapay zekâ uygulamalarını harici sistemlere bağlamak için açık bir standarttır. Bir MCP sunucusu uygulamaya araçlar, kaynaklar ve prompt şablonları sunar; mesajlar JSON-RPC 2.0'dır, yerelde stdio, uzakta Streamable HTTP üzerinden iletilir. Şartname ve birkaç dil için SDK'lar modelcontextprotocol.io adresindedir.

Genesis API'nin resmî bir MCP sunucusu yok. Aynı işleyicilerden kendinizinkini kurabilirsiniz: MCP aracı, bir Genesis API endpoint'ine yapılan GET isteğidir, parametreleri inputSchema içinde JSON Schema olarak yer alır, anahtar ise sunucunun ortamında durur. Yerel bir stdio sunucusu anahtarı makinenizde tutar. Uzak sunucuyu yetkilendirmenin arkasına koyun (MCP, OAuth önerir); aksi halde adresi öğrenen herkes kotanızı tüketebilir.

Ajanların kripto piyasa verileriyle genel olarak nasıl çalıştığı yapay zekâ ajanları için kripto piyasa verileri makalesinde, otomasyon riskleri ise kursun beşinci dersinde anlatılıyor.

Sorular ve cevaplar

Genesis API'nin resmî bir MCP sunucusu var mı?

Hayır. Ajanlar için openapi.json, llms-full.txt ve API kataloğu var. REST API'nin üzerine kendi MCP sunucunuzu yazabilirsiniz: her araç, anahtarı ortam değişkeninden alan bir GET isteğidir.

Ajan Genesis API üzerinden işlem yapabilir mi?

Hayır. Genesis API yalnızca veri okur ve emir vermez. Ajan fırsatları bulur ve uyarı gönderir; işlemi borsada bir insan yapar.

Ajan için hangi plan gerekir?

Herhangi biri: Trial saniyede 1 istek ve 60 sn tazelik, Max saniyede 15 istek ve 5 sn tazelik verir. Bir planın hangi endpoint'leri içerdiği x-genesis-plans alanında ve Genesis API fiyatları sayfasındadır.

Model neden eski fiyatları aktarıyor?

Veri, planınızın tazeliği kadar gecikir ve işleyicinin önbelleği en fazla freshness_sec ekler. Modele updated_at değerini ve verinin yaşını verin, yanıtında zamanı belirtmesini isteyin.