# TroiaQuants

> Plataforma que conecta agentes de IA e robôs de negociação (experts) às contas de corretora do usuário. Agentes compatíveis com o protocolo MCP (Claude, ChatGPT, Cursor e outros) leem o mercado, operam e testam estratégias pela TroiaQuants, com as permissões que o usuário escolhe.

- O usuário cria a conta no app, conecta a corretora (real ou demo) e gera chaves de API, cada uma com as suas permissões: Leitura (sempre), Negociação (envia ordens e liga, pausa, zera e para experts ao vivo), Contas (cadastra contas de corretora) e Backtests (escreve experts e roda backtests nos servidores da plataforma).
- Agentes de IA conectam pelo servidor MCP; robôs próprios usam a API REST e o tempo real por WebSocket.
- Experts são escritos em JavaScript ou TypeScript com o SDK `@troiaquants/sdk`: o mesmo arquivo roda ao vivo e é testado e otimizado no histórico com os candles da corretora, no computador do usuário (grátis) ou nos servidores da plataforma (por créditos).
- Como numa corretora, a conta do teste tem margem: uma ordem que a margem livre não cobre é recusada (10019), e o stop out da corretora (o nível que a conta informa; sem ele, o patrimônio em zero) fecha tudo e encerra o teste ali, também em cada combinação de uma otimização (`report.stop_out` diz quando). Um teste que, sem nada aberto, não paga mais nem o menor lote também termina ali. No histórico da B3, a margem por contrato vai em `costs.margin`.
- IA por créditos: um expert (`this.ai_decide`), um script (`tq.ai_decide`), a API (`POST /ai/decide`) e um agente (`ai_decide` no MCP) mandam dados a um modelo de IA da plataforma (hoje `typesafe-ai/jev`), que responde perguntas tipadas: `choice` (uma das opções), `score` (uma nota numa escala) e `boolean` (a probabilidade de sim), com as probabilidades. Cada chamada custa créditos, ao vivo e no backtest, e fica registrada com os tokens e os créditos (`ai_usage`, `GET /ai/usage`). Qualquer chave chama.
- Ao vivo, um expert roda no app aberto no computador do usuário ou nos servidores da plataforma (a nuvem), onde continua com o computador desligado e a hora custa créditos. Ligado por um agente de IA ou pela API, roda sempre nos servidores; um expert guardado por um agente ou pela API roda só nos servidores, também quando ligado pelo app.
- Um expert roda quantas vezes o usuário quiser ao mesmo tempo, cada execução com o seu id (`run_id`). Os ativos podem ser parâmetros (`input.symbol`): cada um numa conta de qualquer corretora, e a execução opera em todas as contas escolhidas (correlação entre corretoras, arbitragem).
- Cada execução pode ter limites de risco (perda máxima do dia e queda máxima): ao chegar num deles, a plataforma a zera e a para.
- Ao vivo × teste (`expert_compare` no MCP, `run_compare` no SDK, `GET /runs/{id}/compare`, e a aba do mesmo nome na página do robô): o que uma execução fez na conta, operação por operação, ao lado de um backtest dos mesmos dias, com o resultado dos dois, quantas operações do teste aconteceram ao vivo e de onde vem a diferença (entradas, saídas, stops, alvos, custos, operações de um lado só). Os números de uma execução, os mesmos da aba Números, estão em `expert_statistics`.
- O ativo de uma execução pode ser a série contínua de um futuro da B3 (`WIN@N`, `WDO@N`, `IND@N`, `DOL@N`): ela opera o contrato vigente e troca sozinha quando a série troca.
- Avisos dos robôs (`notices_list` no MCP e no SDK, `GET /notices`): execução que falhou ou parou sozinha, ordem recusada, limite atingido, troca de contrato, conta que segue sem conexão depois das tentativas rápidas de reconectar (cerca de 2 minutos; senha recusada, na hora), e cada posição de um robô que fechou, com o resultado (`closed`; `kinds` filtra os tipos). Os mesmos aparecem no app e chegam como notificação no celular e no computador e por e-mail, nos tipos que o usuário escolhe no Perfil.
- No teste, o expert opera vários ativos e contas de corretoras diferentes, cada conta simulada à parte no relógio dela (o relatório traz cada conta em `accounts` e o total), e escreve as próprias planilhas (`FileOpen`, `FileWrite`, `FileClose`), guardadas com o relatório. Testes já feitos podem ser juntados como robôs lado a lado (`backtests_portfolio`): o resultado e a queda do conjunto e a correlação dos resultados diários, sem custo.
- Arquivos para baixar: os negócios, as ordens e a curva de saldo e patrimônio de um backtest em planilhas (CSV), e o diário em texto (`GET /backtests/{id}/files/...`, `backtest_files` no MCP); os candles da B3 (até um ano) e os negócios da bolsa (até 7 dias) como planilha (`format=csv` em `/exchanges/B3/candles` e `/ticks`, `b3_download` no MCP). `POST /links` dá um endereço que abre o arquivo sem a chave por uma hora, para um navegador ou o código de um agente.
- O dinheiro fica na corretora: a TroiaQuants não faz depósitos nem saques.

## Documentação

- [MCP](https://troiaquants.com/mcp): como conectar um agente de IA, as permissões, como a plataforma funciona para o agente (contas, experts, testes e créditos, experts ao vivo nos servidores), o passo a passo recomendado, as confirmações e todas as ferramentas, com a permissão de cada uma
- [SDK](https://troiaquants.com/sdk): como escrever um expert (parâmetros, ativos em várias contas, eventos, indicadores, ordens, IA), testar e otimizar no computador ou nos servidores (também em vários ativos e contas, com os arquivos do robô e testes juntos), créditos, experts e testes guardados, ao vivo (limites de risco, séries da B3, avisos), as funções da conta pelo código, o tempo real e as cotações gravadas
- [Referência da API em texto](https://api.troiaquants.com/docs.md): todas as rotas e modelos da API REST e os tópicos do WebSocket, em Markdown
- [Referência da API](https://api.troiaquants.com/docs): a mesma referência, navegável
- [Descrição OpenAPI](https://api.troiaquants.com/openapi.json): a API em OpenAPI 3.1, para gerar clientes
- [Pacote do SDK no npm](https://www.npmjs.com/package/@troiaquants/sdk)

## Conectar um agente de IA

- Endereço do servidor MCP: https://mcp.troiaquants.com (Streamable HTTP). O agente entra com a conta TroiaQuants do usuário pelo navegador (OAuth), e o usuário escolhe as permissões; uma chave de API no cabeçalho `Authorization: Bearer <chave>` também serve.
- No Claude: Configurações → Conectores → Adicionar conector personalizado, com o endereço acima. Claude Code, Cursor e outros clientes: veja a [página do MCP](https://troiaquants.com/mcp#conectar).
- O caminho do agente: accounts_list → symbols_get → expert_guide → expert_add → backtest_run → optimization_run com estimate_only → confirmação do usuário → optimization_run → confirmação do usuário → expert_start → expert_runs_list, expert_journal e notices_list (os avisos: falhas, paradas, ordens recusadas, limites atingidos, posições fechadas). Antes de enviar uma ordem, ligar ou zerar um expert, cadastrar ou remover uma conta e rodar uma otimização, o agente mostra ao usuário o que será feito e pede confirmação.
- O controle do usuário: as permissões que ele marca ao conectar, a confirmação acima, contas demo para treinar e a pausa da conta no app (com a conta pausada, toda ordem nova é recusada, venha do agente, de um expert ou de outra chave, até ele retomar). Revogar a chave no app corta o agente na hora.

## Conta

- [Criar conta](https://app.troiaquants.com/criar-conta)
- [Entrar](https://app.troiaquants.com/entrar)
- [Página inicial](https://troiaquants.com/)