⚙️ Fluxo do Sistema

O que acontece a cada hora, passo a passo.

Ciclo horário (cron: 2 * * * *)

Timings

• Vela 1H fecha ao minuto :00 de cada hora.
• Cron dispara às :02 — tempo para a Binance confirmar os dados.
• Gemini Flash: ~3–8 segundos. O dashboard atualiza a cada 60 s.

📡 Scanner de Mercado (scan_1h.py)

Fetch de 200 velas 1H, cálculo de indicadores, deteção de zonas e sinais de sweep.

Indicadores calculados

Zonas de S/R detectadas

O scanner usa lookback=5, n=12 pivôts recentes e agrupa zonas a 0.3% de tolerância. Exporta todas as zonas clusterizadas para o dashboard renderizar — resistências acima e suportes abaixo do preço. São exatamente estas zonas que aparecem no gráfico.

Como ler o Histograma MACD

O histograma MACD é o indicador visível no painel inferior do gráfico (barras coloridas). Representa a diferença entre a linha MACD (EMA 12 − EMA 26) e a linha de sinal (EMA 9 do MACD).

Exemplo do gráfico: barras verdes crescentes → compressão progressiva até ao pico → barras vermelhas crescentes indica o ciclo de momentum completo: impulso bullish, esgotamento, e transição para controlo bearish.

Filtro MACD obrigatório

• LONG só é gerado se o histograma MACD (MH) for > 0 — momentum bullish confirmado.
• SHORT só é gerado se MH for < 0 — momentum bearish confirmado.
• Sweeps válidos com MACD oposto são descartados (SIG=NONE).

Output (linha pipe-delimitada)

PX|E8|E21|E50|RSI|MH|MHP|BP|BM|ATR|VR|RES|SUP|ZONES_R|ZONES_S|ALL_R|ALL_S|SWP|SWL|SIG|TP|SL|SLD|QTY|MAR|NOT

• SWP=Y/N — Sweep detetado na última vela fechada.
• SIG — LONG, SHORT ou NONE (após filtro MACD).
• ALL_R / ALL_S — Todas as zonas clusterizadas (usadas no gráfico).
• SLD — Distância do stop loss em USDC (base do trailing).

🎯 Sinais de Liquidity Sweep

Deteção de varrimentos de liquidez em zonas de pivô com confirmação de MACD.

Lógica de deteção

• LONG (sweep bullish): o mínimo (low) perfura uma zona de suporte (−0.08% tolerância), mas o fecho fica acima dela e MACD histograma > 0.
• SHORT (sweep bearish): o máximo (high) perfura uma zona de resistência (+0.08% tolerância), mas o fecho fica abaixo dela e MACD histograma < 0.

Dimensionamento da posição

• SL distance = max(ATR × 1.2, preço × 0.5%)
• TP distance = SL × 2 → ratio risco/recompensa 1:2
• Margem = saldo × invest_pct (default 20%)
• Nocional = margem × alavancagem (default 10×)
• Quantidade BTC = nocional / preço

Em modo live, o saldo usado é o real consultado à Binance API no momento da abertura.

⚡ Gemini Flash — Análise e Decisão

Único modelo IA do sistema. Gera o relatório horário e decide se executa trades. Modelo: gemini-2.5-flash.

Relatório horário

O Flash recebe todos os dados do scanner e produz um relatório conciso em Português Europeu (PT-PT):

🕐 2026-05-01 09:02 (Lisboa) | BTC/USDC 1H Swing Scalper | 🤖 2.5 Flash
💰 $77125.21 | Alta | RSI 71.02 | Vol 0.62x
🏔️ Resistência: $77485.01 | 🛡️ Suporte: $76466.28
🎯 NENHUM⚪
📋 Estrutura bullish; observar $77485 para potencial sweep.

Decisão de trade (quando SIG ≠ NONE)

Se o scanner detetar sweep e não houver posição aberta, o Flash recebe o contexto completo e decide diretamente se executa:

• Avalia qualidade do sweep, alinhamento EMA, RSI, MACD, volume.
• Se confirmar → posição aberta imediatamente.
• Se rejeitar → apenas relatório, sinal registado nos logs.

Fallback local

Se a chave Gemini não estiver configurada ou ocorrer erro de API, o sistema gera um relatório local básico com os mesmos dados numéricos — sem IA.

📐 Gestão de Posição

Abertura, trailing stop, break-even e fecho manual ou automático.

Trailing Stop

O stop só avança na direção do lucro — nunca recua. Distância fixa igual ao SL inicial:

• LONG: novo máximo → SL sobe para novo_max − dist.
• SHORT: novo mínimo → SL desce para novo_min + dist.

Break-even automático

Quando o preço move 70% da distância de trail em favor da posição, o stop é movido automaticamente para o preço de entrada:

• LONG: se preço ≥ entrada + dist × 0.7 → SL = entrada (posição garantida sem perda).
• SHORT: se preço ≤ entrada − dist × 0.7 → SL = entrada.
• Notificação Telegram enviada quando o break-even é ativado 🔒.

Condições de fecho automático

• TP — Preço atinge o Take Profit.
• TRAIL_SL — Preço toca o trailing stop (ou break-even stop).

Stop Manual (segunda camada)

1. Com posição aberta, clica 📌 Stop M na barra de posição.
2. O cursor muda para crosshair — clica no gráfico para escolher o preço do stop manual.
3. A linha laranja mostra o PnL estimado se atingido. Podes reposicionar antes de confirmar.
4. Clica ✓ Definir Stop M para guardar, ou ✕ Cancelar para abortar.
5. O stop manual activo aparece no posbar; clica ✕ Cancelar Stop M para remover.
6. Se o trailing stop ultrapassar o stop manual, o trailing passa a ser o efectivo.

Fecho manual com stop no gráfico

1. Com posição aberta, clica ✕ Fechar na barra de posição.
2. O cursor muda para crosshair — clica no gráfico para posicionar a linha de fecho.
3. Podes clicar várias vezes para reposicionar. A linha mostra o PnL estimado a verde/vermelho.
4. Clica ✓ Confirmar para fechar ao preço escolhido, ou ✕ Cancelar para abortar.

PnL calculado

PnL = (saída − entrada) × qty para LONG; (entrada − saída) × qty para SHORT.

🗺️ Zonas de Suporte e Resistência

As zonas no gráfico são as mesmas que o scanner usa internamente — não uma aproximação visual.

Como são calculadas (scan_1h.py)

1. Pivôts — Para cada vela, verifica se é o máximo/mínimo das 5 velas à esquerda e direita (lookback=5).
2. Clustering — Os 12 pivôts mais recentes de cada lado são agrupados em zonas (tolerância 0.3%).
3. Exportação — Todas as zonas clusterizadas são salvas em price_triggers.json a cada análise horária.
4. Renderização — O dashboard lê essas zonas, determina o início de cada uma (candle de pivô mais próxima) e se foi quebrada por um fecho.

Visual no gráfico

• Zona ativa — linha sólida a vermelho (resistência) ou verde (suporte), com label de preço na direita.
• Zona quebrada — linha a 45% de opacidade, sem label.
• A linha estende-se desde a candle de origem até ao ponto de quebra (ou à vela atual se ainda ativa).

Atualização

As zonas são recalculadas a cada hora quando o analista corre. Podes forçar atualização com o botão ▶ Analisar.

📊 Dashboard — Ferramentas

Interface em tempo real com gráfico, MACD, zonas S/R do scanner, régua nativa e fecho manual.

Gráfico de velas

• Velas de 1H — verde escuro (#00824f) / vermelho escuro (#d8001b) para maximizar contraste com os marcadores.
• ● LONG — marcador e SAÍDA em cyan. ● SHORT — em amarelo.
• Atualização automática a cada 60 segundos.

MACD Histograma

Visível na base do gráfico (abaixo do volume). Barras coloridas em 4 tons:

• Verde forte — histograma positivo e a crescer (momentum bullish forte).
• Verde fraco — histograma positivo mas a encolher (momentum a perder força).
• Vermelho forte — histograma negativo e a crescer (momentum bearish forte).
• Vermelho fraco — histograma negativo mas a encolher.

Régua de Percentagem 📏

Botão 📏 (desktop ou FAB mobile). Ciclo de 3 estados:

1. 1º clique → ancora P1 com linha tracejada amarela.
2. 2º clique → ancora P2; label com % e $Δ fica presa no nível P2.
3. 3º clique → apaga a medição, mantém modo ativo para nova medição.

Para desligar o modo régua, carrega novamente no botão 📏 — o anel amarelo desaparece.

Contagem decrescente / ▶ Analisar

Próxima X:XX — conta até à próxima análise automática (às :02 UTC). O botão ▶ Analisar força execução imediata (~25 s) e atualiza gráfico e logs automaticamente.

Painel de Logs 📋

Últimas 100 análises em ordem cronológica inversa. Análises LONG têm borda verde; SHORT têm borda vermelha.

💼 Paper Trading vs Live Trading

Mesmo algoritmo — fontes de saldo diferentes.

📄 Paper Trading (predefinido)

• Saldo inicial: $400 USDC simulado.
• Ordens completamente simuladas — sem interação com a Binance.
• Estado persistido em paper_state_1h.json entre sessões.

⚡ Live Trading

• Requer BINANCE_API_KEY e BINANCE_API_SECRET no .env.
• O saldo exibido é o saldo real da Binance (Futures → Margin Isolada → Margin Cruzada → Spot).
• No momento de cada abertura de posição, o saldo real é consultado via API para calcular a margem/qty correta.
• Permite ajustar Alavancagem (1×–50×) e % Investimento (1%–50%) no painel ⚙️.

Considerações de alavancagem

• Em Margem Isolada BTC, a Binance permite tipicamente até 10× para Regular User.
• Com SL baseado em ATR 1H (~0.5–0.8% da entrada), até 30× é seguro — a liquidação ocorreria muito mais longe que o stop.
• Acima de 80×, o preço de liquidação aproxima-se perigosamente do stop — não recomendado.

✈️ Alertas Telegram

Mapa completo de todos os alertas enviados ao Telegram e quando surgem.

🔄 Fase de Mercado phase_watcher.py  ·  cron :07

Enviado apenas quando a fase muda (histerese de 2 candles).

• ⚡ EXPANSÃO detectada — MM a movimentar liquidez, volatilidade a aumentar
• 📈 TREND LONG confirmado — ADX > 25 + EMA stack bullish
• 📉 TREND SHORT confirmado — ADX > 25 + EMA stack bearish
• 🔵 CONTRACÇÃO detectada — ADX < 20, mercado a acumular

📊 Análise Horária auto_analyst_gemini.py  ·  cron :02

Enviado todas as horas (ou imediatamente após um TP).

• 🤖 2.5 Flash — análise Gemini com estrutura de mercado, RSI, padrões de vela e sinal
• 🤖 Local — fallback quando Gemini indisponível (sem raciocínio)
• 🔒 Break-even activado — quando o trailing stop move para a entrada

🤖 Gemini Indisponível auto_analyst_gemini.py

Enviado máximo 1x por hora enquanto o erro persistir.

• 🤖 Bot em modo LOCAL — spending cap, quota esgotada ou API key inválida

📈 Breakout price_watcher.py  ·  cron * * * *

Silenciado durante CONTRACÇÃO. Nas restantes fases:

• 🟢/🔴 Breakout Detectado — padrão confirmado (cunha, triângulo, canal…) com confiança alta
• ✅ Retest Confirmado — preço regressou ao nível e vela fechou a confirmá-lo
• ⚠️ Falso Breakout Invalidado — preço não segurou o nível

⚡ TTM Squeeze price_watcher.py  ·  cron * * * *

• ⚡ TTM Squeeze Activo — BB dentro de KC, mola a tensionar (máx 1 alerta por sessão de squeeze)
• 🔥 TTM Squeeze Disparado — BB saiu de KC, breakout potencial iminente

📂 Posição price_watcher.py + auto_analyst_gemini.py

• 🟢/🔴 Posição Aberta — entrada manual ou automática por sweep
• ✅ Take Profit — TP atingido
• 🛑 Stop Loss — SL atingido
• 📉 Trailing Stop — TRAIL_SL atingido
• 🔒 Break-even activado — SL movido para a entrada

Configuração

• TELEGRAM_BOT_TOKEN — Token do bot criado via @BotFather
• TELEGRAM_CHAT_ID — ID do chat/canal de destino
• Ambos configurados em /root/btc_scalper/.env