Genesis Arbitrage

Genesis Arbitrage · · 11 min de leitura

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

ArquivoO que contémPara quê
genesisarbitrage.com/openapi.jsonOpenAPI 3.1: 37 operações, parâmetros, esquemas de resposta, planos em x-genesis-plans, cabeçalhos de rate limitImportar em um cliente de API, gerar código, ferramentas de agentes
genesisarbitrage.com/llms-full.txtA referência completa em um único arquivo Markdown: endpoints, parâmetros, campos, exemplos, limites, errosContexto para um modelo que escreve código ou responde perguntas sobre a API
genesisarbitrage.com/llms.txtVisão geral do site: Genesis API, ferramentas, Guia, curso, glossário, blogPrimeiro contato de um modelo com o site
genesisarbitrage.com/.well-known/api-catalogCatálogo de API conforme a RFC 9727: links para a especificação, a documentação, os planos e o statusDescoberta 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

  1. 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 ambiente GENESIS_API_KEY do servidor que executa o agente. Armazenamento e reemissão estão no guia da chave de API.

  2. 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 de servers e o cabeçalho da chave, de ApiKeyAuth. Como a chave é enviada está descrito em Autenticação.

  3. 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 respondem 403 plan_restricted.

  4. Entregue a referência ao modelo

    Se o agente escreve código ou responde perguntas sobre a API, adicione llms-full.txt ao contexto dele: o arquivo traz os parâmetros, campos e exemplos de cada endpoint, os limites e os códigos de erro.

  5. Teste a chave com uma primeira chamada

    /account/usage devolve 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:

  1. Junto com a pergunta do usuário, o modelo recebe as definições das ferramentas: nome, finalidade e parâmetros como JSON Schema.
  2. O modelo responde com uma chamada: get_spreads com os argumentos {"coin": "TON", "min_spread": 0.5}.
  3. Seu servidor valida os argumentos, faz um GET com o cabeçalho X-API-Key e reduz a resposta aos campos necessários.
  4. 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

RegraComo
A chave fica no servidorUma 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ênciaCache por freshness_sec, ETag e If-None-Match, uma fila abaixo do limite de requisições por segundo
Filtros, não o conjunto completocoin, min_spread, exchange; até 10 linhas e os campos necessários para o modelo
A hora dos dados em cada respostaupdated_at e a idade no resultado da ferramenta e na resposta ao usuário
Texto externo é apenas dadoO 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.