Conecte seu agente de IA.

Endereço

Um endereço só, para todos os agentes:

O servidor fala o MCP pelo transporte Streamable HTTP. O endereço antigo, com /mcp no final, continua valendo. Quem abre o endereço no navegador vem para este site.

Como conectar

Informe só o endereço ao seu agente. Ele abre a TroiaQuants no navegador, você entra com e-mail e senha (quem já está no app não digita de novo) e escolhe o que o agente pode fazer. Não precisa copiar chave nenhuma.

Claude

No claude.ai e nos aplicativos do Claude: Configurações → Conectores → Adicionar conector personalizado, com o endereço acima.

Claude Code

claude mcp add --transport http troiaquants https://mcp.troiaquants.com

Cursor e outros clientes

No Cursor, em .cursor/mcp.json; nos outros clientes que aceitam servidores remotos, no arquivo de configuração deles:

{
  "mcpServers": {
    "troiaquants": { "url": "https://mcp.troiaquants.com" }
  }
}

Com uma chave de API

Para clientes que não abrem o navegador, ou para os seus próprios programas: crie a chave no app, em Chaves de API, com as permissões que quiser, e mande no cabeçalho Authorization: Bearer tq_... (o cabeçalho X-API-Key também serve).

claude mcp add --transport http troiaquants https://mcp.troiaquants.com --header "Authorization: Bearer tq_SUA_CHAVE"

{
  "mcpServers": {
    "troiaquants": {
      "url": "https://mcp.troiaquants.com",
      "headers": { "Authorization": "Bearer tq_SUA_CHAVE" }
    }
  }
}

Clientes que só aceitam servidores locais podem usar a ponte mcp-remote:

{
  "mcpServers": {
    "troiaquants": {
      "command": "npx",
      "args": ["mcp-remote", "https://mcp.troiaquants.com", "--header", "Authorization: Bearer tq_SUA_CHAVE"]
    }
  }
}

A conexão aparece no app, em Chaves de API, com o nome do aplicativo (por exemplo, Claude (agente de IA)). Revogar ali corta o agente na hora.

Permissões

Na hora de entrar, você marca o que o agente pode fazer. Sem a permissão, a ferramenta nem aparece para ele. Para mudar as permissões, conecte de novo: no Claude, em Configurações, Conectores, TroiaQuants, desconecte e conecte outra vez, marcando o que quiser.

Leitura · sempre

Vê contas, cotações, candles, livro de ofertas, posições, ordens e histórico, os seus experts e os testes deles, e os experts ao vivo com o diário de cada um.

Negociação

Também envia, altera e cancela ordens, e liga, pausa, retoma, zera e para experts ao vivo. Em conta real, isso movimenta dinheiro de verdade: para testar, prefira uma conta demo.

Contas

Também cadastra, altera e remove as suas contas de corretora. As senhas vão criptografadas e nunca voltam.

Backtests

Também escreve, altera e remove experts e roda testes no histórico, otimizações e janelas que avançam nos servidores da plataforma, pagos com créditos.

Contas e corretoras

Você conecta as contas de corretora no app, reais e demo (ou o agente, com a permissão Contas). Cada conta é chamada pelo número dela na corretora, o login; o servidor só é preciso quando o mesmo número existe em duas corretoras. Por isso o agente começa sempre por accounts_list.

accounts_list diz também se cada conta está conectada e, quando não está, o motivo e quando sai a próxima tentativa. Uma conta sem conexão com a corretora não lê nem opera.

• Volumes em lotes (contratos ou ações, conforme o ativo), preços absolutos e horários na hora do servidor da corretora.
• O nome do ativo é o exato da corretora: symbols_get com WIN* mostra os contratos do índice, e o agente escolhe o vigente.
• Os nomes das ferramentas e os campos das respostas seguem as funções de negociação de sempre (account_info, positions_get, order_send…) e são os mesmos da API REST.
• O agente só enxerga as contas do seu usuário.

Experts

Um expert é um robô que opera sozinho numa conta. É um arquivo JavaScript que exporta uma classe que estende Expert, do SDK @troiaquants/sdk. Ele só importa o SDK e roda isolado, sem internet, sem arquivos e sem tela: tudo o que usa — cotações, candles, indicadores, posições e ordens — vem de this. O mesmo arquivo roda ao vivo e no teste no histórico.

import { Expert, input } from '@troiaquants/sdk';

export default class MeuExpert extends Expert {
  static title = 'Meu expert';

  volume = input.double(1, { label: 'Volume' });   // cada input é um parâmetro

  async OnInit() { /* uma vez, ao começar: crie os indicadores */ }
  async OnBar() { /* a cada candle novo: decida e envie as ordens */ }
}

• Antes de escrever ou alterar um expert, o agente lê expert_guide: as regras, as funções e três exemplos completos.
• expert_add guarda o arquivo e lê dele o nome e os parâmetros. Se o arquivo tiver um erro, a resposta diz qual: o agente corrige e manda de novo.
• Cada expert marca as ordens com um número mágico (magic), que separa as posições dele das outras da conta.

Todos os eventos, funções e indicadores estão no SDK.

Testes e créditos

Pelo agente, os testes no histórico rodam nos servidores da plataforma, num lugar isolado, e custam créditos. credits_get diz o saldo e o preço de um teste (hoje, 100 créditos). O débito só acontece quando o teste termina bem: um que falha ou é cancelado não custa nada.

• Como numa corretora, a conta do teste tem margem: uma ordem que a margem livre não cobre é recusada (10019). Quando o patrimônio chega ao stop out da corretora (o nível que a conta informa; numa conta sem nível, quando zera), tudo é fechado e o teste para ali, também em cada combinação de uma otimização. report.stop_out diz quando, a quantos % do período e com que patrimônio: um expert que chega lá quebrou a conta. Com o histórico da B3, informe a margem por contrato em costs.margin.
• Numa otimização, cada combinação testada custa o mesmo que um teste. Antes de rodar, optimization_run com estimate_only diz quantos testes ela pode ter e o custo máximo, sem gastar nada; max_tests põe um teto. Quando o saldo acaba, ela para e pode continuar depois, sem repetir o que já testou.
• Os candles vêm da corretora de uma conta conectada (login) ou, sem conta, do histórico da própria B3 (source: "B3"), guardado desde 15/09/2026: WIN, WDO, IND e DOL (os contratos e as séries contínuas, como WIN@N) e as 20 ações mais negociadas.
• Um teste pode operar vários ativos e contas, como uma execução ao vivo: um parâmetro de ativo do expert é o nome de um ativo da mesma conta, ou { login, symbol } de outra conta, de qualquer corretora. Cada conta é simulada à parte, com o mesmo depósito e no relógio da sua corretora; o resultado traz cada conta (accounts) e o total, somado quando as moedas são iguais.
• Sem os custos — corretagem, emolumentos, escorregamento —, o resultado sai otimista. O agente pergunta os seus e informa em costs, e lê os avisos do teste (warnings) antes dos números.
• Para separar estratégia de sorte: backtest_monte_carlo sorteia de novo os negócios de um teste (de graça); optimization_robustness testa a vizinhança de uma combinação ou custos piores; forward e walk_forward_run conferem as melhores fora do trecho em que foram escolhidas.
• Uma otimização longa responde na hora e segue rodando: o agente acompanha com optimization_get, esperando até 50 s por vez, e conta o andamento. Cada usuário tem até 50 testes (esperam na fila, dividida de forma justa entre os usuários) e 2 otimizações esperando ou rodando ao mesmo tempo; um teste pode rodar até 120 minutos.

Experts ao vivo

Com a permissão Negociação, o agente liga um expert numa conta com expert_start. O mesmo expert roda quantas vezes você quiser, ao mesmo tempo: cada execução tem o seu número (run_id), a sua conta, ativo, número mágico e parâmetros. Os ativos também podem ser parâmetros: cada um numa conta de qualquer corretora, e a execução opera em todas elas ao mesmo tempo, para correlação entre corretoras ou arbitragem. Uma execução ligada pelo agente roda sempre nos servidores da plataforma, nunca no seu computador: continua rodando com o computador desligado e o app fechado.

• Antes de ligar, o ativo é conferido na corretora: um contrato futuro vencido (o WINV26 depois do vencimento, por exemplo) é recusado na hora, e symbols_get acha o vigente.
• O que o pedido não diz — a conta, o ativo, o tempo gráfico, o número mágico e os parâmetros — é o que a última execução do expert usou, ou o que o expert guarda. Para um expert que nunca rodou, diga ao menos a conta, o ativo e o tempo gráfico.
• Cada execução pode ter limites de risco em limits, na moeda da conta: daily_loss, a perda máxima do dia (fechada e aberta, no dia do fuso do usuário), e max_drawdown, a queda máxima do resultado desde o início. Atingido um, a plataforma zera a execução, a para e avisa. expert_run_update muda os limites de uma que já roda.
• expert_start espera até 30 s os servidores assumirem o expert e responde o estado dele e as últimas linhas do diário.

Os estados de um expert ao vivo:

starting

A caminho: os servidores ainda vão assumir. Acompanhe com expert_runs_list.

running

Rodando.

paused

Rodando, mas sem abrir posição nova.

stopped

Parado.

failed

Não começou ou parou por um erro; o motivo vem em error.

Para controlar uma execução, pelo run_id: expert_pause a deixa sem abrir posição nova (fechar, mudar stop e alvo e cancelar ordens passam) e pode cancelar as pendentes dela; expert_resume a retoma; expert_flatten cancela as pendentes e fecha as posições dela; expert_run_update troca a conta, o ativo, o tempo gráfico, o número mágico ou os parâmetros, e ela recomeça com isso em segundos; expert_stop a para em até 15 s, e as posições ficam — para fechá-las, zere antes. Parada, ela fica na lista: expert_start com o run_id liga de novo, expert_run_remove remove. expert_journal mostra o que ela imprimiu, as ordens e os erros.

Futuros da B3. O ativo pode ser a série WIN@N, WDO@N, IND@N ou DOL@N: a execução opera o contrato vigente e, no dia em que a série troca de contrato, a plataforma fecha o que ela tem no velho assim que ele volta a ser negociado e a recomeça no novo. Num contrato fixo, ela fica nele e recebe um aviso dias antes do vencimento. expert_runs_list mostra o contrato e o vencimento em contracts.

IA

O agente também pode mandar dados a um modelo de IA da plataforma com ai_decide. Hoje o modelo é o typesafe-ai/jev, rápido e feito para decidir. Ele lê os dados (um texto ou um objeto) e responde várias perguntas de uma vez, cada uma com as probabilidades por trás:

choice

Uma das opções que você descreve: comprar, vender ou esperar.

score

Uma nota numa escala de níveis: o risco de baixo a alto.

boolean

A chance de sim: o mercado está em tendência?

• Um expert faz o mesmo no código, com this.ai_decide, ao vivo e no teste no histórico. O expert_guide ensina o agente a escrever um.
• Cada chamada custa créditos, quase sempre uma fração de um. ai_models diz o preço por milhão de tokens. Sem saldo, a chamada é recusada antes de ir ao modelo.
• Toda chamada fica registrada com os tokens e os créditos, também as que falharam, que não custam nada. ai_usage mostra o consumo por expert, por modelo e por dia.
• Qualquer conexão pode chamar, sem permissão especial. Os dados enviados não ficam guardados.

Passo a passo

O caminho de um pedido como “crie um robô, teste e ligue na minha conta demo” até o expert rodando:

1. 1

   accounts_list: as contas, os números e se estão conectadas. Prefira uma conta demo.

2. 2

   symbols_get: o nome exato do ativo na corretora (com WIN*, os contratos do índice; use o vigente).

3. 3

   expert_guide: as regras e os exemplos, antes de escrever.

4. 4

   expert_add: guarda o arquivo. Se voltar um erro, corrija e mande de novo; versões novas vão por expert_update.

5. 5

   backtest_run: testa no período, com os custos do usuário em costs. Leia os warnings, depois os números. Diga quanto custou.

6. 6

   optimization_run com estimate_only: quantos testes e o custo máximo. Mostre ao usuário e peça confirmação.

7. 7

   optimization_run: roda nos servidores. Acompanhe com optimization_get até terminar, contando o andamento, e confira as melhores com forward, optimization_robustness ou backtest_monte_carlo.

8. 8

   Confirme com o usuário: a conta, o ativo, o tempo gráfico, o número mágico, os parâmetros e o preço da hora nos servidores (expert_runs_list).

9. 9

   expert_start: liga nos servidores e devolve o estado e o diário. Se vier failed, conte o motivo ao usuário.

10. 10

    expert_runs_list e expert_journal: acompanhe o estado, as ordens e o diário.

Confirmações e segurança

O servidor pede ao agente que, antes de cada passo abaixo, mostre ao usuário exatamente o que será feito e peça confirmação:

• Enviar, alterar ou cancelar uma ordem.
• Ligar ou zerar um expert ao vivo.
• Cadastrar, alterar ou remover uma conta.
• Remover um expert, ou rodar uma otimização (com o número de testes e o custo máximo).

• A conexão do agente é sempre uma chave de API sua, tenha ela vindo da entrada pelo navegador ou sido colada à mão: só enxerga as contas do seu usuário, e revogar a chave no app corta o agente na hora. Quando o aplicativo do agente avisa que foi desconectado, a chave também é revogada; na dúvida, revogue no app.
• Na tela de autorização, confira para onde você volta depois de responder: só autorize aplicativos em que você confia.
• As ordens que o agente envia por order_send devem levar um magic dele, para achar depois as ordens, os negócios e as posições que ele abriu.

Ferramentas

Todas as ferramentas, por assunto, com a permissão que cada uma pede. O agente só vê as das permissões que você marcou.

• Leitura
• Negociação
• Contas
• Backtests

Contas e corretoras

accounts_list

Suas contas de corretora: número (login), servidor, corretora, se é demo ou real, se está conectada e o ping. Quando não está, o motivo e quando sai a próxima tentativa. Comece por aqui.

Permissão: Leitura

brokers_list

As corretoras, os métodos e os servidores, com o tipo de credencial que cada um pede.

Permissão: Leitura

account_info

Saldo, patrimônio, lucro em aberto, margem, margem livre, nível de margem, alavancagem e moeda.

Permissão: Leitura

account_add

Cadastra uma conta e conecta na hora. As credenciais são conferidas e guardadas criptografadas.

Permissão: Contas

account_update

Ativa, desativa ou troca as credenciais de uma conta.

Permissão: Contas

account_remove

Tira da plataforma uma conta sem histórico gravado (não mexe na conta na corretora). Uma com histórico, desative.

Permissão: Contas

Mercado

symbols_get

Os ativos cujo nome casa com um filtro (WIN*, PETR4,VALE3), com tudo sobre cada um.

Permissão: Leitura

symbol_info

As regras de um ativo: casas decimais, tick, contrato, volumes mínimo, máximo e passo, e os modos de execução.

Permissão: Leitura

symbol_info_tick

A última cotação: compra, venda, último preço, volume e horário.

Permissão: Leitura

market_book_get

O livro de ofertas.

Permissão: Leitura

copy_rates_from_pos

Candles contando do atual: 0 é o que está em formação, 1 o último fechado.

Permissão: Leitura

copy_rates_from

Os candles que terminam numa data.

Permissão: Leitura

copy_rates_range

Os candles de um período.

Permissão: Leitura

Posições, ordens e histórico

positions_get

Posições abertas: ativo, tipo, volume, preços, stop, alvo, lucro e magic.

Permissão: Leitura

orders_get

Ordens pendentes.

Permissão: Leitura

history_deals_get

Negócios (execuções) de um período, de uma ordem ou de uma posição.

Permissão: Leitura

history_orders_get

Ordens executadas, canceladas ou expiradas no período.

Permissão: Leitura

ledger_get

Numa conta compensada, a parte de cada robô: a posição aberta dele, o que cada negócio fez com ela e o resultado do período.

Permissão: Leitura

order_send

Envia, altera ou cancela uma ordem e devolve o resultado: 10009 executada, 10008 colocada; outro código é uma recusa, com o motivo.

Permissão: Negociação

Experts

expert_guide

Como escrever um expert: as regras do arquivo, as funções e os indicadores, e três exemplos completos.

Permissão: Leitura

experts_list

Seus experts, com os parâmetros (padrão e limites), sem o código.

Permissão: Leitura

expert_get

Um expert, com o código.

Permissão: Leitura

expert_add

Guarda um expert novo. Um arquivo com erro volta com o motivo.

Permissão: Backtests

expert_update

Troca o arquivo ou o nome de um expert.

Permissão: Backtests

expert_remove

Remove um expert e os testes dele, sem volta.

Permissão: Backtests

Experts ao vivo

expert_runs_list

As execuções dos experts, cada uma com o seu número: onde rodam, o estado, a conta, o ativo, o número mágico, as ordens e o custo. Também o preço da hora nos servidores e quantas horas o saldo paga.

Permissão: Leitura

expert_journal

O diário de uma execução: o que imprimiu, as ordens que mandou e como foram, e os erros.

Permissão: Leitura

backtests_portfolio

Vários testes já feitos juntos, como robôs lado a lado: o resultado e a maior queda do conjunto, e o quanto eles andam juntos. Não custa créditos.

Permissão: Leitura

notices_list

Os avisos dos robôs: uma execução que falhou ou parou sozinha, uma ordem recusada, um limite de risco atingido, uma troca de contrato, uma conta que segue sem conexão depois das tentativas rápidas de reconectar (cerca de 2 minutos; a senha recusada, na hora), e cada posição de um robô que fechou, com o resultado. Os mesmos que o app mostra e que chegam como notificação no celular e por e-mail.

Permissão: Leitura

expert_statistics

Os números de uma execução ao vivo, os mesmos de um backtest: lucro, fator de lucro, maior queda do saldo e do patrimônio, sequências de ganhos e perdas, Sharpe.

Permissão: Leitura

expert_compare

Uma execução ao lado de um backtest dos mesmos dias, operação por operação: o resultado dos dois, quantas operações do teste aconteceram ao vivo e de onde vem a diferença. Não roda teste nem gasta créditos.

Permissão: Leitura

expert_start

Liga uma execução nova de um expert numa conta, ou de novo uma parada, sempre nos servidores, e espera até 30 s eles assumirem. A hora custa créditos.

Permissão: Negociação

expert_run_update

Troca a conta, o ativo, o tempo gráfico, o número mágico ou os parâmetros de uma execução; rodando, ela recomeça com isso em segundos.

Permissão: Negociação

expert_pause

O expert segue rodando, mas não abre posição nova; pode cancelar as pendentes dele.

Permissão: Negociação

expert_resume

O expert pausado volta a abrir posições.

Permissão: Negociação

expert_flatten

Zera a execução: cancela as pendentes e fecha as posições dela, pelo número mágico. Pode pausar antes.

Permissão: Negociação

expert_stop

Para a execução em até 15 s. As posições e ordens dela ficam.

Permissão: Negociação

expert_run_remove

Remove uma execução parada, com o diário dela.

Permissão: Negociação

Testes no histórico

credits_get

O saldo de créditos, o que os testes em andamento reservam, o que sobra e o preço de um teste.

Permissão: Leitura

b3_symbols

Os ativos da B3 guardados para testar sem conta, com o primeiro e o último dia de cada um.

Permissão: Leitura

b3_rates_range

Candles de um ativo da B3 guardado, sem conta de corretora.

Permissão: Leitura

b3_download

Um endereço para baixar, como planilha, os candles de um ativo da B3 (até um ano) ou os negócios da bolsa (até 7 dias). Abre sem chave por uma hora.

Permissão: Leitura

backtests_list

Seus testes: onde rodaram (no seu computador ou nos servidores), o que testaram, o estado, o custo e os números principais.

Permissão: Leitura

backtest_get

Um teste com o relatório: os números pelo nome e o fim do diário do expert. Se pedir, todos os negócios de página em página, até 1000 linhas do diário e a curva de saldo e patrimônio.

Permissão: Leitura

backtest_files

Endereços para baixar os arquivos de um teste: todos os negócios, as ordens e a curva em planilhas, o diário em texto e as planilhas que o próprio expert escreveu no teste (FileOpen, FileWrite). Abrem sem chave por uma hora.

Permissão: Leitura

backtest_monte_carlo

Sorteia de novo, milhares de vezes, os negócios de um teste: o lucro e a maior queda prováveis e as chances de prejuízo e de ruína. De graça.

Permissão: Leitura

backtest_run

Testa um expert no histórico, nos servidores, e espera o resultado até 45 s. Com source: "B3", sem conta, nos negócios da própria B3. Custa créditos.

Permissão: Backtests

backtest_cancel

Para um teste que espera ou roda nos servidores, sem custo.

Permissão: Backtests

Otimizações

optimizations_list

Suas otimizações: onde rodaram, o estado, quantos testes, o custo e a melhor.

Permissão: Leitura

optimization_get

Onde uma otimização está e as melhores combinações, de página em página; espera até 50 s, para acompanhar uma longa.

Permissão: Leitura

optimization_run

Testa várias combinações dos parâmetros nos servidores. Com estimate_only, só diz quantos testes e o custo máximo; com forward, confere as melhores no trecho final guardado.

Permissão: Backtests

optimization_robustness

Testa de novo uma combinação: a vizinhança dela ou os custos sorteados.

Permissão: Backtests

optimization_stop

Para a otimização; o que foi testado fica.

Permissão: Backtests

optimization_resume

Continua de onde parou, sem repetir combinações.

Permissão: Backtests

IA

ai_models

Os modelos de IA: o que fazem, os tipos de pergunta e o preço em créditos por milhão de tokens.

Permissão: Leitura

ai_decide

Manda dados a um modelo e recebe as respostas das perguntas (escolha, nota ou sim/não), com as probabilidades. Custa créditos.

Permissão: Leitura

ai_usage

O consumo de um período: chamadas, tokens e créditos, por modelo, por expert, por origem e por dia, e as chamadas.

Permissão: Leitura

Janelas que avançam

O walk forward corta o período em rodadas: cada uma otimiza alguns meses e opera a melhor combinação nos meses seguintes, onde ela não foi escolhida.

walk_forwards_list

Seus walk forwards: o estado, as rodadas e o que cada uma fez.

Permissão: Leitura

walk_forward_get

Um walk forward e as rodadas: a melhor de cada uma, o que fez na busca e operando depois, e a soma dos trechos operados.

Permissão: Leitura

walk_forward_run

Corta o período em rodadas de busca e operação e roda nos servidores, uma depois da outra. Com estimate_only, só diz as rodadas e o custo máximo.

Permissão: Backtests

walk_forward_stop

Para na rodada em que está; o que foi testado fica.

Permissão: Backtests

walk_forward_resume

Continua da rodada em que parou.

Permissão: Backtests

Respostas e erros

Cada ferramenta responde em JSON, com os mesmos campos da API REST. Um erro volta como resposta da ferramenta, com o código HTTP e o motivo, para o agente corrigir e tentar de novo:

401

Chave ausente ou revogada: conecte de novo

402

Créditos que não pagam o teste nos servidores

403

A conexão não tem a permissão

404

Conta, ativo, expert ou teste que não existe ou não é seu

429

Chamadas demais, ou testes demais esperando nos servidores

503

Conta sem conexão com a corretora

Uma ordem recusada pela corretora não é erro: volta como resultado de order_send, e o retcode diz o motivo.

Mais documentação

SDK

Como escrever um expert, testar e otimizar no seu computador ou nos servidores, e usar as contas pelo código.

Referência da API (abre em nova aba)

Todas as rotas e modelos da API REST e os tópicos do tempo real, com os mesmos campos das ferramentas.

A referência em texto

A mesma referência em Markdown, para agentes de IA lerem.

Descrição OpenAPI

A API em OpenAPI 3.1, para gerar clientes.

llms.txt

O resumo da plataforma e onde está cada documentação, para agentes de IA.