tradermonty/vcp-screener

VCP Screener - Padrão de Contração de Volatilidade de Minervini

Selecione ações do S&P 500 para o Padrão de Contração de Volatilidade (VCP) de Mark Minervini, identificando ações em tendência de Estágio 2 com volatilidade em contração perto de pontos de pivô de rompimento.

Quando Usar

• O usuário pede varredura de VCP ou setups estilo Minervini
• O usuário quer encontrar padrões de base apertada / contração de volatilidade
• O usuário solicita varredura de ações momentum de Estágio 2
• O usuário pede candidatos a rompimento com risco definido
• O usuário pede "encontre todo VCP histórico em " ou quer estudar setups passados de VCP de um ticker com resultados futuros (--history --ticker SYM)

Pré-requisitos

• Chave da API FMP (defina a variável de ambiente FMP_API_KEY ou passe --api-key)
• O nível gratuito (250 chamadas/dia) é suficiente para a varredura padrão (top 100 candidatos)
• Recomenda-se o nível pago para varredura completa do S&P 500 (--full-sp500)

Fluxo de Trabalho

Passo 1: Preparar e Executar a Varredura

Execute o script de varredura VCP:

# Padrão: S&P 500, top 100 candidatos
python3 skills/vcp-screener/scripts/screen_vcp.py --output-dir skills/vcp-screener/scripts

# Universo personalizado
python3 skills/vcp-screener/scripts/screen_vcp.py --universe AAPL NVDA MSFT AMZN META --output-dir skills/vcp-screener/scripts

# S&P 500 completo (nível de API pago)
python3 skills/vcp-screener/scripts/screen_vcp.py --full-sp500 --output-dir skills/vcp-screener/scripts

Modo Estrito (setup puro de Minervini)

Retorne apenas ações com valid_vcp=True E execution_state em (Pre-breakout, Breakout):

python3 skills/vcp-screener/scripts/screen_vcp.py --strict --output-dir reports/

Modo histórico de ticker único

Percorra o histórico de vários anos de um ticker, detecte cada VCP que já se formou e anexe estatísticas de resultado futuro (rompimento / stop atingido / tempo esgotado, dias até o resultado, ganho máximo, perda máxima) por detecção. Útil para estudo de padrões e contexto de backtesting — não é um screener em tempo real.

# Padrão: varredura de ~5 anos (1260 dias de negociação), passo de 5 dias, janela de resultado de 60 dias
python3 skills/vcp-screener/scripts/screen_vcp.py \
  --history --ticker FIX --output-dir reports/

# Comprimento de varredura personalizado: 750 dias de negociação (~3 anos), janela de resultado de 90 dias
python3 skills/vcp-screener/scripts/screen_vcp.py \
  --history 750 --ticker TSLA \
  --stride-days 5 --outcome-days 90 \
  --output-dir reports/

# Varredura longa: 10 anos (2520 dias de negociação)
python3 skills/vcp-screener/scripts/screen_vcp.py \
  --history 2520 --ticker NVDA --output-dir reports/

Saídas (com carimbo de data/hora):

• vcp_history_<SYM>_<YYYY-MM-DD_HHMMSS>.json — linha do tempo das detecções com payload completo do analisador + forward_outcome por detecção + estatísticas resumidas.
• vcp_history_<SYM>_<YYYY-MM-DD_HHMMSS>.md — linha do tempo legível por humanos.

Flags específicas do modo:

Parâmetro	Padrão	Intervalo	Efeito
--history [DAYS]	(desligado) / 1260 se vazio	100-5040	Habilita o modo histórico; opcionalmente especifica a janela de varredura em dias de negociação (requer --ticker)
--ticker SYM	—	—	Ticker a ser varrido
--stride-days	5	1-60	Passo em dias de negociação entre posições do cursor "as-of"
--outcome-days	60	5-252	Janela futura avaliada por detecção

Notas:

• Duas chamadas à API FMP por varredura (histórico do ticker + SPY), não 100+ como no pipeline transversal.
• marketCap e percentil RS absoluto refletem o ticker isoladamente, não contra o universo de varredura ao vivo — use este relatório para estudo de padrões, não para dimensionamento de portfólio.
• As detecções são desduplicadas por (T1_high_date, last_low_date, pivot) para que o mesmo VCP não seja relatado repetidamente à medida que o cursor envelhece.

Ajuste Avançado (para backtesting)

Ajuste os parâmetros de detecção de VCP para pesquisa e backtesting:

python3 skills/vcp-screener/scripts/screen_vcp.py \
  --min-contractions 3 \
  --t1-depth-min 12.0 \
  --breakout-volume-ratio 2.0 \
  --trend-min-score 90 \
  --atr-multiplier 1.5 \
  --output-dir reports/

Parâmetro	Padrão	Intervalo	Efeito
--min-contractions	2	2-4	Mais alto = menos padrões, mas de maior qualidade
--t1-depth-min	10.0%	1-50	Mais alto = exclui primeiras correções rasas
--breakout-volume-ratio	1.5x	0.5-10	Mais alto = confirmação de volume mais rigorosa
--trend-min-score	85	0-100	Mais alto = filtro de Estágio 2 mais rigoroso
--atr-multiplier	1.5	0.5-5	Mais baixo = detecção de swing mais sensível
--contraction-ratio	0.70	0.1-1	Mais baixo = requer contrações mais apertadas
--min-contraction-days	5	1-30	Mais alto = contração mínima mais longa
--lookback-days	120	30-365	Mais longo = encontra padrões mais antigos
--max-sma200-extension	50.0%	—	Limite de distância da SMA200 para estado de sobre-extensão e penalidade
--wide-and-loose-threshold	15.0%	—	Profundidade da contração final acima da qual a flag wide-and-loose é acionada
--strict	desligado	—	Modo estrito Minervini: apenas Pré-rompimento ou Rompimento com VCP válido

Passo 2: Revisar Resultados

1. Leia os relatórios JSON e Markdown gerados
2. Carregue references/vcp_methodology.md para contexto de interpretação de padrões
3. Carregue references/scoring_system.md para orientação de limites de pontuação

Passo 3: Apresentar Análise

Para cada candidato principal, apresente:

• Qualidade (composite_score / classificação) — quão bem formado é o padrão VCP?
• Estado de Execução (execution_state) — é comprável agora? (Pré-rompimento / Rompimento = acionável)
• Tipo de Padrão (pattern_type) — VCP Texto / VCP-adjacente / Pós-rompimento / Líder Estendido / Danificado
• Marcador ★ se um Teto de Estado foi aplicado (pontuação bruta foi rebaixada)
• Detalhes da contração (profundidades e proporções T1/T2/T3)
• Setup de negociação: preço do pivô, stop-loss, percentual de risco
• Taxa de secagem de volume e pontuação de volume de rompimento
• Classificação de força relativa

Passo 4: Fornecer Orientação Acionável

Por Estado de Execução (filtro primário):

• Pré-rompimento / Rompimento: O padrão está na janela de entrada ativa — aplique dimensionamento baseado na classificação
• Início-pós-rompimento: Rompimento em andamento, mas acima da entrada ideal — tamanho reduzido ou aguarde pullback
• Estendido / Sobreextendido: Negociação perdida — adicione à lista de observação para a próxima base
• Danificado / Inválido: Setup invalidado — não entre

Por Classificação (secundário, após o estado confirmar a acionabilidade):

• VCP Texto (90+): Compre no pivô com dimensionamento agressivo (1.5-2x)
• VCP Forte (80-89): Compre no pivô com dimensionamento padrão (1x)
• VCP Bom (70-79): Compre na confirmação de volume acima do pivô (0.75x)
• Em Desenvolvimento (60-69): Adicione à lista de observação, aguarde contração mais apertada
• VCP Fraco/Sem VCP (<60): Apenas monitore ou pule

Pipeline de 3 Fases

1. Pré-Filtro - Triagem baseada em cotações (preço, volume, posição em 52 semanas) ~101 chamadas de API
2. Template de Tendência - Filtro de Estágio 2 de 7 pontos com históricos de 260 dias ~100 chamadas de API
3. Detecção de VCP - Análise de padrões, pontuação, geração de relatórios (nenhuma chamada de API adicional)

Saída

• vcp_screener_YYYY-MM-DD_HHMMSS.json - Resultados estruturados
• vcp_screener_YYYY-MM-DD_HHMMSS.md - Relatório legível por humanos

Recursos

• references/vcp_methodology.md - Teoria do VCP e explicação do Template de Tendência
• references/scoring_system.md - Limites de pontuação e pesos dos componentes
• references/fmp_api_endpoints.md - Endpoints da API e limites de taxa