Genesis Arbitrage

Genesis Arbitrage · · 17 min de lectura

Datos de mercado cripto para agentes de IA: API, function calling, MCP y llms.txt

En resumen

  • Un modelo de lenguaje conoce el mercado solo hasta la fecha de corte de su entrenamiento. Los precios, spreads y tasas de financiación (funding) actuales los obtiene mediante herramientas: el modelo elige la llamada y sus argumentos, y tu código hace la petición a la API.
  • Una herramienta sobre una API de datos de mercado debe ser acotada: un endpoint, filtros como parámetros, pocas filas con los campos que importan y la hora de los datos en el resultado. Las definiciones de herramientas salen de la especificación OpenAPI, y MCP conecta las mismas herramientas a cualquier cliente compatible.
  • La clave se queda en tu servidor, el texto de datos externos llega al modelo solo dentro de resultados de herramientas y una persona confirma cada operación. Genesis API es de solo lectura y publica openapi.json, llms-full.txt y un catálogo de API para agentes.

Un agente de IA obtiene datos de mercado cripto mediante herramientas: el modelo decide qué datos necesita, tu código llama a una API de criptomonedas y devuelve un JSON breve con precios, spreads y la hora en que se construyeron los datos. Las herramientas se conectan mediante function calling en la API del modelo o mediante un servidor MCP, y ambas funcionan sobre una API REST común.

Los ejemplos usan Genesis API, una API REST de solo lectura con datos de CEX, DEX, on-chain y mercados de predicción. Sobre las API de criptomonedas en general y cómo compararlas, consulta API de criptomonedas: tipos de API de datos de mercado y cómo elegir.

Por qué el modelo no conoce los precios actuales

Un modelo de lenguaje se entrena con texto recopilado hasta una fecha determinada, su fecha de corte de conocimiento. No sabe nada de listados, tasas y precios posteriores, y un precio de BTC citado de memoria es una cifra de un texto de entrenamiento de fecha desconocida. Tampoco conoce la hora actual si no se la pasas en la petición.

Para el arbitraje una respuesta de memoria no sirve: un spread entre exchanges dura minutos, y la tasa de financiación (funding) cambia en cada periodo de liquidación, cada 8, 4 o 1 hora. Las cifras en vivo solo llegan de una herramienta: una referencia de la API en el contexto enseña al modelo rutas y parámetros, pero no contiene precios.

Qué necesita el modeloDe dónde saleEjemplo
Rutas, parámetros y campos de la APIReferencia en el contextollms-full.txt, openapi.json
Precios, spreads, tasasLlamada a una herramientaGET /funding/spread?coin=TON
Hora actual y antigüedad de los datosPrompt del sistema y resultado de la herramientaupdated_at, age_sec

Cómo funciona el function calling

El function calling es un modo en el que el modelo devuelve el nombre de una herramienta y sus argumentos en lugar de texto, y tu código ejecuta la petición. Ejemplo ilustrativo: un usuario pregunta dónde está ahora el mayor spread de funding de TON. La llamada y el resultado, de forma esquemática:

{
  "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"]
      }
    ]
  }
}
  1. La aplicación envía al modelo la pregunta y las definiciones de las herramientas: nombre, finalidad y un esquema de argumentos en JSON Schema.
  2. El modelo devuelve una llamada a get_funding con los argumentos {"coin": "TON"}.
  3. Tu código valida los argumentos, envía GET /funding/spread?coin=TON con el encabezado X-API-Key y recorta la respuesta.
  4. El resultado vuelve al modelo, que responde: Bitget y Bybit, 0,05 % y 0,01 % cada 8 horas, una diferencia de 0,04 %, datos de hace 12 segundos.
  5. Si los datos no bastan, el modelo llama a la siguiente herramienta.

El modelo no hace peticiones de red y nunca ve la clave de API. Los nombres de los campos dependen de la API del modelo: en la API de Claude el esquema va en input_schema, la llamada llega como un bloque tool_use y el resultado vuelve como un bloque tool_result, mientras que MCP llama al esquema inputSchema. En ambos casos es JSON Schema.

Cómo diseñar herramientas sobre una API de datos de mercado

Una herramienta, una tarea

El modelo elige la herramienta por su descripción, así que las herramientas acotadas funcionan con más fiabilidad que un call_api(path, params) genérico. Elegir entre cinco y siete herramientas hechas para las tareas del agente es más fácil que elegir entre las 37 operaciones de la especificación.

HerramientaEndpoint de Genesis APIPlanes
get_spreads/arbitrage/spot-spotTodos
get_funding/funding/spreadTodos
get_prediction_arbs/predictions/arbitrageStart, Pro, Max
get_book/orderbooks/bookPro, Max

La descripción indica cuándo llamar a la herramienta y en qué unidades están los números: en Genesis API los spreads y las tasas son porcentajes, así que 0.92 significa 0,92 %.

Filtros como parámetros, validación en el código

Los filtros de la API, como coin, exchange y min_spread, se convierten en parámetros de la herramienta. El modelo los rellena a partir de la pregunta, el handler los comprueba contra una lista de parámetros, tipos y valores permitidos, y enum enumera los valores admitidos: en /orderbooks/book, market solo puede ser spot o futures. El modelo nunca construye la ruta de la petición, y el esquema rechaza los campos adicionales (additionalProperties: false).

Una respuesta filtrada llega sin ETag, así que cada consulta filtrada repetida cuesta una llamada: no hay 304 gratis. Si el agente necesita decenas de monedas, sale más barato conservar en local el conjunto de datos completo sin filtrar y consultarlo con If-None-Match.

Resultados compactos

Ejemplo ilustrativo: la respuesta completa sin filtrar de /funding/spread abarca 1.000 monedas. Para una moneda en 10 exchanges, una fila contiene 2 + 10 + 8 × 5 = 52 valores: la moneda, el spread, 10 campos del mejor par en best y 5 campos por cada uno de los otros 8 exchanges en others. La respuesta completa son 1.000 × 52 = 52.000 valores, mientras que una respuesta sobre los mejores pares necesita 5 filas de 8 valores: 5 × 8 = 40.

Las definiciones de herramientas y los resultados entran en el contexto en cada paso: la API de Claude los factura como tokens de entrada.

Hora de los datos y frescura

El handler incluye en el resultado updated_at, la hora de construcción de los datos de meta.updated_at en segundos unix, y age_sec. Así el modelo puede decir «datos de hace 12 segundos» en lugar de hacer pasar por actual el spread de ayer.

La frescura de los datos depende del plan: meta.freshness_sec va de 60 s en Trial a 5 s en Max. Antes de que pase ese intervalo, la API devuelve la misma instantánea, por lo que el handler guarda la respuesta en caché durante freshness_sec segundos. Los libros de órdenes llevan su propio reloj: book_ts, age_sec y una marca stale para los libros de más de 30 s.

Ejemplo: la herramienta get_funding

La definición de abajo usa el formato MCP; para la API de Claude el mismo contenido va en input_schema. El handler aplica limit por su cuenta: la API no tiene ese parámetro.

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

El handler en Python: una caché durante freshness_sec, una pausa breve ante 429 y 503, un log sin la clave y un resultado compacto con la hora de los datos.

import logging
import os
import time

import requests

URL = "https://api.genesisarbitrage.com/v1/funding/spread"
KEY = os.environ["GENESIS_API_KEY"]  # la clave se queda en el servidor
cache = {}  # parámetros de la petición -> (hora de recepción, cuerpo de la respuesta)


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: espera corta, un reintento
            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"))  # sin la clave en el 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}

El handler no espera pausas de más de 5 segundos: cuando se agota la cuota, Retry-After apunta al reinicio, que puede estar a días de distancia. El modelo recibe el código de estado y cuenta al usuario lo ocurrido: 403 significa plan_restricted, un endpoint fuera del plan (errores de Genesis API).

OpenAPI como fuente de las definiciones de herramientas

OpenAPI es un estándar para descripciones de API HTTP legibles por máquina: una operación se describe con un operationId, un summary breve y parámetros con esquemas. En la versión 3.1 el Schema Object es un superconjunto de JSON Schema 2020-12 (especificación OpenAPI 3.1), y MCP lee inputSchema como JSON Schema 2020-12 por defecto. Por eso los parámetros pasan a una herramienta sin conversión.

El script construye las herramientas a partir de la especificación de Genesis API: toma las operaciones que quieres, omite las que quedan fuera de tu plan según x-genesis-plans y traslada los parámetros de query y de ruta. Los encabezados son tarea del handler.

import requests

SPEC = "https://genesisarbitrage.com/openapi.json"


def tools_from_spec(wanted, plan):
    """wanted: operationId -> nombre de la herramienta; 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  # no deseada o fuera del plan: 403 plan_restricted
        props, required = {}, []
        for prm in op.get("parameters", []):
            if "$ref" in prm or prm["in"] not in ("query", "path"):
                continue  # el handler envía 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  # nombre de la herramienta -> ruta del endpoint
    return tools, routes


tools, routes = tools_from_spec({"getFundingSpread": "get_funding",
                                 "getArbitrageSpotSpot": "get_spreads"},
                                plan="trial")

getFundingSpread se convierte en una herramienta get_funding con los parámetros coin y min_spread. Si pasas todas las operaciones, Trial conserva 11 de las 37 y Start conserva 16. El diccionario routes guarda la ruta de cada herramienta.

MCP: tu propio servidor sobre una API REST

MCP (Model Context Protocol) es un estándar abierto para conectar aplicaciones de IA con datos y herramientas. Anthropic lo publicó como código abierto el 25 de noviembre de 2024 (anuncio de Anthropic) y el 9 de diciembre de 2025 lo donó a la Agentic AI Foundation, un fondo de la Linux Foundation (blog de MCP).

La aplicación con el modelo, el host, crea un cliente MCP por servidor. Un servidor expone herramientas, recursos y plantillas de prompts sobre JSON-RPC 2.0: uno local mediante stdio, uno remoto mediante Streamable HTTP, para el cual MCP recomienda obtener los tokens con OAuth (arquitectura de MCP).

Function callingMCP
Dónde se definen las herramientasEn la petición a la API del modeloEn el servidor; el cliente las obtiene con tools/list
Quién ejecuta la llamadaEl código de tu aplicaciónEl servidor MCP, ante una petición tools/call
Dónde funcionaEn la aplicación donde escribiste el bucleEn cualquier cliente compatible con MCP

Envolver una API REST en un servidor MCP lleva cuatro pasos:

  1. Elige las operaciones

    Toma de 3 a 7 operaciones para la tarea del agente; construye los nombres, descripciones y parámetros de las herramientas a partir de OpenAPI, como en el script anterior.

  2. Devuelve la lista en tools/list

    El servidor devuelve name, description e inputSchema de cada herramienta.

  3. Atiende tools/call

    Valida los argumentos, haz una petición GET con la clave del entorno del servidor y devuelve un JSON compacto en un bloque content. Devuelve un error de la API con isError: true: el modelo lo usa para corregir sus argumentos.

  4. Elige el transporte

    Con stdio el servidor se ejecuta en tu máquina y la clave nunca sale de ella. Pon un servidor remoto Streamable HTTP detrás de una autorización, o cualquiera que conozca la URL gastará tu cuota.

Existen SDK oficiales de MCP para 10 lenguajes, de Python y TypeScript a Go y Rust (lista de SDK).

llms.txt y llms-full.txt

llms.txt es un archivo Markdown en /llms.txt que ayuda a los modelos de lenguaje a usar un sitio web. Jeremy Howard propuso el formato el 3 de septiembre de 2024 (llmstxt.org): lo único obligatorio es un H1 con el nombre, seguido de un resumen en cita y secciones con enlaces a versiones en Markdown de las páginas.

La propuesta no define llms-full.txt: el nombre se usa para toda una documentación en un solo archivo Markdown, y el sitio de documentación de MCP, por ejemplo, lo publica. El modelo no necesita seguir enlaces, porque toda la referencia llega a su contexto.

Seguridad del agente

Guarda la clave en una variable de entorno del servidor: no debe aparecer en prompts, navegadores ni logs. Una clave de Genesis API es de solo lectura, así que no puede colocar una orden ni retirar fondos, y una filtración te cuesta cuota. Sustituye una clave filtrada con Reemitir en tu perfil (almacenamiento de claves).

La inyección de prompts es una instrucción para el modelo oculta en los datos. El nombre de un token lo fija quien lo desplegó y el nombre de un trader lo fija el trader, así que un campo puede contener «ignore previous instructions». En Genesis API el texto externo llega en los campos title y outcome de los mercados de predicción, en el name de los traders, en el token_name on-chain y en message_ru y message_en de las señales de Genesis AI+: indica en el prompt del sistema que los resultados de las herramientas son solo datos.

La especificación de MCP exige que los servidores validen las entradas de las herramientas, limiten la frecuencia de las invocaciones y saneen las salidas, y aconseja a los clientes confirmar las operaciones sensibles y registrar el uso de las herramientas (herramientas de MCP). Registra el X-Request-Id: con él, la hora en UTC, el endpoint y el estado, el soporte puede encontrar la petición.

Los riesgos de la automatización se tratan en la lección 5 del curso de API de criptomonedas.

Costes y límites

Solo una respuesta 200 consume la cuota de Genesis API; 304 y los errores son gratuitos, pero cuentan para el límite de frecuencia (rate limit) por segundo. Al superar los límites, el servidor responde 429 y no cobra nada.

PlanPrecioCuota y frecuenciaFrescura
Trial20 $/mes500.000 llamadas, 1 petición/s60 s
Start50 $/mes2 M de llamadas, 2 peticiones/s30 s
Pro100 $/mes5 M de llamadas, 5 peticiones/s10 s
Max200 $/mes10 M de llamadas, 15 peticiones/s5 s

Ejemplo ilustrativo: 500 preguntas al día con 3 llamadas a herramientas cada una son 500 × 3 = 1.500 llamadas al día y 1.500 × 30 = 45.000 en 30 días, el 9 % de la cuota de Trial. La caché cubre las repeticiones con los mismos parámetros dentro de freshness_sec, y un tope de llamadas a herramientas por respuesta evita que un bucle se coma la cuota.

Consultar con más frecuencia que meta.freshness_sec no aporta ninguna instantánea nueva. Las consultas baratas con ETag y reintentos se explican en Cómo consultar una API de criptomonedas sin chocar con los límites, y los límites, en la guía Límites de Genesis API. Si el agente solo necesita reglas y no un modelo, un bot de arbitraje cripto en Python es más sencillo.

Genesis API para agentes de IA

Genesis API es una API REST con datos de Genesis Arbitrage: spreads de CEX y DEX, libros de órdenes, funding, open interest, cross-chain, flujos on-chain, mercados de predicción, surebets de casas de apuestas y señales de IA. Las peticiones son HTTP GET con el encabezado X-API-Key, las respuestas son JSON con data y meta (formato de respuesta) y no hace falta ningún SDK.

Publicado para agentes:

No hay servidor MCP oficial, ni WebSocket, ni endpoints de trading: el agente lee datos y las operaciones quedan en manos de una persona. La configuración paso a paso está en la guía Genesis API para agentes de IA.

Preguntas y respuestas

¿Puede un agente de IA operar con criptomonedas por sí solo?

Solo si le das una API de trading de un exchange, y eso es tu código y tu riesgo. No a través de Genesis API: esta solo lee datos. La especificación de MCP dice que una persona siempre debe poder rechazar una llamada a una herramienta; para las operaciones, establece como regla que una persona confirme cada orden.

¿Qué plan de Genesis API necesita un agente de IA?

Trial, a 20 $ al mes, cubre spreads de CEX, funding y open interest. Start añade acciones, secciones on-chain y arbitraje de mercados de predicción en los modos exact y dutch, mientras que Pro y Max abren todo, incluidos DEX y libros de órdenes. La velocidad de reacción depende del límite por segundo y de la frescura del plan; el contenido de los planes está en la página de precios de Genesis API.

¿Dónde consigo la especificación de Genesis API para un agente?

OpenAPI 3.1 está en genesisarbitrage.com/openapi.json, y la referencia para el modelo, en genesisarbitrage.com/llms-full.txt. Un agente también puede encontrar ambos mediante el catálogo /.well-known/api-catalog.

¿Tiene Genesis API un servidor MCP?

No hay uno oficial. Construyes el tuyo a partir de los mismos handlers: una herramienta MCP es una petición GET a un endpoint con la clave del entorno del servidor. Un ejemplo mínimo en Python está en la entrada MCP del glosario.