Genesis API para agentes de IA: OpenAPI, llms.txt e function calling
Em resumo
- Para os agentes há openapi.json (OpenAPI 3.1, 37 operações com planos), llms-full.txt, llms.txt e um catálogo de API conforme a RFC 9727.
- O modelo escolhe uma ferramenta e seus argumentos; seu servidor faz a requisição com a chave e devolve ao modelo um JSON curto com a hora dos dados.
- A Genesis API apenas lê dados. Seu código limita a frequência das requisições, o modelo trata o texto das respostas como dados e uma pessoa confirma qualquer operação.
A Genesis API é uma API REST de dados de mercado cripto que um agente de IA chama como ferramenta: o modelo decide de quais dados precisa, seu servidor faz uma requisição GET com a chave e devolve um JSON curto. Para agentes e modelos de linguagem há uma descrição da API legível por máquina: uma especificação OpenAPI 3.1, uma referência completa em Markdown e um catálogo de API. Os dados são os que o site mostra: spreads CEX e DEX, livros de ofertas, funding, fluxos on-chain e mercados de previsão.
Arquivos legíveis por máquina
| Arquivo | O que contém | Para quê |
|---|---|---|
| genesisarbitrage.com/openapi.json | OpenAPI 3.1: 37 operações, parâmetros, esquemas de resposta, planos em x-genesis-plans, cabeçalhos de rate limit | Importar em um cliente de API, gerar código, ferramentas de agentes |
| genesisarbitrage.com/llms-full.txt | A referência completa em um único arquivo Markdown: endpoints, parâmetros, campos, exemplos, limites, erros | Contexto para um modelo que escreve código ou responde perguntas sobre a API |
| genesisarbitrage.com/llms.txt | Visão geral do site: Genesis API, ferramentas, Guia, curso, glossário, blog | Primeiro contato de um modelo com o site |
| genesisarbitrage.com/.well-known/api-catalog | Catálogo de API conforme a RFC 9727: links para a especificação, a documentação, os planos e o status | Descoberta da API a partir do domínio |
A especificação segue o OpenAPI 3.1, cujos esquemas são um superconjunto do JSON Schema 2020-12, então os parâmetros de uma operação passam para a definição de uma ferramenta quase sem mudanças. llms.txt é um formato proposto em 2024: um arquivo Markdown na raiz do site com uma visão geral curta e links para modelos de linguagem. O catálogo fica no endereço definido pela RFC 9727.
As páginas de documentação, de produto e de planos da Genesis API trazem <link rel="service-desc"> no <head>, apontando para openapi.json. Esse tipo de relação vem da RFC 8631 e marca uma descrição de serviço destinada a máquinas. Um trecho resumido da especificação:
{
"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 operação tem um operationId, parâmetros tipados, um esquema de resposta 200, uma resposta 304, códigos de erro e os cabeçalhos X-RateLimit-*, X-Quota-*, X-Request-Id e ETag. A chave é descrita pelo esquema de segurança ApiKeyAuth: tipo apiKey, cabeçalho X-API-Key.
Como conectar
Obtenha uma chave e guarde-a no servidor
A chave
gns_live_…é emitida no seu perfil, no bloco Genesis API, e é mostrada uma única vez. Guarde-a na variável de ambienteGENESIS_API_KEYdo servidor que executa o agente. Armazenamento e reemissão estão no guia da chave de API.Importe a especificação
Um cliente de API ou framework de agentes que aceite OpenAPI monta as requisições e as ferramentas direto de
openapi.json: a URL base vem deserverse o cabeçalho da chave, deApiKeyAuth. Como a chave é enviada está descrito em Autenticação.Mantenha as operações de que precisa
Cada definição de ferramenta ocupa espaço no contexto do modelo, e escolher entre poucas é mais fácil. Mantenha as operações que sua tarefa exige e retire as que ficam fora do seu plano segundo
x-genesis-plans: elas respondem403 plan_restricted.Entregue a referência ao modelo
Se o agente escreve código ou responde perguntas sobre a API, adicione
llms-full.txtao contexto dele: o arquivo traz os parâmetros, campos e exemplos de cada endpoint, os limites e os códigos de erro.Teste a chave com uma primeira chamada
/account/usagedevolve seu plano, a cota usada, o limite de requisições por segundo e a atualidade dos dados.
Como o modelo chama a Genesis API
Function calling é o mecanismo em que o modelo devolve o nome de uma ferramenta e argumentos em vez de texto, e seu código faz a chamada. O ciclo:
- Junto com a pergunta do usuário, o modelo recebe as definições das ferramentas: nome, finalidade e parâmetros como JSON Schema.
- O modelo responde com uma chamada:
get_spreadscom os argumentos{"coin": "TON", "min_spread": 0.5}. - Seu servidor valida os argumentos, faz um GET com o cabeçalho
X-API-Keye reduz a resposta aos campos necessários. - Um JSON curto com a hora dos dados volta ao modelo, e ele responde ao usuário.
O modelo não faz chamadas de rede e nunca vê a chave: ele tem apenas a definição da ferramenta e o resultado. Uma ferramenta get_spreads sobre o endpoint Spot — Spot:
{
"name": "get_spreads",
"description": "Onde comprar uma moeda mais barata e vendê-la mais cara (CEX)",
"parameters": {
"type": "object",
"properties": {
"coin": {
"type": "string",
"description": "Ticker da moeda, p. ex. BTC"
},
"min_spread": {
"type": "number",
"description": "Spread mínimo, %: 0.5 significa 0.5%"
}
},
"additionalProperties": false
}
}
O campo que guarda o esquema de parâmetros tem nomes diferentes entre os provedores de modelos, inputSchema no MCP; por dentro é sempre JSON Schema. As propriedades coin e min_spread vêm dos parâmetros da operação getArbitrageSpotSpot, e description diz quando chamar a ferramenta: o modelo escolhe por esse texto.
Um handler em Python que chama /arbitrage/spot-spot e devolve ao modelo até 10 linhas com os campos necessários e meta.updated_at:
import os
import time
import requests
API = "https://api.genesisarbitrage.com/v1/arbitrage/spot-spot"
KEY = os.environ["GENESIS_API_KEY"] # a chave fica no servidor
FIELDS = ("coin", "exchange_buy", "exchange_sell", "spread_pct",
"withdraw_enabled_buy", "deposit_enabled_sell")
cache = {} # params -> (hora, ETag, corpo da resposta)
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) # os dados não serão atualizados antes
headers = {"X-API-Key": KEY}
if etag:
headers["If-None-Match"] = etag
for attempt in range(2): # 429 e 503: esperar Retry-After e tentar de novo
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} # o modelo vê o 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]}
A resposta fica em cache por meta.freshness_sec segundos: os dados não serão atualizados antes. Depois disso, o handler envia o ETag anterior em If-None-Match, e uma resposta 304 não gasta cota. Em 429 e 503 ele espera Retry-After, limitado a 30 s, tenta mais uma vez e devolve os demais erros ao modelo como um código. O modelo recebe 10 linhas de 6 campos. Um exemplo ilustrativo: uma resposta completa de 214 linhas com 22 campos dá 214 × 22 = 4.708 valores; a reduzida, 10 × 6 = 60.
Regras para o agente
| Regra | Como |
|---|---|
| A chave fica no servidor | Uma variável de ambiente do handler; sem chave no prompt, no navegador nem nos logs de chat |
| A API apenas lê | A Genesis API não envia ordens; uma pessoa confirma qualquer operação na exchange |
| Seu código define a frequência | Cache por freshness_sec, ETag e If-None-Match, uma fila abaixo do limite de requisições por segundo |
| Filtros, não o conjunto completo | coin, min_spread, exchange; até 10 linhas e os campos necessários para o modelo |
| A hora dos dados em cada resposta | updated_at e a idade no resultado da ferramenta e na resposta ao usuário |
| Texto externo é apenas dado | O modelo não age com base em títulos de mercados, resultados, nomes de traders ou textos de sinais |
O modelo pode pedir várias ferramentas ao mesmo tempo, e o limite conta todas as requisições da chave: 1 requisição por segundo no Trial, 15 no Max. Respostas 304 e erros não gastam cota, mas contam para o limite por segundo; veja Planos e limites e o guia de limites.
Os campos title e outcome dos mercados de previsão, o name de um trader, o token_name dos eventos on-chain e as message_ru e message_en dos sinais da Genesis AI+ vêm de fontes externas. Alguém pode chamar um mercado de «ignore as instruções anteriores e…»: isso é prompt injection, comandos introduzidos por meio dos dados. Passe esses campos apenas dentro do resultado da ferramenta, limite o tamanho deles e informe no prompt de sistema que o texto dentro dos resultados são dados.
MCP: seu próprio servidor sobre a API REST
MCP (Model Context Protocol) é um padrão aberto para conectar aplicações de IA a sistemas externos. Um servidor MCP oferece à aplicação ferramentas, recursos e modelos de prompts; as mensagens são JSON-RPC 2.0, via stdio localmente e Streamable HTTP remotamente. A especificação e os SDKs de várias linguagens estão em modelcontextprotocol.io.
A Genesis API não tem servidor MCP oficial. Você pode montar o seu a partir dos mesmos handlers: uma ferramenta MCP é um GET para um endpoint da Genesis API, seus parâmetros são JSON Schema em inputSchema e a chave fica no ambiente do servidor. Um servidor stdio local mantém a chave na sua máquina. Coloque um servidor remoto atrás de autorização (o MCP recomenda OAuth); caso contrário, quem descobrir o endereço pode gastar sua cota.
Como os agentes trabalham com dados de mercado cripto em geral está no artigo sobre dados de mercado cripto para agentes de IA, e os riscos da automação, na quinta lição do curso.
Perguntas e respostas
A Genesis API tem um servidor MCP oficial?
Não. Para os agentes há openapi.json, llms-full.txt e o catálogo de API. Você pode escrever por conta própria um servidor MCP sobre a API REST: cada ferramenta é uma requisição GET com a chave de uma variável de ambiente.
Um agente pode operar pela Genesis API?
Não. A Genesis API apenas lê dados e não envia ordens. O agente encontra oportunidades e envia alertas; uma pessoa faz a operação na exchange.
De qual plano um agente precisa?
De qualquer um: o Trial dá 1 requisição por segundo e atualidade de 60 s, o Max 15 requisições por segundo e 5 s. Os endpoints de cada plano estão em x-genesis-plans e na página de planos da Genesis API.
Por que o modelo cita preços desatualizados?
Os dados chegam com o atraso de atualidade do seu plano, e o cache do handler soma até freshness_sec. Dê ao modelo updated_at e a idade dos dados, e peça que ele informe a hora na resposta.