⚙️ Fluxo do Sistema

O que acontece a cada ciclo de análise, passo a passo.

Ciclo (cron: */5 * * * *)

Timings

• O scanner corre a cada 5 minutos, mas lê a última vela 1H fechada — não abre posições em velas em formação.
• O Gemini só é chamado quando há sinal (LONG/SHORT) ou quando passaram mais de 60 min desde a última chamada — poupa ~85% dos custos de API.
• Saídas por timeout (96 barras sem trail stop) e trailing stop (3× ATR dinâmico) estão implementadas.
• O dashboard atualiza a cada 60 s.

📡 MACD + Ranging Detection (scan_1h.py)

BTC/USDC 1H — ATP MACD Signal System com filtro de ranging: só entra quando o mercado tem momentum direcional claro.

Indicadores calculados

Condições para sinal válido

• LONG: hist cruza 0 de baixo para cima (hist > 0 e hist_prev ≤ 0) e MACD > 0 e NOT is_ranging.
• SHORT: hist cruza 0 de cima para baixo (hist < 0 e hist_prev ≥ 0) e MACD < 0 e NOT is_ranging.
• Ranging Detection: is_ranging = barsSinceHigh ≥ 1 AND barsSinceLow ≥ 1 onde barsSince é calculado em relação ao máximo/mínimo das últimas 50 barras. Quando a barra atual não é um extremo dos últimos 50 bares, o mercado está em ranging e os sinais são bloqueados.

Output (linha pipe-delimitada)

PX|MACD|SIG_LINE|HIST|ATR|RSI|IS_RANGING|RANGE_HIGH|RANGE_LOW|EMA_FILTER|EMA_TREND|SIG|TRAIL_SL|TP|SL|SLD|ENTRY|STRAT|SETUP|BIAS

• SIG — LONG, SHORT ou NONE.
• IS_RANGING — 1 se mercado em consolidação (sinal bloqueado), 0 se trending.
• RANGE_HIGH/LOW — máximo e mínimo das últimas 50 barras (limites do range atual).
• TRAIL_SL — nível de trail stop calculado a partir da entrada ± 3× ATR.

🎯 Sinais MACD + Ranging

Cruzamento MACD confirmado com zero-line filter e mercado em movimento — momentum real, não ruído de consolidação.

Lógica de entrada detalhada

• Cruzamento do histograma: o histograma (MACD − Signal) muda de sinal numa única barra — confirma que o momentum mudou de direção.
• Zero-line filter: a linha MACD tem de estar acima de zero (LONG) ou abaixo de zero (SHORT) — garante que a tendência principal está alinhada com o cruzamento.
• Anti-ranging: is_ranging = False — o preço tem de ter tocado o extremo de 50 barras recentemente, indicando que saiu da consolidação.
• Min bars between signals: mínimo de 3 barras entre sinais consecutivos (evita over-trading em cruzamentos rápidos).

Dimensionamento e saídas

• Trailing SL = entrada ∓ 3× ATR (dinâmico — avança com o preço na direção do lucro).
• TP = desactivado por default (tp_atr_mult=0) — só o trailing stop fecha a posição.
• Timeout: posição fechada ao fim de 96 barras sem trail stop atingido.
• Break-even automático: quando o preço avança 70% da distância do trail, o stop move-se para o preço de entrada.
• Margem = saldo × 20% · Nocional = margem × 10× alavancagem.

Presets MACD testados

• Scalping 5/13/3 — sinais rápidos, muita atividade, spreads maiores.
• Day Trading 8/21/5 — equilibrio entre velocidade e fiabilidade.
• Swing 12/26/9 — preset clássico de mercado, menos sinais mas mais fiáveis.
• Custom 14/28/9 — default deste sistema, adaptado ao BTC/USDC 1H.
• Position 24/52/18 — sinais de longo prazo, menor frequência.

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

⚡ Gemini Flash — Análise e Decisão

IA de suporte ao sistema MACD+Ranging. Analisa momentum, ranging e contexto de mercado, gera relatório em PT-PT. Modelo: gemini-2.5-flash.

Gate de chamada (economia de API)

O Gemini só é invocado se:

• O scanner emitir um sinal LONG ou SHORT, ou
• Tiver passado mais de 60 minutos desde a última chamada.

Nas restantes chamadas do cron (cada 5 min), o sistema gera um relatório local sem custo de API — apenas quando há sinal MACD ou é hora de actualização horária é que o Flash é chamado.

Relatório MACD + Ranging

O Flash recebe o estado completo do MACD e ranging e produz um relatório em Português Europeu (PT-PT):

🕒 2026-06-22 09:02 (Lisboa) | BTC/USDC 1H MACD | 🤖 2.5 Flash
💰 $105250.00 | MACD 0.0023 | RSI 58.4
📈 Ranging: NAO | Range $103100–$107800 | EMA100 trend BULL
🎯 NENHUM⚪
📋 Histograma positivo mas sem cruzamento — aguarda confirmação de momentum

Decisão de trade (quando SIG ≠ NONE)

Se o scanner emitir um cruzamento MACD válido e não houver posição aberta, o sistema abre directamente:

• Avalia MACD, histograma, ranging status, EMA trend e contexto de mercado.
• Se confirmar → posição aberta imediatamente com metadados MACD (macd, hist, ema_trend, is_ranging).
• Se rejeitar (ex: RSI extremo) → 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 com os dados numéricos do MACD e ranging — sem IA mas com toda a informação da estratégia.

📐 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. 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.

📊 Análise de ciclo auto_analyst_gemini.py  ·  cron */5

Enviado quando há sinal MACD ou quando passam mais de 60 min desde o último envio.

• 🤖 2.5 Flash — análise Gemini com MACD, ranging status, EMA100 trend e sinal
• 🤖 Local — relatório rápido sem custo quando Gemini está em gate (sem sinal, <60 min)

🤖 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

📈 MACD Signal auto_analyst_gemini.py

Enviado quando o cruzamento MACD é válido e o mercado não está em ranging:

• 📈 LONG — hist cruza 0↑ + MACD > 0 + NOT ranging
• 📉 SHORT — hist cruza 0↓ + MACD < 0 + NOT ranging

📂 Posição auto_analyst_gemini.py

• 🟢/🔴 Posição Aberta — entrada automática por sinal MACD ou manual pelo dashboard
• 🛑 Trailing Stop — stop dinâmico atingido (3× ATR da entrada)
• ⏱️ Timeout — 96 barras sem trail stop atingido
• 🔒 Break-even activado — SL movido para a entrada após movimento favorável

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