Genesis Arbitrage

Genesis Arbitrage · · 17 min de leitura

Dados de mercado cripto para agentes de IA: APIs, function calling, MCP e llms.txt

Em resumo

  • Um modelo de linguagem conhece o mercado apenas até a data de corte do seu treinamento. Ele obtém preços, spreads e taxas de financiamento (funding) atuais por meio de ferramentas: o modelo escolhe a chamada e seus argumentos, e o seu código faz a requisição à API.
  • Uma ferramenta sobre uma API de dados de mercado deve ser enxuta: um endpoint, filtros como parâmetros, poucas linhas com os campos que importam e o horário dos dados no resultado. As definições das ferramentas vêm da especificação OpenAPI, e o MCP conecta as mesmas ferramentas a qualquer cliente compatível.
  • A chave fica no seu servidor, o texto de dados externos chega ao modelo apenas dentro de resultados de ferramentas, e uma pessoa confirma cada operação. A Genesis API é somente leitura e publica openapi.json, llms-full.txt e um catálogo de API para agentes.

Um agente de IA obtém dados de mercado cripto por meio de ferramentas: o modelo decide de quais dados precisa, o seu código chama uma API de criptomoedas e devolve um JSON curto com preços, spreads e o horário em que os dados foram gerados. As ferramentas são conectadas por function calling na API do modelo ou por um servidor MCP, e ambas funcionam sobre uma API REST comum.

Os exemplos usam a Genesis API, uma API REST somente leitura com dados de CEX, DEX, on-chain e mercados de previsão. Sobre APIs de criptomoedas em geral e como compará-las, veja API de criptomoedas: tipos de API de dados de mercado e como escolher.

Por que o modelo não conhece os preços atuais

Um modelo de linguagem é treinado com textos coletados até certa data, a sua data de corte de conhecimento. Ele não sabe nada sobre listagens, taxas e preços posteriores, e um preço do BTC citado de memória é um número de um texto de treinamento de data desconhecida. O modelo também não sabe a hora atual, a menos que você a passe na requisição.

Para arbitragem, uma resposta de memória é inútil: um spread entre exchanges dura minutos, e a taxa de financiamento (funding) muda a cada período de liquidação, a cada 8, 4 ou 1 hora. Os números em tempo real vêm apenas de uma ferramenta: uma referência da API no contexto ensina ao modelo caminhos e parâmetros, mas não contém preços.

O que o modelo precisaDe onde vemExemplo
Caminhos, parâmetros e campos da APIReferência no contextollms-full.txt, openapi.json
Preços, spreads, taxasChamada de ferramentaGET /funding/spread?coin=TON
Hora atual e idade dos dadosPrompt de sistema e resultado da ferramentaupdated_at, age_sec

Como funciona o function calling

O function calling é um modo em que o modelo devolve o nome de uma ferramenta e argumentos em vez de texto, e o seu código executa a requisição. Exemplo ilustrativo: um usuário pergunta onde está agora o maior spread de funding para TON. A chamada e o 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. O aplicativo envia ao modelo a pergunta e as definições das ferramentas: nome, finalidade e um esquema de argumentos em JSON Schema.
  2. O modelo devolve uma chamada get_funding com os argumentos {"coin": "TON"}.
  3. O seu código valida os argumentos, envia GET /funding/spread?coin=TON com o cabeçalho X-API-Key e reduz a resposta.
  4. O resultado volta ao modelo, que responde: Bitget e Bybit, 0,05% e 0,01% por 8 horas, uma diferença de 0,04%, dados de 12 segundos atrás.
  5. Se os dados não bastarem, o modelo chama a próxima ferramenta.

O modelo não faz requisições de rede e nunca vê a chave de API. Os nomes dos campos dependem da API do modelo: na API do Claude o esquema fica em input_schema, a chamada chega como um bloco tool_use e o resultado volta como um bloco tool_result, enquanto o MCP chama o esquema de inputSchema. Nos dois casos é JSON Schema.

Como projetar ferramentas sobre uma API de dados de mercado

Uma ferramenta, uma tarefa

O modelo escolhe uma ferramenta pela descrição, então ferramentas enxutas funcionam com mais confiabilidade do que um call_api(path, params) genérico. Escolher entre cinco e sete ferramentas feitas para as tarefas do agente é mais fácil do que escolher entre as 37 operações da especificação.

FerramentaEndpoint da Genesis APIPlanos
get_spreads/arbitrage/spot-spotTodos
get_funding/funding/spreadTodos
get_prediction_arbs/predictions/arbitrageStart, Pro, Max
get_book/orderbooks/bookPro, Max

A descrição diz quando chamar a ferramenta e em quais unidades estão os números: na Genesis API, spreads e taxas são porcentagens, então 0.92 significa 0,92%.

Filtros como parâmetros, validação no código

Filtros da API como coin, exchange e min_spread viram parâmetros da ferramenta. O modelo os preenche a partir da pergunta, o handler os confere com uma lista permitida de parâmetros, tipos e valores, e enum lista os valores aceitos: em /orderbooks/book, market é apenas spot ou futures. O modelo nunca monta o caminho da requisição, e o esquema rejeita campos extras (additionalProperties: false).

Uma resposta filtrada vem sem ETag, então cada consulta filtrada repetida custa uma chamada: não existe 304 gratuito. Se o agente precisa de dezenas de moedas, sai mais barato manter localmente o conjunto de dados completo, sem filtro, e consultá-lo com If-None-Match.

Resultados compactos

Exemplo ilustrativo: a resposta completa, sem filtro, de /funding/spread cobre 1.000 moedas. Para uma moeda em 10 exchanges, uma linha contém 2 + 10 + 8 × 5 = 52 valores: a moeda, o spread, 10 campos do melhor par em best e 5 campos para cada uma das outras 8 exchanges em others. A resposta inteira tem 1.000 × 52 = 52.000 valores, enquanto uma resposta sobre os melhores pares precisa de 5 linhas de 8 valores: 5 × 8 = 40.

As definições das ferramentas e os resultados entram no contexto a cada passo: a API do Claude os cobra como tokens de entrada.

Horário dos dados e atualidade

O handler coloca no resultado updated_at, o horário de geração dos dados de meta.updated_at em segundos unix, e age_sec. Assim o modelo pode dizer «dados de 12 segundos atrás» em vez de passar o spread de ontem como atual.

A atualidade dos dados é definida pelo plano: meta.freshness_sec vai de 60 s no Trial a 5 s no Max. Antes de esse intervalo passar, a API devolve o mesmo snapshot, então o handler guarda a resposta em cache por freshness_sec segundos. Os livros de ofertas têm o próprio relógio: book_ts, age_sec e um sinalizador stale para livros com mais de 30 s.

Exemplo: a ferramenta get_funding

A definição abaixo usa o formato MCP; na API do Claude o mesmo conteúdo vai em input_schema. O handler aplica limit por conta própria: a API não tem esse 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
  }
}

O handler em Python: cache por freshness_sec, uma pausa curta em 429 e 503, um log sem a chave e um resultado compacto com o horário dos dados.

import logging
import os
import time

import requests

URL = "https://api.genesisarbitrage.com/v1/funding/spread"
KEY = os.environ["GENESIS_API_KEY"]  # a chave fica no servidor
cache = {}  # parâmetros da requisição -> (hora de recebimento, corpo da resposta)


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 curta, uma nova tentativa
            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"))  # sem a chave no 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}

O handler não espera pausas maiores que 5 segundos: quando a cota acaba, Retry-After aponta para a renovação, que pode estar a dias de distância. O modelo recebe o código de status e conta ao usuário o que aconteceu: 403 significa plan_restricted, um endpoint fora do plano (erros da Genesis API).

OpenAPI como fonte das definições de ferramentas

OpenAPI é um padrão para descrições de APIs HTTP legíveis por máquina: uma operação é descrita por um operationId, um summary curto e parâmetros com esquemas. Na versão 3.1, o Schema Object é um superconjunto do JSON Schema 2020-12 (especificação OpenAPI 3.1), e o MCP lê inputSchema como JSON Schema 2020-12 por padrão. Assim os parâmetros passam para uma ferramenta sem conversão.

O script monta as ferramentas a partir da especificação da Genesis API: pega as operações que você quer, ignora as que ficam fora do seu plano segundo x-genesis-plans e transfere os parâmetros de query e de caminho. Os cabeçalhos ficam por conta do handler.

import requests

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


def tools_from_spec(wanted, plan):
    """wanted: operationId -> nome da ferramenta; 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  # não desejada ou fora do plano: 403 plan_restricted
        props, required = {}, []
        for prm in op.get("parameters", []):
            if "$ref" in prm or prm["in"] not in ("query", "path"):
                continue  # o handler envia 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  # nome da ferramenta -> caminho do endpoint
    return tools, routes


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

getFundingSpread vira uma ferramenta get_funding com os parâmetros coin e min_spread. Se você passar todas as operações, o Trial mantém 11 das 37 e o Start mantém 16. O dicionário routes guarda o caminho de cada ferramenta.

MCP: o seu próprio servidor sobre uma API REST

O MCP (Model Context Protocol) é um padrão aberto para conectar aplicações de IA a dados e ferramentas. A Anthropic o abriu como código aberto em 25 de novembro de 2024 (anúncio da Anthropic) e, em 9 de dezembro de 2025, o doou à Agentic AI Foundation, um fundo sob a Linux Foundation (blog do MCP).

O aplicativo com o modelo, o host, cria um cliente MCP por servidor. Um servidor expõe ferramentas, recursos e modelos de prompt via JSON-RPC 2.0: um servidor local via stdio, um remoto via Streamable HTTP, para o qual o MCP recomenda obter tokens por OAuth (arquitetura do MCP).

Function callingMCP
Onde as ferramentas são definidasNa requisição à API do modeloNo servidor; o cliente as obtém com tools/list
Quem executa a chamadaO código do seu aplicativoO servidor MCP, numa requisição tools/call
Onde funcionaNo aplicativo em que você escreveu o loopEm qualquer cliente com suporte a MCP

Envolver uma API REST em um servidor MCP leva quatro passos:

  1. Escolha as operações

    Pegue de 3 a 7 operações para a tarefa do agente; monte nomes, descrições e parâmetros das ferramentas a partir do OpenAPI, como no script acima.

  2. Devolva a lista em tools/list

    O servidor devolve name, description e inputSchema de cada ferramenta.

  3. Trate tools/call

    Valide os argumentos, faça uma requisição GET com a chave do ambiente do servidor e devolva um JSON compacto em um bloco content. Devolva um erro da API com isError: true: o modelo o usa para corrigir seus argumentos.

  4. Escolha o transporte

    Com stdio o servidor roda na sua máquina e a chave nunca sai dela. Coloque um servidor Streamable HTTP remoto atrás de autorização, ou qualquer um que descobrir a URL gastará a sua cota.

Existem SDKs oficiais do MCP para 10 linguagens, de Python e TypeScript a Go e Rust (lista de SDKs).

llms.txt e llms-full.txt

llms.txt é um arquivo Markdown em /llms.txt que ajuda modelos de linguagem a usar um site. Jeremy Howard propôs o formato em 3 de setembro de 2024 (llmstxt.org): a única parte obrigatória é um H1 com o nome, seguido de um resumo em citação e de seções com links para versões em Markdown das páginas.

A proposta não define o llms-full.txt: o nome é usado para uma documentação inteira em um único arquivo Markdown, e o site de documentação do MCP, por exemplo, o publica. O modelo não precisa seguir links, já que toda a referência vai para o seu contexto.

Segurança do agente

Guarde a chave em uma variável de ambiente no servidor: ela não deve aparecer em prompts, navegadores nem logs. Uma chave da Genesis API é somente leitura, então não consegue enviar uma ordem nem sacar fundos, e um vazamento custa cota. Substitua uma chave vazada com Reemitir no seu perfil (armazenamento de chaves).

A injeção de prompt é uma instrução para o modelo escondida nos dados. O nome de um token é definido por quem o implantou e o nome de um trader, pelo próprio trader, então um campo pode conter «ignore previous instructions». Na Genesis API, o texto externo chega nos campos title e outcome dos mercados de previsão, no name dos traders, no token_name on-chain e em message_ru e message_en dos sinais da Genesis AI+: informe no prompt de sistema que os resultados das ferramentas são apenas dados.

A especificação do MCP exige que os servidores validem as entradas das ferramentas, limitem a frequência das invocações e higienizem as saídas, e aconselha os clientes a confirmar operações sensíveis e registrar o uso das ferramentas (ferramentas do MCP). Registre o X-Request-Id: com ele, o horário em UTC, o endpoint e o status, o suporte consegue encontrar a requisição.

Os riscos da automação são tratados na lição 5 do curso de API de criptomoedas.

Custos e limites

Apenas uma resposta 200 consome a cota da Genesis API; 304 e erros são gratuitos, mas contam para o limite de requisições (rate limit) por segundo. Acima dos limites, o servidor responde 429 e não cobra nada.

PlanoPreçoCota e frequênciaAtualidade
Trial$20/mês500.000 chamadas, 1 req/s60 s
Start$50/mês2 mi de chamadas, 2 req/s30 s
Pro$100/mês5 mi de chamadas, 5 req/s10 s
Max$200/mês10 mi de chamadas, 15 req/s5 s

Exemplo ilustrativo: 500 perguntas por dia com 3 chamadas de ferramenta cada são 500 × 3 = 1.500 chamadas por dia e 1.500 × 30 = 45.000 em 30 dias, 9% da cota do Trial. O cache cobre as repetições com os mesmos parâmetros dentro de freshness_sec, e um teto de chamadas de ferramenta por resposta impede que um loop consuma a cota.

Consultar com mais frequência que meta.freshness_sec não traz nenhum snapshot novo. A consulta barata com ETag e novas tentativas está em Como consultar uma API de criptomoedas sem estourar os limites, e os limites, no guia Limites da Genesis API. Se o agente precisa só de regras e de nenhum modelo, um bot de arbitragem de criptomoedas em Python é mais simples.

Genesis API para agentes de IA

A Genesis API é uma API REST com dados da Genesis Arbitrage: spreads de CEX e DEX, livros de ofertas, funding, open interest, cross-chain, fluxos on-chain, mercados de previsão, surebets de casas de apostas e sinais de IA. As requisições são HTTP GET com o cabeçalho X-API-Key, as respostas são JSON com data e meta (formato de resposta), e nenhum SDK é necessário.

Publicado para agentes:

Não há servidor MCP oficial, nem WebSocket, nem endpoints de trading: o agente lê dados, e as operações ficam com uma pessoa. A configuração passo a passo está no guia Genesis API para agentes de IA.

Perguntas e respostas

Um agente de IA pode negociar criptomoedas sozinho?

Somente se você der a ele uma API de trading de exchange, e isso é o seu código e o seu risco. Não pela Genesis API: ela apenas lê dados. A especificação do MCP diz que uma pessoa deve sempre poder negar uma chamada de ferramenta; para operações, defina como regra que uma pessoa confirme cada ordem.

De qual plano da Genesis API um agente de IA precisa?

O Trial, a $20 por mês, cobre spreads de CEX, funding e open interest. O Start acrescenta ações, seções on-chain e arbitragem de mercados de previsão nos modos exact e dutch, enquanto o Pro e o Max abrem tudo, inclusive DEX e livros de ofertas. A velocidade de reação depende do limite por segundo e da atualidade do plano; o conteúdo dos planos está na página de preços da Genesis API.

Onde consigo a especificação da Genesis API para um agente?

O OpenAPI 3.1 está em genesisarbitrage.com/openapi.json, e a referência para o modelo, em genesisarbitrage.com/llms-full.txt. Um agente também pode encontrar os dois pelo catálogo /.well-known/api-catalog.

A Genesis API tem um servidor MCP?

Não há um oficial. Você monta o seu a partir dos mesmos handlers: uma ferramenta MCP é uma requisição GET a um endpoint com a chave do ambiente do servidor. Um exemplo mínimo em Python está no verbete MCP do glossário.