Portfólio de trading ao vivo

Como as estratégias operam com dinheiro real: valores em dólares, reconciliação automática, fechar tudo e o kill switch.

Visão geral

O portfólio de trading é o conjunto de estratégias autorizadas a enviar ordens reais. Cada estratégia nele recebe um valor fixo em dólares; o daemon reconciliador então mantém as posições que as próprias estratégias abriram convergindo para o alvo combinado — você nunca envia essas ordens manualmente. Ele só gerencia as próprias ordens: uma posição que você abriu manualmente é invisível para ele e nunca é tocada.

strategy.py ──► state.json ──────────────┐
   (cron)                                ├──► reconciler.py ──► exchange
amounts     ──► portfolio_config.json ───┘

Dimensionamento baseado em valor

Cada estratégia no portfólio recebe um valor na moeda da conta (ex.: USD) — com o que a estratégia opera quando o sinal está em tamanho total. A posição-alvo por símbolo é a soma entre estratégias:

target[symbol] = Σ ( amount × position )

position é o sinal da estratégia e pode ser fracionário (uma estratégia com escala de volatilidade pode emitir 0.5 ou 1.8). O valor que você define é exatamente o que dimensiona as posições — ele não muda com o patrimônio da conta. Exceção: para estratégias de futuros de Taiwan da Capital (群益), o valor é uma contagem de lotes (número de contratos), não uma cifra em dólares.

O reconciliador

O reconciliador é um daemon que consulta a cada 5 segundos e reconcilia sempre que:

• uma estratégia atualiza seu sinal (state.json muda)
• você salva novos valores em Configuração de trading
• o kill switch é acionado ou desativado
• 5 minutos passaram sem reconciliação — uma rede de segurança que detecta desvio de posição e chaves de exchange mortas
• uma execução TWAP ou personalizada termina — assim a diferença residual converge em uma consulta, em vez de esperar pela rede de segurança de 5 minutos

Cada passagem compara o alvo com o book do próprio bot — o reconciliador mantém seu próprio livro-razão, um total corrente de cada ordem que enviou (manager/orders.jsonl), em vez de ler as posições brutas da exchange na conta, então uma posição que você abriu manualmente nunca é lida como "já em posição" e nunca é somada ou fechada. As ordens são então enviadas para fechar a diferença — ordens a mercado por padrão; cada estratégia pode ser configurada para mercado, TWAP, chase limit, ou um estilo de execução personalizado em Configuração de trading (futuros TW da Capital (群益) suportam apenas mercado). Diferenças abaixo de $10 são ignoradas (futuros TW reconciliam em lotes inteiros). Uma inversão de posição (comprado → vendido) é dividida em um fechamento reduce-only mais uma nova abertura, então contas em hedge mode nunca mantêm os dois lados ao mesmo tempo.

Quando não é possível ler as posições na exchange: uma falha temporária da exchange (timeout, sobrecarga, manutenção) só pula essas rodadas e o trading retoma sozinho quando a leitura volta; após 30 minutos seguidos sem conexão, você é avisado. O reconciliador aciona o kill switch apenas para chave inválida, permissão insuficiente, IP fora da lista branca, 3 erros não reconhecidos seguidos, ou conta divergente detectada na inicialização, na reconexão ou na troca de chave — e esse kill switch nunca se desativa sozinho; quem decide retomar é você.

Fechar todas as posições

Pressione Pausar trading na área de trabalho e a caixa de diálogo oferece duas opções: Pausar novas posições apenas aciona o kill switch; Pausar e fechar posições (ou python3 manager/flatten.py) encerra a mercado as posições que as estratégias abriram — apenas o que está no book do próprio bot, então uma posição que você abriu manualmente fica intocada, e o spot vende apenas as moedas sob gestão da estratégia, nunca suas outras posições. É um botão de pânico, não gestão de portfólio:

• O kill switch é acionado primeiro, então nada reabre após o flatten — o trading fica pausado até você pressionar Iniciar trading.
• Posições abaixo do mínimo da exchange não podem ser fechadas — o resíduo (dust) é registrado e deixado como está.
• Todo fechamento é gravado no histórico de ordens com sua execução confirmada pela exchange.

Kill switch (HALT)

Enquanto o kill switch está ativo, qualquer ordem que aumentaria a exposição é recusada no nível do código. Fechamento de posições, stop-loss / take-profit e cancelamentos continuam passando — um halt nunca prende uma posição que você está tentando reduzir.

Ele é ativado por Pausar trading na área de trabalho (incluindo Pausar e fechar posições), ao pedir ao agente para parar o trading, ou automaticamente em caso de erro de chave ou permissão, 3 erros não reconhecidos seguidos, ou conta divergente detectada na inicialização, na reconexão ou na troca de chave (uma falha temporária da exchange não o aciona — o trading retoma sozinho quando ela volta). Nunca é desativado automaticamente — o trading só é retomado quando você pressiona Iniciar trading ou pede explicitamente ao agente para retomar. Iniciar trading também oferece duas opções: Iniciar e recuperar posições envia ordens a mercado imediatamente para igualar o sinal atual de cada estratégia; Iniciar, aguardar novos sinais não envia nenhuma ordem agora — cada estratégia só começa a operar na sua próxima entrada, saída ou inversão. Toda tentativa de ordem e recusa é registrada em um log de auditoria.

Histórico de ordens e execuções

Toda ordem executada é anexada a manager/orders.jsonl com suas pernas — o preço de execução e a quantidade executada, confirmados pela exchange, de cada perna individual. Uma inversão de posição registra duas pernas: a perna de fechamento carrega o preço de saída, a perna de abertura o preço de entrada.

Falhas parciais também são registradas: se a perna de fechamento de uma inversão foi executada mas a perna de abertura falhou, o registro é mantido e marcado como falho — o histórico nunca esconde uma ordem que movimentou dinheiro real. A aba Histórico de ordens da área de trabalho exibe esse arquivo.