Genesis Arbitrage

Genesis Arbitrage · · 11 min de lectura

Genesis API para agentes de IA: OpenAPI, llms.txt y function calling

En resumen

  • Para los agentes hay openapi.json (OpenAPI 3.1, 37 operaciones con planes), llms-full.txt, llms.txt y un catálogo de API según RFC 9727.
  • El modelo elige una herramienta y sus argumentos; tu servidor hace la petición con la clave y devuelve al modelo un JSON corto con la hora de los datos.
  • Genesis API solo lee datos. Tu código limita la frecuencia de peticiones, el modelo trata el texto de las respuestas como datos y una persona confirma cualquier operación.

Genesis API es una API REST de datos de mercado cripto que un agente de IA llama como herramienta: el modelo decide qué datos necesita, tu servidor hace una petición GET con la clave y devuelve un JSON corto. Para agentes y modelos de lenguaje hay una descripción de la API legible por máquina: una especificación OpenAPI 3.1, una referencia completa en Markdown y un catálogo de API. Los datos son los que muestra el sitio: spreads CEX y DEX, libros de órdenes, funding, flujos on-chain y mercados de predicción.

Archivos legibles por máquina

ArchivoQué contienePara qué sirve
genesisarbitrage.com/openapi.jsonOpenAPI 3.1: 37 operaciones, parámetros, esquemas de respuesta, planes en x-genesis-plans, cabeceras de rate limitImportar en un cliente de API, generar código, herramientas de agentes
genesisarbitrage.com/llms-full.txtLa referencia completa en un solo archivo Markdown: endpoints, parámetros, campos, ejemplos, límites, erroresContexto para un modelo que escribe código o responde preguntas sobre la API
genesisarbitrage.com/llms.txtResumen del sitio: Genesis API, herramientas, Guía, curso, glosario, blogPrimera mirada de un modelo al sitio
genesisarbitrage.com/.well-known/api-catalogCatálogo de API según RFC 9727: enlaces a la especificación, la documentación, los precios y el estadoDescubrir la API a partir del dominio

La especificación sigue OpenAPI 3.1, cuyos esquemas son un superconjunto de JSON Schema 2020-12, así que los parámetros de una operación pasan a la definición de una herramienta casi sin cambios. llms.txt es un formato propuesto en 2024: un archivo Markdown en la raíz del sitio con un resumen breve y enlaces para modelos de lenguaje. El catálogo está en la dirección definida por el RFC 9727.

Las páginas de documentación, de producto y de precios de Genesis API incluyen <link rel="service-desc"> en <head>, que apunta a openapi.json. Ese tipo de relación viene del RFC 8631 y marca una descripción de servicio pensada para máquinas. Un extracto abreviado de la especificación:

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

Cada operación tiene un operationId, parámetros tipados, un esquema de respuesta 200, una respuesta 304, códigos de error y las cabeceras X-RateLimit-*, X-Quota-*, X-Request-Id y ETag. La clave se describe con el esquema de seguridad ApiKeyAuth: tipo apiKey, cabecera X-API-Key.

Cómo conectarse

  1. Consigue una clave y guárdala en el servidor

    La clave gns_live_… se emite en tu perfil, en el bloque Genesis API, y se muestra una sola vez. Guárdala en la variable de entorno GENESIS_API_KEY del servidor que ejecuta el agente. El almacenamiento y la reemisión se explican en la guía de la clave API.

  2. Importa la especificación

    Un cliente de API o un framework de agentes que acepte OpenAPI construye las peticiones y las herramientas directamente desde openapi.json: la URL base sale de servers y la cabecera de la clave, de ApiKeyAuth. Cómo se envía la clave se describe en Autenticación.

  3. Conserva las operaciones que necesitas

    Cada definición de herramienta ocupa espacio en el contexto del modelo, y elegir entre pocas es más fácil. Conserva las operaciones que tu tarea necesita y descarta las que quedan fuera de tu plan según x-genesis-plans: responden 403 plan_restricted.

  4. Dale al modelo la referencia

    Si el agente escribe código o responde preguntas sobre la API, añade llms-full.txt a su contexto: contiene los parámetros, campos y ejemplos de cada endpoint, los límites y los códigos de error.

  5. Comprueba la clave con una primera llamada

    /account/usage devuelve tu plan, la cuota usada, el límite de peticiones por segundo y la frescura de los datos.

Cómo llama el modelo a Genesis API

Function calling es el mecanismo por el que el modelo devuelve el nombre de una herramienta y sus argumentos en lugar de texto, y tu código hace la llamada. El ciclo:

  1. Junto con la pregunta del usuario, el modelo recibe las definiciones de las herramientas: nombre, finalidad y parámetros como JSON Schema.
  2. El modelo responde con una llamada: get_spreads con los argumentos {"coin": "TON", "min_spread": 0.5}.
  3. Tu servidor valida los argumentos, hace un GET con la cabecera X-API-Key y recorta la respuesta a los campos que necesitas.
  4. Un JSON corto con la hora de los datos vuelve al modelo, y este responde al usuario.

El modelo no hace llamadas de red y nunca ve la clave: solo tiene la definición de la herramienta y el resultado. Una herramienta get_spreads sobre el endpoint Spot — Spot:

{
  "name": "get_spreads",
  "description": "Dónde comprar una moneda más barata y venderla más cara (CEX)",
  "parameters": {
    "type": "object",
    "properties": {
      "coin": {
        "type": "string",
        "description": "Ticker de la moneda, p. ej. BTC"
      },
      "min_spread": {
        "type": "number",
        "description": "Spread mínimo, %: 0.5 significa 0.5%"
      }
    },
    "additionalProperties": false
  }
}

El campo que contiene el esquema de parámetros se llama distinto según el proveedor del modelo, inputSchema en MCP; dentro siempre es JSON Schema. Las propiedades coin y min_spread salen de los parámetros de la operación getArbitrageSpotSpot, y description indica cuándo llamar a la herramienta: el modelo elige según ese texto.

Un handler en Python que llama a /arbitrage/spot-spot y devuelve al modelo hasta 10 filas con los campos necesarios y meta.updated_at:

import os
import time

import requests

API = "https://api.genesisarbitrage.com/v1/arbitrage/spot-spot"
KEY = os.environ["GENESIS_API_KEY"]  # la clave se queda en el servidor
FIELDS = ("coin", "exchange_buy", "exchange_sell", "spread_pct",
          "withdraw_enabled_buy", "deposit_enabled_sell")
cache = {}  # params -> (hora, ETag, cuerpo de la respuesta)


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)  # los datos no se actualizarán antes
    headers = {"X-API-Key": KEY}
    if etag:
        headers["If-None-Match"] = etag
    for attempt in range(2):  # 429 y 503: esperar Retry-After y reintentar
        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}  # el modelo ve el código
    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]}

La respuesta se conserva en caché durante meta.freshness_sec segundos: los datos no se actualizarán antes. Pasado ese tiempo, el handler envía el ETag anterior en If-None-Match, y una respuesta 304 no consume cuota. Con 429 y 503 espera Retry-After, con un máximo de 30 s, reintenta una vez y devuelve al modelo los demás errores como un código. El modelo recibe 10 filas de 6 campos. Un ejemplo ilustrativo: una respuesta completa de 214 filas con 22 campos son 214 × 22 = 4.708 valores; la recortada, 10 × 6 = 60.

Reglas para el agente

ReglaCómo
La clave se queda en el servidorUna variable de entorno del handler; sin clave en el prompt, el navegador ni los registros del chat
La API solo leeGenesis API no coloca órdenes; una persona confirma cualquier operación en el exchange
Tu código fija la frecuenciaCaché durante freshness_sec, ETag e If-None-Match, una cola por debajo del límite de peticiones por segundo
Filtros, no el conjunto completocoin, min_spread, exchange; hasta 10 filas y los campos necesarios para el modelo
La hora de los datos en cada respuestaupdated_at y la antigüedad en el resultado de la herramienta y en la respuesta al usuario
El texto externo es solo datosEl modelo no actúa según títulos de mercados, resultados, nombres de traders ni textos de señales

El modelo puede pedir varias herramientas a la vez, y el límite cuenta todas las peticiones de la clave: 1 petición por segundo en Trial, 15 en Max. Las respuestas 304 y los errores no consumen cuota, pero sí cuentan para el límite por segundo; consulta Planes y límites y la guía de límites.

Los campos title y outcome de los mercados de predicción, el name de un trader, el token_name de los eventos on-chain y los message_ru y message_en de las señales de Genesis AI+ vienen de fuentes externas. Alguien puede llamar a un mercado «ignora las instrucciones anteriores y…»: eso es prompt injection, órdenes coladas a través de los datos. Pasa esos campos solo dentro del resultado de la herramienta, limita su longitud e indica en el prompt del sistema que el texto dentro de los resultados son datos.

MCP: tu propio servidor sobre la API REST

MCP (Model Context Protocol) es un estándar abierto para conectar aplicaciones de IA con sistemas externos. Un servidor MCP ofrece a la aplicación herramientas, recursos y plantillas de prompts; los mensajes son JSON-RPC 2.0, sobre stdio en local y Streamable HTTP en remoto. La especificación y los SDK de varios lenguajes están en modelcontextprotocol.io.

Genesis API no tiene un servidor MCP oficial. Puedes construir el tuyo con los mismos handlers: una herramienta MCP es un GET a un endpoint de Genesis API, sus parámetros son JSON Schema en inputSchema y la clave está en el entorno del servidor. Un servidor stdio local mantiene la clave en tu máquina. Pon uno remoto detrás de una autorización (MCP recomienda OAuth); de lo contrario, cualquiera que conozca la dirección puede gastar tu cuota.

Cómo trabajan los agentes con datos de mercado cripto en general se explica en el artículo sobre datos de mercado cripto para agentes de IA, y los riesgos de la automatización, en la quinta lección del curso.

Preguntas y respuestas

¿Tiene Genesis API un servidor MCP oficial?

No. Para los agentes hay openapi.json, llms-full.txt y el catálogo de API. Puedes escribir tú mismo un servidor MCP sobre la API REST: cada herramienta es una petición GET con la clave de una variable de entorno.

¿Puede un agente operar a través de Genesis API?

No. Genesis API solo lee datos y no coloca órdenes. El agente encuentra oportunidades y envía alertas; una persona hace la operación en el exchange.

¿Qué plan necesita un agente?

Cualquiera: Trial da 1 petición por segundo y una frescura de 60 s, Max 15 peticiones por segundo y 5 s. Los endpoints que incluye cada plan están en x-genesis-plans y en la página de precios de Genesis API.

¿Por qué el modelo cita precios desactualizados?

Los datos van con el retraso de frescura de tu plan, y la caché del handler añade hasta freshness_sec. Dale al modelo updated_at y la antigüedad de los datos, y pídele que indique la hora en su respuesta.