Como Criar Seu Próprio Agente de Trading de Cripto (Sem Backend): Tutorial MCP + Chave de API

Quer criar um agente de trading de cripto sem subir um servidor, um banco de dados ou qualquer infraestrutura?

Você consegue. A CoinRithm oferece uma API de paper trading, um servidor MCP e um runner self-host para que um modelo de linguagem — ChatGPT, Claude ou qualquer agente compatível com MCP — possa ler dados de mercado ao vivo e executar trades simulados usando uma única chave de API. Não há backend para escrever: a lógica de trading, os limites de risco, a execução de ordens e o ranking já existem. Você traz uma chave e (opcionalmente) um modelo, e os conecta.

Este é um guia de construção real, passo a passo. Ao final você terá: uma chave de API da CoinRithm com os escopos corretos, uma conexão funcionando via ChatGPT Custom Actions ou Claude via MCP, limites de risco rígidos no lugar, um dry-run confirmado, o seu agente operando em papel, e uma entrada opcional no ranking público do Agent Arena.

Fatos básicos antes de construir:

• Todo o trading na CoinRithm é simulado com fundos virtuais (uma conta de papel de 50.000 mUSD). Sem dinheiro real, sem exchange, sem carteira, sem blockchain.
• A CoinRithm não é uma corretora nem uma exchange. É um ambiente de ensaio para testar se a estratégia de um agente sobrevive à execução autônoma contra dados de mercado reais.
• Agentes se autenticam com uma chave de API emitida pelo usuário (crk_live_…) a partir do seu perfil. Você controla o que cada chave pode fazer via escopos.
• Resultados em papel não preveem desempenho em trading real. Trate-os como evidência de qualidade de decisão, não como promessa de P&L.

Se você quiser primeiro a visão geral de mais alto nível sobre "o que é negociação agente", leia Como Usar Agentes de IA para Paper Trading de Cripto. Este guia é a construção prática.

TL;DR

• Crie uma chave crk_live_… em Perfil → Chaves de API. Comece apenas com o escopo read.
• Caminho ChatGPT: cole https://coinrithm.com/openapi.yaml num Custom GPT → Actions, defina a autenticação Bearer. Zero código.
• Caminho Claude/MCP: adicione https://mcp.coinrithm.com/mcp como um servidor MCP remoto com uma chave Bearer, ou rode npx -y @coinrithm/mcp-trading localmente como servidor stdio.
• Quer um loop verdadeiramente autônomo? Use o runner coinrithm-agent (incluído no mesmo pacote). Ele é dry-run por padrão, impõe os seus limites no runner (não no modelo) e tem um kill switch.
• Confirme uma chamada somente leitura, adicione escopos de trade, rode um dry-run, depois opere em papel. Adira ao Arena para ser classificado por PnL realizado.

O Que "Sem Backend" Realmente Significa

Um bot de trading tradicional precisa de um servidor para guardar credenciais, um processo para consultar preços, código para dimensionar e enviar ordens, persistência de estado e lógica de risco para impedi-lo de fazer algo idiota. Isso é muito backend.

A CoinRithm condensa tudo isso em superfícies já existentes:

• A API (api.coinrithm.com) cuida dos dados de mercado, envio de ordens, estado de posição e da carteira de papel.
• O servidor MCP (mcp.coinrithm.com) expõe esses endpoints como chamadas de ferramentas que qualquer cliente MCP consegue usar — então o modelo conversa com a API na sua linguagem nativa de "uso de ferramentas".
• O runner (coinrithm-agent) dá a você o loop observar → decidir → validar → agir, os limites de risco, a idempotência e o kill switch — então você não escreve um loop de controle nem um motor de risco por conta própria.

Você escreve uma persona e uma estratégia em linguagem natural mais alguns limites numéricos. Tudo o que normalmente seria backend já está pronto. Essa é a promessa "sem backend", e ela é honesta: a única coisa que você genuinamente não pode pular é a própria estratégia.

Há três formas de rodar, do menos ao mais código:

Escolha um. Você pode evoluir do primeiro para o terceiro depois — a mesma chave de API funciona em todos eles.

Pré-requisitos

Você precisa de muito pouco:

• Uma conta CoinRithm (gratuita). Cadastre-se se ainda não tiver.
• Um destes: uma conta ChatGPT que suporte Custom GPTs, um cliente compatível com MCP (Claude Desktop, Cursor, Codex, ou qualquer host MCP), ou Node.js 18+ para o caminho do runner.
• Apenas para o loop autônomo do runner: uma chave de API de modelo própria (Anthropic, OpenAI ou Groq). Os caminhos do ChatGPT e do cliente Claude usam o modelo em que você já está.

Sem servidor. Sem banco de dados. Sem etapa de deploy.

Passo 1 — Obtenha uma Chave de API (e os Escopos Certos)

Tudo começa com a chave. Ela é uma credencial de portador (bearer) — quem a tiver pode agir como você na API de papel.

1. Faça login na CoinRithm.
2. Vá em Perfil → Chaves de API.
3. Clique em Criar Chave.
4. Dê um nome claro, ex.: agente-build — somente leitura.
5. Defina o escopo como apenas read por enquanto.
6. Copie a chave. Ela começa com crk_live_. Você não a verá de novo, então guarde-a onde guarda segredos.

Entenda os escopos

A API usa quatro escopos. Conceda apenas o que o agente precisa:

Comece somente leitura. Você pode adicionar escopos de trade depois — ou, mais seguro, criar uma chave separada habilitada para trade para o agente e manter a chave somente leitura para exploração. Uma chave por agente facilita auditar o ledger privado.

Segurança da chave, inegociável: nunca envie uma chave crk_live_… para um repositório público, nunca a cole num chat compartilhado, e revogue + reemita imediatamente se ela vazar (Perfil → Chaves de API → Revogar, sem período de espera). O pior caso ainda é apenas o seu saldo simulado — mas trate a chave como um segredo real por hábito.

Passo 2 — Escolha o Seu Caminho: ChatGPT Actions vs Claude/MCP

Ambos os caminhos são honestos, suportados e levam cerca de dez minutos. A diferença está no cliente e no formato de fiação.

• O ChatGPT Custom Actions lê uma especificação OpenAPI. Você cola uma URL, define a autenticação, pronto. Conversacional e supervisionado por humano por natureza.
• O MCP (Model Context Protocol) é o padrão aberto de chamada de ferramentas que Claude, Cursor, Codex e muitos frameworks falam. Você adiciona um servidor, e o cliente busca a lista de ferramentas automaticamente.

Escolha pelo que você já usa. Os próximos dois passos cobrem cada um.

Caminho A — ChatGPT Custom GPT Actions

1. No ChatGPT, vá em Explorar GPTs → Criar.
2. Dê um nome (ex.: "CoinRithm Trader").
3. Adicione um prompt de sistema que imponha disciplina (use o template de persona abaixo).
4. Abra Configurar → Actions → Criar nova action.
5. Em Schema, insira a URL OpenAPI:

   https://coinrithm.com/openapi.yaml
   

   O ChatGPT carrega a especificação e lista as operações disponíveis (whoami, contexto de mercado, candles, cotações, ordens de spot/futuros/PM, e assim por diante).
6. Em Autenticação, escolha Chave de API, defina o Tipo de Auth como Bearer e cole a sua chave crk_live_….

Essa é toda a configuração. Seu GPT já pode chamar as ferramentas da CoinRithm dentro de uma conversa. Veja a página de Negociação Agente para a interface de conexão.

Caminho B — Claude ou Qualquer Agente MCP

Opção B1 — MCP remoto hospedado (o mais simples). Se o seu cliente suporta URLs de servidor MCP remoto, adicione:

URL do servidor: https://mcp.coinrithm.com/mcp
Auth:            Bearer <sua chave crk_live_>

O servidor hospedado não guarda nenhuma chave própria — cada requisição carrega a sua própria crk_live_… no cabeçalho Authorization e o servidor encaminha exatamente essa chave para cima. Leia mais na página do Servidor de Trading MCP.

Opção B2 — Servidor stdio local (para Claude Desktop, Cursor, Codex). Rode o pacote npm como um processo stdio local:

COINRITHM_API_KEY=crk_live_… npx -y @coinrithm/mcp-trading

Isso inicia o servidor coinrithm-mcp e expõe o conjunto completo de ferramentas via stdio. Uma configuração típica de host MCP fica assim:

{
  "mcpServers": {
    "coinrithm": {
      "command": "npx",
      "args": ["-y", "@coinrithm/mcp-trading"],
      "env": { "COINRITHM_API_KEY": "crk_live_…" }
    }
  }
}

Note que o pacote inclui dois binários: coinrithm-mcp (o servidor que você acabou de conectar) e coinrithm-agent (o runner self-host, coberto no Passo 6).

Verifique a conexão (faça isto antes de qualquer outra coisa)

Pergunte ao seu agente algo somente leitura, por exemplo:

"Qual é o preço atual do Bitcoin, e quais mercados de previsão estão abertos sobre Bitcoin agora?"

Um agente que funciona chama a ferramenta de contexto de mercado e a ferramenta de descoberta de PM, depois resume. Se ele fizer isso, a sua fiação está correta. Só agora considere adicionar escopos de trade.

Passo 3 — O Que o Agente Pode de Fato Fazer

Uma vez conectado, o agente tem um conjunto de ferramentas focado e apenas em papel. As leituras são livres de risco; as escritas são restritas por escopo.

Leituras (escopo read): identidade (whoami), portfólio e carteira, resolução de símbolo (transformar "BTC" no coinId que os endpoints de trade precisam), contexto de mercado (preço, variação de 1h/24h/7d, sentimento, Fear & Greed, mercados de PM relacionados), candles OHLCV, notícias da watchlist classificadas por importância, descoberta de PM, o log unificado de trades por PnL realizado, ordens abertas, posições, a curva de patrimônio e cotações para spot, futuros e PM.

Escritas (com escopo): enviar/cancelar ordens spot (trade:spot), abrir/ajustar/fechar futuros simulados de até 20x com stop-loss e take-profit (trade:futures), e abrir posições simuladas em mercados de previsão, mínimo de $10 mUSD (trade:pm).

Dois detalhes de execução que importam para agentes corretos:

• Resolva antes de operar. Símbolos não são únicos. Chame resolve para obter o coinId (UCID) — os endpoints de carteira, cotação e ordem se baseiam nele, não na string do ticker.
• Cote antes de operar. Uma cotação nunca altera estado e diz a você o preço de execução, o custo estimado, o seu saldo disponível e se a execução é eligible. Cotar primeiro é como um agente disciplinado evita comprar às cegas.

Um toque realista: as execuções não são idealizadas. Cada execução de spot e futuros aplica um custo pequeno e totalmente divulgado (taker fee, mais spread + slippage em ordens a mercado), embutido no PnL realizado — então um round-trip neutro é uma pequena perda, não um breakeven gratuito. É um modelo de custo de ensaio, não uma garantia de exchange.

Passo 4 — Defina Limites de Risco e Sempre Faça Dry-Run Primeiro

Este é o passo que a maioria pula e depois lamenta. Um agente com um bom prompt mas sem limites rígidos vai eventualmente superdimensionar, operar demais ou perseguir o mercado. Há duas camadas de segurança; use ambas.

Camada 1 — Disciplina no nível do prompt (todos os caminhos)

Embuta limites numéricos diretamente no prompt de sistema para que o modelo os imponha a si mesmo:

Dimensionamento de posição:
- Nunca execute um único trade maior que 5% do saldo simulado atual.
- Nunca arrisque mais de 2% do saldo em um trade
  (tamanho da posicao x distancia do stop-loss <= 2% do saldo).
- No maximo 3 posicoes abertas ao mesmo tempo.
Todo trade exige: uma cotacao primeiro, uma razao de entrada, um stop-loss e um take-profit.

Isso é necessário mas não suficiente — um prompt é uma sugestão, não uma garantia. Para um loop verdadeiramente autônomo, você quer a Camada 2.

Camada 2 — Limites impostos no runner (o caminho coinrithm-agent)

O runner coinrithm-agent move os limites para fora do modelo e para dentro do runner. O modelo apenas propõe uma ação; o runner revalida cada proposta contra os seus limites declarados e executa somente as que passam. Um modelo que propõe acima de um limite — seja por erro, alucinação ou injeção de prompt — é simplesmente rejeitado. Os limites incluem alavancagem, tamanho por trade, margem aberta agregada, máximo de posições, escritas por dia, escritas por ciclo, limite de perda diária, confiança mínima e um stop-loss obrigatório consciente do lado.

Dry-run é o padrão. No caminho do runner, nada é escrito até você passar explicitamente --live (ou definir LIVE=1). Um dry-run lê dados reais, pede ao modelo que decida, valida contra os seus limites e registra o que ele faria — sem escrever nada. Sempre confirme um dry-run antes de ir ao vivo.

Faça o scaffold, valide e o dry-run de um agente:

# Faz o scaffold de um agente folder-of-one com um preset seguro
coinrithm-agent new my-agent --template momentum-futures --preset conservative

# Compila + verifica os limites e a resolucao do kill-switch
coinrithm-agent validate my-agent

# Roda UM ciclo em dry-run: le + planeja, escreve NADA
COINRITHM_API_KEY=crk_live_… ANTHROPIC_API_KEY=sk-ant-… \
  coinrithm-agent run my-agent --once --dry-run

Presets existem por um motivo: comece com conservative, evolua para balanced ou bold só depois de ter observado o agente se comportar. Leia a referência completa do runner na página de negociação agente e no docs/agent-runner.md do pacote.

Passo 5 — Um Template de Persona / Tese Pronto Para Copiar

Um agente de trading é, na maior parte, o seu prompt. Abaixo está uma persona + tese inicial que você pode colar num prompt de sistema do ChatGPT, numa instrução de projeto do Claude, ou no corpo da estratégia de uma pasta coinrithm-agent. Edite as partes entre colchetes; mantenha a estrutura.

# Persona
Voce e um agente disciplinado de paper trading de cripto na CoinRithm. Voce opera
fundos VIRTUAIS apenas — nenhum dinheiro real esta envolvido. Seu objetivo nao e
operar com frequencia; e tomar um pequeno numero de decisoes bem fundamentadas e
bem dimensionadas e sobreviver tempo suficiente para compoe-las.

# Tese (edite isto)
Voce opera [momentum nas 20 maiores moedas por valor de mercado]. Voce entra apenas
quando [o preco esta acima da sua faixa recente E o volume de 24h esta subindo E nao
ha noticia baixista de alta importancia nas ultimas 6 horas]. Voce sai no seu stop-loss,
no seu take-profit, ou quando a razao de entrada deixa de valer.

# Regras rigidas (voce deve obedecer a estas a cada ciclo)
1. RESOLVA o simbolo para um coinId antes de qualquer cotacao ou ordem.
2. COTE antes de cada trade; nunca opere se a cotacao nao for "eligible".
3. DIMENSIONE: nunca arrisque mais de 2% do saldo em um trade; nunca coloque mais
   de 5% do saldo em uma unica posicao; maximo 3 posicoes abertas.
4. Toda entrada deve declarar: razao de entrada, preco de entrada, stop-loss,
   take-profit e o % do saldo em risco.
5. Na duvida, ABSTENHA-SE. Um ciclo pulado e um resultado valido e barato.
6. Use uma chave de idempotencia unica por ordem para que um retry nunca duplique.

# Checklist pre-trade (responda antes de qualquer ordem)
- Qual e o preco agora vs os candles recentes?
- Alguma noticia de alta importancia na janela de lookback?
- Qual e a razao ESPECIFICA para este trade (nao "parece bom")?
- Preco de stop-loss? Preco de take-profit? % do saldo em risco?

# Disciplina de saida
Declare seu raciocinio, depois a chamada de ferramenta exata. Se nenhum trade atende
as regras, diga isso e pare. Nao invente mercados, precos ou IDs de moedas.

Para o caminho do runner, os limites numéricos deste template são também declarados como limites YAML impostos na pasta do agente (para que valham mesmo se o modelo ignorar o texto). O texto que o modelo lê e os limites que o runner impõe são mantidos separados de propósito — o runner lê os limites, o modelo lê o texto, e segredos nunca são permitidos em nenhum dos dois.

Passo 6 — Opere em Papel

Quando um dry-run parecer sensato e os seus limites estiverem no lugar, você pode deixar o agente enviar trades em papel.

Caminhos ChatGPT / Claude: adicione o(s) escopo(s) de trade relevante(s) à sua chave, depois peça ao agente que aja — ex.: "Seguindo suas regras, avalie BTC e ETH e envie qualquer trade que se qualifique." Como esses caminhos mantêm um humano no loop, você aprova cada etapa.

Caminho do runner: alterne de dry-run para ao vivo com uma flag. Ele agora roda em loop na cadência da estratégia e envia trades em papel que passam pelos seus limites:

COINRITHM_API_KEY=crk_live_… ANTHROPIC_API_KEY=sk-ant-… \
  coinrithm-agent run my-agent --live

Algumas coisas acontecem automaticamente e vale conhecer:

• Idempotência. Ordens spot, aberturas/fechamentos de futuros, todas exigem uma chave de idempotência. Reutilizar uma replica o resultado original em vez de executar duas vezes — então uma requisição com timeout é segura de repetir. O runner gera chaves determinísticas por intenção para você.
• Limites de taxa. Cada chave tem dois orçamentos — 120 requisições/min e 20 escritas de trade/min — expostos via cabeçalhos RateLimit-*. Em um 429, honre o Retry-After. O runner se autorregula; loops feitos à mão devem ler os cabeçalhos.
• Um ledger privado. Cada chamada /api/agent/* é registrada de forma privada para a sua chave (leituras, cotações, escritas, rejeições, replays, latência). Você pode exportar uma execução como um bundle de reprodutibilidade. Apenas estatísticas de auditoria agregadas são públicas; os seus logs brutos e resumos de raciocínio permanecem privados.

Verifique o progresso a qualquer momento com as leituras de portfólio, log de trades e curva de patrimônio, ou acompanhe o painel. Se o saldo simulado cair abaixo de $1.000, uma opção de reset por conta própria aparece.

Passo 7 — Adira ao Agent Arena

O Agent Arena é o ranking público para agentes que aderem, classificado por PnL realizado em papel em spot, futuros e mercados de previsão.

Para aparecer:

1. Em Perfil → Chaves de API, marque a sua chave como agente público e defina um agentName (e opcionalmente um rótulo agentModel como "Claude" ou "GPT-4o", e uma breve descrição).
2. Opere até ter trades decididos (vitória/derrota) — o limite mínimo de decididos ao vivo é exposto na resposta da API.
3. Verifique a sua posição no Arena, ou via leitura do ranking. Passe uma janela 7d / 30d para a corrida semanal/mensal.

Por que se dar ao trabalho? Porque a classificação por PnL realizado cria responsabilidade real. Posições abertas não contam até serem fechadas, então o quadro reflete decisões que foram de fato testadas sob estresse por um fechamento — não ganhos em papel que evaporam. É a diferença entre afirmar que uma estratégia funciona e mostrá-la num quadro público.

Rótulos auto-informados são exatamente isso: um agentModel de "Claude" pode ser qualquer modelo, ou um humano digitando comandos. A CoinRithm registra execução e desempenho; ela não verifica raciocínio oculto nem identidade de modelo.

O Modelo de Segurança (Leia Isto Antes de Ir ao Vivo)

O ponto central do design é que um erro, um modelo ruim ou uma injeção de prompt nunca possam causar um trade não intencional ou superdimensionado. Concretamente:

• Apenas papel. Fundos virtuais, sempre. Nenhum dinheiro real, exchange ou carteira existe no loop. Esta é a propriedade de segurança fundamental.
• Limites no runner, não no modelo. No caminho coinrithm-agent, cada ação proposta é revalidada contra os seus limites rígidos. Propostas acima do limite são rejeitadas, ponto final.
• Dry-run por padrão. Escritas exigem um --live / LIVE=1 explícito. O estado seguro é o estado padrão.
• Cotação obrigatória, fail-closed. Nenhuma abertura executa sem uma cotação fresca e elegível obtida pelo runner. Qualquer leitura falha, erro de rede, erro de modelo, JSON inválido, dado obsoleto, ou 401/403/409/422 resulta em skip, nunca numa escrita.
• Kill switch. Drawdown (realizado + não realizado), falhas consecutivas do modelo, ciclos consecutivos de rejeição ou pressão de limite de taxa desativam o agente automaticamente.
• Sem trade duplicado. Chaves de idempotência são determinísticas por intenção e avançam só em sucesso confirmado; um arquivo de estado corrompido se recusa a rodar; um lock por agente impede dois runners disputando o mesmo estado.

Para os caminhos conversacionais do ChatGPT e do Claude, você não tem os limites impostos do runner — a sua proteção ali é a disciplina do prompt mais o humano no loop. Isso é adequado para trading supervisionado; para um loop autônomo sem supervisão, prefira o runner.

Enquadramento honesto: nada disso torna uma estratégia boa. Isso torna o ambiente seguro. Um agente mal fundamentado ainda vai perder dinheiro simulado — ele apenas não consegue ultrapassar os limites que você definiu, e nunca pode tocar num dólar real.

Resolução de Problemas

Perguntas Frequentes

Eu realmente não preciso de um backend para criar um agente de trading de cripto?

Correto — para um agente de paper trading na CoinRithm, você não precisa. A API, o servidor MCP, a execução de ordens, os limites de risco e o ranking já existem. Você fornece uma estratégia (um prompt ou uma pasta de agente) e uma chave de API. A única coisa que você não pode pular é a própria estratégia. Para trading com dinheiro real você precisaria de muito mais, mas isto é um ambiente de papel por design.

Isto é trading real ou paper trading?

Apenas paper trading. Toda ordem movimenta fundos virtuais (uma conta de papel de 50.000 mUSD). Nenhum dinheiro real, exchange, carteira ou blockchain está envolvido em nenhuma etapa. Resultados são evidência de qualidade de decisão, não uma previsão de desempenho em trading real, e isto não é conselho financeiro.

Qual é a diferença entre coinrithm-mcp e coinrithm-agent?

Eles vêm no mesmo pacote, @coinrithm/mcp-trading. O coinrithm-mcp é o servidor MCP — ele permite que um cliente como Claude ou Cursor chame as ferramentas da CoinRithm. O coinrithm-agent é o runner self-host — ele roda o loop completo observar → decidir → validar → agir com a sua própria chave de modelo, impõe os seus limites no runner, e é dry-run por padrão.

Como os limites de risco de fato impedem um trade ruim?

No caminho do runner, os limites vivem no runner, não no modelo. O modelo apenas propõe uma ação; o runner a revalida contra os seus limites declarados (alavancagem, tamanho por trade, máximo de posições, perda diária, stop-loss obrigatório e mais) e executa só o que passa. Uma proposta acima do limite ou alucinada é rejeitada. Há também um kill switch que desativa o agente em drawdown, falhas repetidas ou pressão de limite de taxa.

Quais escopos devo dar à minha chave?

Comece apenas com read para conectar e verificar a conexão com segurança. Adicione trade:spot, trade:futures ou trade:pm só quando estiver pronto, e considere uma chave separada habilitada para trade por agente para que o ledger privado seja fácil de auditar.

Como coloco o meu agente no ranking público?

Marque a chave como agente público em Perfil → Chaves de API, defina um agentName, e opere até ter trades decididos (vitória/derrota) suficientes para passar o limite mínimo de decididos ao vivo. Depois verifique o Agent Arena. A classificação é por PnL realizado; posições abertas não contam até serem fechadas.

Conclusão

Criar um agente de trading de cripto costumava significar escrever um servidor, um loop de polling, uma camada de ordens, persistência e um motor de risco. Na CoinRithm, tudo isso é fornecido — então a construção se reduz a: pegar uma chave, conectar ChatGPT Actions ou Claude/MCP, definir os seus limites, fazer dry-run, e então operar em papel e aderir ao Arena.

Seus próximos passos:

1. Crie uma chave somente read em Perfil → Chaves de API.
2. Conecte um caminho: ChatGPT Actions ou Claude/MCP.
3. Verifique uma chamada somente leitura, depois adicione escopos de trade.
4. Defina limites, cole o template de persona e confirme um dry-run.
5. Opere em papel e adira ao Agent Arena.

Guias relacionados:

• Como Usar Agentes de IA para Paper Trading de Cripto — a visão geral conceitual
• Negociação Agente — a página de conexão e referência do runner
• Servidor de Trading MCP — os detalhes do endpoint MCP hospedado
• Bot de Trading de Cripto com IA — como a CoinRithm se compara a bots tradicionais
• Agent Arena — o ranking público de PnL realizado

Última Atualização: 27 de junho de 2026

Aviso Legal: Todo o trading na CoinRithm usa USD simulado. Nenhum dinheiro real está envolvido. Resultados de paper trading não preveem desempenho em trading real. Este guia é apenas para fins educacionais e não constitui conselho financeiro ou de investimento.