Motor de Execução de Bots
Como bots rodam via cron, paper vs live
O motor de execução de bots é o runtime acionado por cron que de fato executa as estratégias dos seus bots. Entender como ele funciona ajuda você a depurar comportamentos inesperados dos bots e a ajustá-los para melhor desempenho.
Arquitetura
O motor de execução é um cron job da Vercel que roda a cada 15 minutos:
- Disparo. O cron da Vercel aciona /api/cron/execute-bots aos 0/15/30/45 minutos de cada hora.
- Autenticação. O endpoint verifica que a requisição veio da Vercel usando um token assinado.
- Enumeração de bots. Busca no banco de dados todos os bots com status="running".
- Despacho de estratégia. Para cada bot, carrega o template de estratégia apropriado (EV Follower, ARB Hunter, etc.).
- Avaliação de mercado. A estratégia examina o estado atual do mercado em relação aos parâmetros do bot.
- Colocação de ordens. Quando as condições coincidem, o motor envia ordens via Polymarket CLOB API (modo Live) ou registra fills simulados (modo Paper).
- Registro de auditoria. Cada ação — avaliação, trade, erro — é registrada na trilha de auditoria.
Por Que 15 Minutos?
A escolha de intervalos de 15 minutos equilibra diversos fatores:
- •Rate limits da Polymarket. A CLOB API permite 10 trades/minuto por usuário. Considerando todos os bots × todos os usuários, precisamos ficar abaixo dos limites agregados.
- •Custo. Cada tick do cron varre todos os mercados de todos os bots. Mais frequente = mais processamento = custos maiores.
- •Retornos decrescentes. Os prediction markets se movem mais devagar do que cripto ou ações. Uma granularidade de 5 minutos versus 15 minutos raramente captura mais alpha.
- •Compatibilidade com o plano gratuito da Vercel. Nosso cronograma de cron se encaixa dentro dos limites do tier hobby da Vercel.
Para usuários do plano Bot que desejam execução mais rápida, as ordens TWAP não estão vinculadas ao cron de 15 minutos — elas são executadas em fatias por minuto através de um cron separado.
Limites Que São de Fato Aplicados
Os freios do bot são por DINHEIRO e por posições abertas, não por contador de trades:
- •Por trade: US$ 25 por padrão na automação, ajustável em Configurações → Trading.
- •Por bot, por dia: US$ 100 por padrão, mais um teto opcional de número de trades que você define no próprio bot.
- •Por bot, simultâneas: 3 posições live abertas, e nunca duas no mesmo mercado no mesmo dia.
- •Por perfil, por dia: um orçamento total reservado atomicamente antes de cada ordem, para dois bots não gastarem o mesmo dólar.
Ao bater um teto a ordem é recusada, registrada e reportada a você — o bot segue adiante em vez de re-tentar. ## O Que Acontece Quando um Trade Falha
A CLOB API pode falhar por diversos motivos:
- •Erro de rede. A reserva de idempotência é mantida e a ordem vai para reconciliação — nunca sai uma segunda ordem às cegas.
- •Saldo insuficiente. Recusado antes de tocar a venue, registrado e notificado; o bot não é pausado por isso.
- •Mercado fechado. Registrado, e o bot passa para a próxima oportunidade.
- •Preço deslocado. Se o preço saiu do seu limite, a ordem não cruza e o bot re-tenta no ciclo seguinte.
Um trade que falha não quebra a execução: fica registrado e o bot continua. ## Monitorando Seus Bots
Três superfícies mostram o que os seus bots estão fazendo:
- •Desempenho (plano Bot) — PnL por bot com ao vivo e paper separados, taxa de acerto, número de trades e as posições ainda abertas.
- •Segurança → registro de auditoria — o rastro de toda ação sensível da conta, inclusive uma ordem real recusada e o motivo (kill switch, teto do dia, plano, região).
- •Notificações — preenchimentos e falhas chegam no app e, se você verificou o canal, no Telegram ou WhatsApp. Um bot que atinge a perda máxima se pausa sozinho e te avisa.
Se um bot não operou quando você esperava, o motivo está no registro de auditoria. Não existe um log de skip por ciclo: um ciclo que não acha nada simplesmente não faz nada.
Disparando a Execução Manualmente
O botão "Execute now" na página de Bots (disponível para usuários do plano Bot) permite disparar um ciclo imediato sem esperar pelo próximo tick do cron. Útil para:
- •Testar mudanças de parâmetros sem esperar 15 minutos
- •Capturar sinais sensíveis ao tempo que você identificou manualmente
- •Verificar a conectividade após uma manutenção da CLOB API
Disparos manuais contam para o seu rate limit diário. Não fique apertando esse botão sem parar.
Parando um Bot
Três formas de parar um bot:
- Pausar. O bot mantém as posições existentes e não assume novas. Use para pausas curtas.
- Parar. O bot é totalmente desativado. As posições abertas permanecem; feche-as manualmente.
- Kill switch (global). Settings → Trading → Kill Switch interrompe imediatamente TODOS os bots e TODA a execução automatizada. Use em emergências.
O kill switch é a decisão certa se você notar comportamento inesperado — pause para investigar e reative quando tiver certeza.
Trilha de Auditoria
Cada ação do bot é registrada na tabela bot_audit_logs com:
- •Timestamp
- •ID do bot
- •Tipo de ação (evaluate, place_order, close_order, error)
- •Mercado envolvido
- •Justificativa da decisão (qual condição foi acionada ou por que houve skip)
- •Detalhes da ordem (tamanho, preço, direção)
- •Resultado (filled, rejected, partial)
Você pode exportar os logs de auditoria como CSV a partir da página de detalhes do bot. Útil para:
- •Declaração de impostos (exportação do Form 8949 disponível)
- •Revisão de estratégia ("por que o bot passou batido neste mercado?")
- •Depuração quando o comportamento não corresponde às expectativas
- •Documentação de compliance caso você esteja operando profissionalmente
Problemas Comuns de Execução de Bots
O bot mostra "running" mas nunca opera.
- •Verifique o log de skip — provavelmente todos os sinais estão abaixo do seu limite mínimo de edge.
- •Tente reduzir um pouco o min_edge, mas não vá abaixo de 5pp.
- •Verifique se os filtros de categoria não estão estreitos demais.
O bot opera demais.
- •O limite diário de trades está alto demais.
- •O min edge está baixo demais — você está capturando ruído.
- •Adicione filtros adicionais (confiança mínima, volume mínimo).
O bot opera em apenas uma plataforma.
- •Verifique o toggle Polymarket vs Kalshi na configuração do bot.
- •Verifique se o indicador de status da outra plataforma está verde.
O bot Live parou de operar de repente.
- •Verifique o status da CLOB API (pode estar fora do ar).
- •Verifique se as suas credenciais da CLOB API não expiraram.
- •Verifique se a sua carteira Polymarket tem saldo em USDC.