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 precisa | De onde vem | Exemplo |
|---|---|---|
| Caminhos, parâmetros e campos da API | Referência no contexto | llms-full.txt, openapi.json |
| Preços, spreads, taxas | Chamada de ferramenta | GET /funding/spread?coin=TON |
| Hora atual e idade dos dados | Prompt de sistema e resultado da ferramenta | updated_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"]
}
]
}
}
- O aplicativo envia ao modelo a pergunta e as definições das ferramentas: nome, finalidade e um esquema de argumentos em JSON Schema.
- O modelo devolve uma chamada
get_fundingcom os argumentos{"coin": "TON"}. - O seu código valida os argumentos, envia
GET /funding/spread?coin=TONcom o cabeçalhoX-API-Keye reduz a resposta. - 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.
- 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.
| Ferramenta | Endpoint da Genesis API | Planos |
|---|---|---|
get_spreads | /arbitrage/spot-spot | Todos |
get_funding | /funding/spread | Todos |
get_prediction_arbs | /predictions/arbitrage | Start, Pro, Max |
get_book | /orderbooks/book | Pro, 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 calling | MCP | |
|---|---|---|
| Onde as ferramentas são definidas | Na requisição à API do modelo | No servidor; o cliente as obtém com tools/list |
| Quem executa a chamada | O código do seu aplicativo | O servidor MCP, numa requisição tools/call |
| Onde funciona | No aplicativo em que você escreveu o loop | Em qualquer cliente com suporte a MCP |
Envolver uma API REST em um servidor MCP leva quatro passos:
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.
Devolva a lista em tools/list
O servidor devolve
name,descriptioneinputSchemade cada ferramenta.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 comisError: true: o modelo o usa para corrigir seus argumentos.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.
| Plano | Preço | Cota e frequência | Atualidade |
|---|---|---|---|
| Trial | $20/mês | 500.000 chamadas, 1 req/s | 60 s |
| Start | $50/mês | 2 mi de chamadas, 2 req/s | 30 s |
| Pro | $100/mês | 5 mi de chamadas, 5 req/s | 10 s |
| Max | $200/mês | 10 mi de chamadas, 15 req/s | 5 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:
openapi.json— OpenAPI 3.1: 37 operações, esquemas de resposta e planos emx-genesis-plans;llms-full.txt— a referência completa em um único arquivo Markdown;llms.txt— uma visão geral do site para modelos de linguagem;/.well-known/api-catalog— um catálogo conforme a RFC 9727 que aponta para a especificação, a documentação e a página de status.
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.