Documentação

A cadeia de valor é: dados de mercado (Binance USD-M Futures) → motor determinístico de indicadores (funções puras) → score de confluência ponderado → ajuste por regime de mercado → interpretação por IA (Claude ou Gemini) → filtro de risco/retorno → persistência e acompanhamento do desfecho → autoaprendizado (recalibração de pesos).

Todo o cálculo dos indicadores é determinístico: os mesmos candles produzem sempre o mesmo snapshot. A IA nunca inventa números — ela só interpreta o snapshot já calculado.

Há dois motores de análise independentes: o Clássico (score de confluência + interpretação da IA, descrito acima) e o Stormer (setups S1–S9 multi-timeframe, detalhado nas seções próprias). Você alterna entre eles no dashboard e pode rodar cada um em lote nas Oportunidades. Cada motor tem sua própria acurácia acompanhada separadamente.

Além do uso manual, há uma Automação que executa todo esse fluxo de hora em hora sobre os 30 pares de maior volume e as 30 gemas, cruza os dois motores num funil de qualidade e — em modo observação (shadow) ou execução real, à sua escolha — seleciona os trades. Ver a seção Automação.

Timeframe base e superior por perfil:

• Scalping: base 5m, superior 1h.
• Daytrade: base 15m, superior 1h.
• Swingtrade: base 4h, superior 1d.

Cada perfil também tem um R:R mínimo (scalping 1.2, daytrade 1.5, swingtrade 2.0) e um conjunto de pesos: scalping reforça médias curtas e osciladores; swingtrade reforça médias longas, ADX e estrutura.

São usados 400 candles por análise (cobre a EMA200 com folga e o aquecimento das médias). O candle ainda em formação é descartado — só candles fechados entram no cálculo, evitando leituras que mudam a cada tick. O snapshot é persistido em snapshots_tecnicos e a análise da IA em analises_ia. Qualquer fonte externa (derivativos, BTC, persistência) que falhe é ignorada sem derrubar a análise — o cálculo determinístico é a parte crítica. O precoAtual do snapshot é ancorado no ticker em tempo real (quando disponível), não no fechamento do último candle, para o R:R refletir o preço de agora.

• RSI: sobrevenda < 30 (voto alta), sobrecompra > 70 (baixa).
• Estocástico / StochRSI: < 20 alta, > 80 baixa.
• MACD (12,26,9): voto pelo sinal do histograma.
• ADX (14): só vota quando ≥ 20; +DI > -DI → alta, senão baixa.
• Bollinger (20,2): acima da banda superior → baixa; abaixo da inferior → alta.
• OBV: voto pela inclinação recente.

Osciladores (RSI/Estocástico/Bollinger) são de reversão: votam contra o movimento. Médias/MACD/ADX são de tendência. Essa distinção é o que o regime de mercado reconcilia (ver adiante).

É a soma ponderada dos votos (+peso para alta, -peso para baixa), normalizada pela soma dos pesos apenas dos indicadores que votaram — unanimidade dá exatamente ±100. Neutros e pesos zero são ignorados. Os pesos vêm do perfil e podem ser recalibrados pelo autoaprendizado.

Estrutura e divergências viram "votos sintéticos" no score (chaves estrutura e divergencia). Divergências consideram os dois pivôs mais recentes contra RSI e MACD. Padrões de candle são detectados e exibidos, mas hoje não entram diretamente no score.

Zonas são agrupadas a partir de pivôs (tolerância 0,5%), classificadas pela posição vs preço atual, descartadas se além de 15% de distância, e ranqueadas por proximidade, nº de toques e recência (máx. 3 por lado). A sugestão de níveis usa buffer de ATR e cai num fallback por múltiplos de ATR quando não há zona adequada.

O viés é derivado do score com um limiar (padrão 25). Base e superior precisam apontar a mesma direção não-neutra para confirmar; qualquer conflito ou lado neutro resulta em viés confirmado neutro.

O regime (tendencia, range ou indefinido) é classificado por ADX, largura das Bandas de Bollinger e estrutura. A ponderação adaptativa então amplifica (×1,5) os indicadores de tendência e atenua (×0,5) os de reversão em regime de tendência — e o inverso em range. Em indefinido, os pesos ficam inalterados. Isso resolve o problema de sinais que se anulavam.

Cada um vira um voto no score (chaves funding, open_interest, long_short, liquidacoes). Funding: |taxa| ≥ 0,05% aciona voto contrário. OI: matriz preço×tendência-de-OI. Long/short: extremos (≥ 2,0 ou ≤ 0,5) viram voto contrário. Liquidações: lado dominante precisa ser ≥ 1,5× o outro. São coletados best-effort; se a Binance não responder, a análise segue sem eles.

A tendência do BTC vem das EMAs (50 vs 200) e a correlação é de Pearson sobre os retornos. Só há voto quando a correlação positiva é relevante (≥ 0,6). Para o próprio BTCUSDT, o contexto é neutro.

Suporta Claude e Gemini (o usuário escolhe e usa a própria chave). O catálogo atual é: Claude Sonnet 5 (padrão) e Opus 4.5; Gemini 3 Flash, 2.5 Flash e 2.5 Pro. A partir do Sonnet 5, a Anthropic exige os valores default de sampling — então o cliente OMITE temperature para esses modelos (enviar causaria erro 400). A saída é forçada por function calling num schema fixo: vies, confianca (0–100), argumentos, invalidacao e alvo_sugerido (entrada, alvo1, alvo2?, stop). O prompt injeta o desempenho histórico real da IA no par/perfil para calibrar a confiança, e regras de geometria (short: alvos abaixo, stop acima).

R:R = |alvo1 − entrada| / |entrada − stop|. Mínimos: scalping 1.2, daytrade 1.5, swingtrade 2.0 (o usuário pode sobrescrever entre 1 e 10). Reprovada → viés neutro, confiança limitada a 25 e alvo removido, com uma nota explicando o rebaixamento. Isso roda antes de persistir, então acurácia e diário só contam sinais com R:R aceitável.

Quando há alvo2, a resolução usa a versão com gestão: o toque no alvo1 trava a parcial e move o stop para a entrada; o restante encerra no alvo2 (status alvo) ou no break-even (status alvo_parcial). Sem alvo2, mantém o modelo clássico (alvo1 vs stop). Regra de borda: se um candle toca dois níveis, o pior (stop/BE) tem prioridade — conservador. O statusalvo_parcial conta como acerto na acurácia.

Gestão avançada ao vivo. A decisão é PURA em decidirGestao (lib/journal/gestao-saida.ts): recebe entrada, stop atual, preço, ATR e se a parcial já foi feita, e devolve { realizarParcial, fracaoParcial, moverStop, novoStop }. A casca gerirPosicoesAvancado (lib/journal/gerir-posicoes-io.ts) aplica na Binance: realiza a fração com ordem MARKET reduceOnly, cancela as ordens do par e recria o TP (preservado) + SL (break-even ou trailing) para a quantidade restante. Detecta que a parcial já ocorreu comparando a posição atual com a quantidade original do journal. Roda a cada rodada do cron; o trailing é amostrado por rodada (não é loop de alta frequência) e o stop nunca afrouxa. O break-even simples permanece em gerirPosicoesVivas.

A resolução percorre os candles após a análise e vê qual nível o preço tocou primeiro (se um candle toca ambos, o stop tem prioridade — cenário conservador). Os candles são buscados no timeframe operacional da própria análise (o mesmo em que ela foi gerada), então o desfecho é medido no horizonte da tese — não num TF fixo. Horizonte padrão de 7 dias; sem resolução, marca "expirada" (fora do denominador da acurácia). Roda por polling na tela e por cron. Taxa de acerto = acertos / (acertos + stops), onde acertos incluem alvo e alvo_parcial; break_even e expirada ficam fora do denominador.

Acurácia por ambiente (produção/homologação). A acurácia dos dois motores (Clássico e Stormer) e o histórico da automação passam a refletir o ambiente ativo no seu perfil: ao alternar entre produção e homologação (testnet), as taxas de acerto e as listagens mostram só as análises daquele ambiente. Os testes que você fez na homologação não contam na acurácia de produção, e vice-versa.

Para cada previsão resolvida, o "resultado real" do mercado é derivado do desfecho (alvo = direção do viés; stop = inverso). Comparando o voto de cada indicador com esse resultado, apura-se a taxa de acerto por chave. Os pesos são reescalados por 1 + intensidade·(taxa−50)/50 (mín. de amostras 10, peso entre 0 e 5). As chaves de derivativos e contexto BTC entram nessa calibração como quaisquer outras quando há amostras.

A calibração aprende só de produção. Diferente da acurácia (que você vê por ambiente), o autoaprendizado de pesos e de confiança — e o desempenho por setup injetado no prompt do Stormer — usa apenas o histórico de produção. Como os pesos ajustados são aplicados quando você opera de verdade, as validações feitas na homologação (testnet) não entram nesse aprendizado para não distorcê-lo.

Arquitetura: o backend calcula todos os indicadores de 3 timeframes — uma pilha alto/médio/operacional (padrão 1d + 4h + 15m; na automação o operacional é configurável, e a pilha de contexto acompanha) —, classifica o regime Stormer de cada TF (ALTA_ESTRUTURAL, ALTA_EM_CORRECAO, LATERAL, BAIXA_EM_REPIQUE, BAIXA_ESTRUTURAL) e detecta os 9 setups com funções puras determinísticas. A IA recebe um payload com booleanos e números já prontos — ela valida a confluência top-down, aplica vetos e escreve o plano operacional. Nunca faz aritmética de indicador.

• Regime top-down obrigatório: 1D define o viés, 4H confirma ou nega, 15M fornece o gatilho.
• Éden dos Traders: condição close > MME8 > MME80 com inclinação positiva da MME80 — base do filtro de tendência.
• Vetos automáticos (V1–V7): ATR fora da faixa, volume fraco, evento macro, funding rate extremo, pavio anômalo e baixa liquidez de fim de semana.
• Plano completo: gatilho de entrada (ordem STOP), stop loss, alvo parcial em 1R e alvo final com gestão de parcial + break-even.
• Temperatura 0: a IA opera de forma maximamente determinística — setup é regra, não interpretação.

Cada setup inclui campos de contexto para a IA: volume_confirmado (S3/S7/S9 — se falso, confiança é rebaixada por V2), regime_favoravel (S4 — se está em alta ou perto de suporte), eden_alinhado (S6 — se close > MME8 > MME80), pavio_anomalo (todos — pavio > 3× corpo médio aciona veto V7). O S5 é detectado no snapshot do 4h (não no 15m), conforme o método original. Em mercados laterais nos 3 TFs, o batch descarta o par sem chamar a IA (pré-filtro de regime).

Piso de stop por ATR. Depois que a IA responde, o plano passa por um filtro que impede stops apertados demais (causa comprovada de baixa acurácia em setups de pullback como o S2): se a distância entrada→stop for menor que 1× ATR do TF operacional (fallback 0,6% quando não há ATR), o stop é afastado até o mínimo e o alvo parcial (1R), o alvo final e o R:R são recalculados — preservando a relação risco/retorno declarada, com piso de 2R.

A resolução reutiliza a mesma lógica de avaliarDesfechoGeridoComExpiracao do sistema clássico. O mapeamento de campos é: gatilho_entrada → entrada, stop_loss → stop, alvo_final → alvo1, alvo_parcial_1r → alvo2 (para gestão com parcial + break-even). A acurácia é calculada por setup_id (S1–S9), decisão (COMPRA/VENDA) e par. Persiste em analises_stormer com os mesmos status: alvo, alvo_parcial, stop, expirada, sem_plano.

O rank é determinístico sobre o ticker de 24h. A análise clássica em lote descarta moedas com |score| < score_minimo (padrão 25) antes de chamar a IA. A análise Stormer em lote pré-filtra por regime: pares com 3 TFs em LATERAL ou BAIXA_ESTRUTURAL em 1D+4H são descartados sem custo de tokens e marcados como descartada_regime. Concorrência de IA: 4 workers no clássico, 9 no Stormer (o prompt caching mantém o custo baixo com o system prompt estável, permitindo mais paralelismo sem estourar o rate limit). Persistência é fire-and-forget no Stormer para não bloquear a resposta.

A abertura usa endpoints assinados da Binance (chave por usuário, criptografada). São enviadas a ordem de entrada (MARKET, ou LIMIT com timeInForce GTC; GTX quando post-only) e as ordens condicionais de TP/SL (Algo Service). Se a criação do TP/SL falhar, há limpeza automática (fecha a posição e cancela órfãs) para não deixar risco descoberto.

Preço de entrada real. Em MARKET a resposta da ordem costuma vir com avgPrice zerado, então o preço é resolvido por uma cascata: avgPrice → preço da ordem → média ponderada dos fills da própria ordem (userTrades por orderId) → preço de referência do dimensionamento. Uma LIMIT que fica pendente registra o próprio preço limite.

Reconciliação (Sincronizar). Compara os trades binance-live ainda abertos com as posições reais da conta. Para os que já não têm posição, deriva o preço de saída EXATO dos fills de fechamento (lado oposto à direção, realizedPnl ≠ 0, posteriores à abertura) e grava pnl_valor com o PnL realizado real; sem fills, cai num fallback por mark price. A reconciliação também repara trades já fechados que ficaram sem entrada (reconstruindo-a pelos fills de abertura) e trades fechados pelo fallback que ficaram sem pnl_valor — assim que os fills aparecem, o PnL realizado real é preenchido e o trade passa a contar nas métricas financeiras. A seção "Registros em aberto no journal" só aparece como rede de segurança quando um trade não pôde ser fechado automaticamente (edição manual de entrada/saída). O painel também mostra uma sugestão de tamanho por risco (ver seção seguinte).

Orquestração. O job /api/cron/shadow (protegido por CRON_SECRET, agendado por hora) processa só os usuários que ativaram a automação. Para cada um, chama as quatro rotas de análise em lote (Clássico e Stormer × top-volume e gemas), cruza os resultados por par e aplica o funil puro (lib/shadow/funil.ts). O botão "Rodar agora" (/api/shadow/run) faz o mesmo sob demanda, para o usuário logado.

Autoria das análises. As chamadas internas às rotas de análise levam o CRON_SECRET e o id do usuário, de forma que as análises geradas pela automação ficam vinculadas a você e entram na sua acurácia (Clássico e Stormer) — não ficam órfãs. Sem o segredo válido, o id é ignorado (um cliente comum não forja autoria de terceiros).

Alavancagem efetiva e guarda de liquidação. A alavancagem usada é min(desejada, teto do par) — o teto vem do leverageBracket da Binance, resolvendo o caso "20x não dá, 10x dá". A guarda rejeita o candidato quando |entrada − stop| / entrada alcança a distância de liquidação da alavancagem (≈ 1/alavancagem), pois a posição seria liquidada antes de a tese ser invalidada.

Critérios no funil. As escolhas de aprovação são campos da config (fontes_exigidas, ordenacao, setups_permitidos) e entram no funil puro. Fontes usam a direção efetiva de cada motor; Só concordância reprova unilaterais; a priorização é uma ordenação lexicográfica (o critério escolhido primeiro, depois os demais como desempate). O setup do Stormer de cada sinal é persistido (setup_stormer), o que habilita o filtro de setup e o painel de desempenho por setup.

Timeframe operacional configurável. Os campos timeframe_classico (padrão 15m) e timeframe_stormer (padrão 1h) da config definem o horizonte de geração E de resolução de cada motor. O batch usa esse TF ao montar a análise e o grava no sinal (shadow_sinais.timeframe) e na análise (analises_ia.timeframe / analises_stormer.timeframe_operacional), de modo que a resolução do desfecho busca candles no MESMO horizonte. No Stormer, a pilha multi-TF de contexto acompanha o operacional (ex.: operacional 1h → contexto 1w/1d), mantendo a leitura top-down do método.

Proteção de regime adverso. O gate protecao_regime_adverso (config, padrão ligado) reprova a tese contra a tendência ESTRUTURAL dominante. A tendência de fundo é lida dos timeframes superiores do Stormer (1D, com apoio do 4H) — não do TF operacional — para que um pullback no curto prazo dentro de uma tendência de fundo NÃO bloqueie a entrada a favor dela. É uma camada de RISCO no funil (não altera a geração dos motores): protege PnL e drawdown mantendo a automação fora de entradas contra-tendência de baixa taxa de acerto, sem forçar a direção oposta.

Execução real. Ligada por usuário (executar_binance), abre cada aprovado a mercado com a chave do próprio usuário (reusa o abrirOrdem da tela de Trades) e registra no diário com origem binance-live — vinculando à análise clássica quando ela existe — daí aparecer no histórico e ser reconciliado no fechamento. Cada tentativa registra o resultado (aberto / pulado / falha, com o motivo) no próprio sinal.

Não empilhar a mesma aposta. Além da trava por par já aberto, o orçamento considera as posições vivas de rodadas anteriores (o teto de trades vale sobre a conta, não só sobre a rodada) e a correlação com o que já está aberto — um candidato no mesmo par+direção de uma posição viva é reprovado como ja_posicionado.

Concorrência e reinício (execução segura). Um lock por usuário impede que o cron horário e o "Rodar agora" rodem em paralelo e dupliquem ordens (o segundo disparo é recusado enquanto o primeiro roda; o lock tem TTL para não travar num crash). Antes de enviar, o candidato é marcado como enviando, e a ordem de entrada usa um id de cliente determinístico por rodada+par: se o processo reiniciar, uma reexecução não abre a posição duas vezes — a própria Binance rejeita o id duplicado (tratado como já processado). A decisão de executar em modo real é relida no momento do envio, então desligar "Abrir trades" durante uma rodada em andamento impede o disparo.

Placar e desfechos. Os agregados (avaliados, aprovados, alvos/stops, taxas) são contados no banco sobre todo o histórico — não sobre a janela exibida — então não oscilam conforme você pagina. A taxa realizada conta só sinais com execução aberta. A resolução dos candidatos reusa a mesma lógica anti-look-ahead das previsões (descarta a vela em formação, só candles após a criação, empate intra-candle conta como stop) e roda ao abrir a tela, no "Atualizar" e no cron. Tudo é opt-in; parâmetros e faixas são validados no servidor (margem > 0, alavancagem 1–125, máx. 1–20 trades; ordenação, fontes e setups restritos aos valores válidos).

Parâmetros de gestão configuráveis (por usuário, na tela de Automação, persistidos em shadow_config):

• modo_sizing (valor | risco) e risco_usd — dimensionamento da posição (ver seção Sizing).
• rr_min — R:R mínimo exigido do candidato (assimetria "perder pouco"; padrão 1,5). Aplicado no funil.
• gatilho_breakeven_r — break-even simples em N×R (0 = desligado).
• usar_gestao_avancada — liga a gestão avançada (parcial + trailing), substituindo o break-even simples; com gatilho_parcial_r, fracao_parcial e trailing_atr_mult.

Defaults preservam o comportamento anterior: a gestão avançada vem desligada (opt-in, pois muda a posição ao vivo). Recomenda-se validar em modo shadow antes de ligar com capital real.

risco em USDT = capital × risco%/100; quantidade = risco ÷ |entrada − stop|; notional = quantidade × entrada; margem = notional ÷ alavancagem. Requer entrada, stop e capital.

Três modos de dimensionamento na execução (capitalModo em abrirOrdem):

• valor — margem fixa em USDT (histórico). A perda no stop VARIA conforme a distância do stop.
• pct — margem = % do saldo disponível.
• risco — dimensiona a quantidade por risco ÷ |entrada − stop|, de modo que a perda no stop seja ~constante entre trades (a margem vira consequência). É o modo recomendado para o objetivo "perder pouco". Disponível na ordem manual e na automação.

Custo total = (taxa por perna + slippage por perna) × 2 (ida e volta). Padrões conservadores: taker 0,05% e slippage 0,02% por perna, ajustáveis. O resultado líquido = bruto − custo total, sempre subtraído (reduz ganho e amplia perda). Aplicado na simulação realista do backtest e disponível para o cálculo de resultado do diário.

Resultado percentual: long = (saída−entrada)/entrada; short = o inverso. Win rate = trades com resultado > 0 sobre os fechados. Há agregação por símbolo e por período (7d/30d/90d/tudo) e curva de capital acumulada. Além do win-rate, a tela mostra métricas de risco: expectativa por trade (pWin·ganho médio − pLoss·perda média), profit factor (ganhos ÷ perdas) e max drawdown (maior queda pico-a-vale da curva). Essas métricas revelam se a estratégia é lucrativa mesmo com win-rate abaixo de 50% — o que importa é a expectativa, não só a taxa de acerto.

Separação por ambiente (produção/homologação). Cada trade guarda o ambiente em que foi aberto. Ao alternar entre produção e homologação (testnet) no perfil, o diário e a performance passam a mostrar só os trades do ambiente ativo — os testes feitos na homologação não contaminam as métricas de produção, e vice-versa. Os dados de mercado (candles, preços, indicadores) são sempre de produção; só a parte da sua conta (ordens e trades) segue o ambiente escolhido.

O envio é best-effort: o módulo lib/notificacoes/ formata a mensagem (função pura) e a despacha ao Telegram numa casca que NUNCA lança — se o Telegram cair, faltar a chave do bot ou a rede falhar, a notificação é engolida sem afetar o trade. Os gatilhos ficam no caminho da automação: abertura (executar-trades), saída parcial e stop movido (gestão de saída) e o desfecho pela verdade real do trade fechado (executar-resolucao-shadow).

Importante: o alvo e o stop só disparam notificação pela verdade real — o trade de fato fechado na conta (lucro → alvo, prejuízo → stop) —, nunca por uma mecha que apenas tocou o nível sugerido com a posição ainda aberta. O chat_id é guardado cifrado (AES-256-GCM) e jamais volta ao navegador: a tela só sabe se está conectado e se as notificações estão ligadas.

Janela deslizante reusando montarSnapshot (mesma lógica de produção, incluindo o regime). A simulação realista ancora stop/alvo em múltiplos de ATR (1,5× e 3× por padrão), resolve o desfecho com path-dependency (mesma lógica de tracking) e aplica custos, produzindo taxaAcerto, expectativa e profitFactor líquidos. Limitação: os dados de derivativos e o contexto BTC não são backtestáveis com candles puros (ficam ausentes); o backtest reflete os indicadores técnicos + regime.

Candles são cacheados em candles_cache com TTL por timeframe; scalping ignora o cache para dados frescos. Endpoints públicos (klines, ticker, derivativos) não são assinados; conta e ordens usam assinatura HMAC. Erros de rate limit (429/418) e símbolo inválido são tipados e tratados.

Frescor na interface. Os dados ao vivo (preço, posições, saldo, P&L aberto e candles) seguem o padrão stale-while-revalidate: ao voltar a uma tela, ela reexibe o último valor conhecido imediatamente e revalida em segundo plano — sem piscar "carregando" e sem exigir recarregar a página. O polling continua ativo (preço/posições a cada 5s, saldo a cada 15s, candle ao vivo via stream) e retoma na hora quando a aba volta ao foco. Um F5 limpa esse cache de sessão e recarrega do zero. As transições entre páginas mostram esqueletos (skeletons) enquanto a próxima tela monta.

Proteção de custo/escala. Os endpoints caros (análise em lote) e os públicos de mercado (klines, preço, screener) têm rate limiting por usuário/IP — uma janela deslizante que barra loops e abuso com HTTP 429, sem atrapalhar o uso normal. O candles_cache tem retenção por timeframe (job diário): velas curtas expiram em dias, as diárias/semanais ficam anos, mantendo o banco compacto sem perder histórico relevante.

O perfil (perfis_usuario) carrega role (user/admin), status (active/inactive) e plano (free/pro) + plano_expira_em. O isolamento por usuário (RLS) é reforçado por policies de admin via a função is_admin() (SECURITY DEFINER, evita recursão de RLS). A autorização das rotas passa por um helper único requireUsuario (401 sem sessão, 403 conta inativa) e requireAdmin; o proxy protege as rotas do app e redireciona contas inativas. O gate de plano requerPlano('pro') já existe para fechar features pagas quando a cobrança for ligada (considera a expiração). A gestão usa /api/admin/usuarios (service role), com trava que impede o admin de desativar ou rebaixar a própria conta.