tradermonty/vcp-screener

VCP Screener - Motif de contraction de volatilité Minervini

Analysez les actions du S&P 500 pour détecter le motif de contraction de volatilité (VCP) de Mark Minervini, en identifiant les actions en tendance haussière de Stage 2 avec une volatilité qui se contracte près de points de rupture.

Quand l'utiliser

• L'utilisateur demande un screening VCP ou des setups de type Minervini
• L'utilisateur veut trouver des motifs de base serrée / contraction de volatilité
• L'utilisateur demande une analyse d'actions momentum en Stage 2
• L'utilisateur cherche des candidats de breakout avec risque défini
• L'utilisateur demande « trouve chaque VCP historique dans » ou veut étudier les anciens setups VCP d'un ticker avec leurs résultats ultérieurs (--history --ticker SYM)

Prérequis

• Clé API FMP (définir la variable d'environnement FMP_API_KEY ou passer --api-key)
• Le niveau gratuit (250 appels/jour) suffit pour le screening par défaut (top 100 candidats)
• Niveau payant recommandé pour le screening complet du S&P 500 (--full-sp500)

Flux de travail

Étape 1 : Préparer et exécuter le screening

Lancez le script de screening VCP :

# Par défaut : S&P 500, top 100 candidats
python3 skills/vcp-screener/scripts/screen_vcp.py --output-dir skills/vcp-screener/scripts

# Univers personnalisé
python3 skills/vcp-screener/scripts/screen_vcp.py --universe AAPL NVDA MSFT AMZN META --output-dir skills/vcp-screener/scripts

# S&P 500 complet (niveau API payant)
python3 skills/vcp-screener/scripts/screen_vcp.py --full-sp500 --output-dir skills/vcp-screener/scripts

Mode strict (setup Minervini pur)

Ne renvoie que les actions avec valid_vcp=True ET execution_state dans (Pre-breakout, Breakout) :

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

Mode historique pour un seul ticker

Parcourez l'historique pluriannuel d'un ticker, détectez chaque VCP qui s'est jamais formé, et attachez des statistiques de résultats ultérieurs (breakout / stop hit / timeout, jours jusqu'au résultat, gain max, perte max) par détection. Utile pour l'étude de motifs et le contexte de backtest — pas un screener en temps réel.

# Par défaut : scan ~5 ans (1260 jours de trading), pas de 5 jours, fenêtre de résultat de 60 jours
python3 skills/vcp-screener/scripts/screen_vcp.py \
  --history --ticker FIX --output-dir reports/

# Longueur de scan personnalisée : 750 jours de trading (~3 ans), fenêtre de résultat de 90 jours
python3 skills/vcp-screener/scripts/screen_vcp.py \
  --history 750 --ticker TSLA \
  --stride-days 5 --outcome-days 90 \
  --output-dir reports/

# Scan long : 10 ans (2520 jours de trading)
python3 skills/vcp-screener/scripts/screen_vcp.py \
  --history 2520 --ticker NVDA --output-dir reports/

Sorties (horodatées) :

• vcp_history_<SYM>_<YYYY-MM-DD_HHMMSS>.json — chronologie des détections avec payload complet de l'analyseur + forward_outcome par détection + statistiques récapitulatives.
• vcp_history_<SYM>_<YYYY-MM-DD_HHMMSS>.md — chronologie lisible par un humain.

Drapeaux spécifiques au mode :

Paramètre	Défaut	Plage	Effet
--history [DAYS]	(désactivé) / 1260 si nu	100-5040	Activer le mode historique ; spécifier optionnellement la fenêtre de scan en jours de trading (nécessite --ticker)
--ticker SYM	—	—	Ticker à scanner
--stride-days	5	1-60	Pas en jours de trading entre les positions du curseur
--outcome-days	60	5-252	Fenêtre avant évaluée par détection

Notes :

• Deux appels API FMP par scan (historique du ticker + historique de SPY), pas 100+ comme le pipeline transversal.
• marketCap et le percentile RS absolu reflètent le ticker isolément, pas par rapport à l'univers de screening en direct — utilisez ce rapport pour l'étude de motifs, pas pour le dimensionnement de portefeuille.
• Les détections sont dédupliquées par (T1_high_date, last_low_date, pivot) afin que le même VCP ne soit pas signalé de manière répétée à mesure que le curseur vieillit.

Réglages avancés (pour le backtest)

Ajustez les paramètres de détection VCP pour la recherche et le backtest :

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/

Paramètre	Défaut	Plage	Effet
--min-contractions	2	2-4	Plus élevé = moins de motifs mais de meilleure qualité
--t1-depth-min	10.0%	1-50	Plus élevé = exclut les premières corrections peu profondes
--breakout-volume-ratio	1.5x	0.5-10	Plus élevé = confirmation de volume plus stricte
--trend-min-score	85	0-100	Plus élevé = filtre Stage 2 plus strict
--atr-multiplier	1.5	0.5-5	Plus bas = détection de swing plus sensible
--contraction-ratio	0.70	0.1-1	Plus bas = nécessite des contractions plus serrées
--min-contraction-days	5	1-30	Plus élevé = contraction minimale plus longue
--lookback-days	120	30-365	Plus long = trouve des motifs plus anciens
--max-sma200-extension	50.0%	—	Seuil de distance SMA200 pour l'état Overextended et la pénalité
--wide-and-loose-threshold	15.0%	—	Profondeur de contraction finale au-dessus de laquelle le drapeau wide-and-loose se déclenche
--strict	désactivé	—	Mode strict Minervini : uniquement Pre-breakout ou Breakout avec VCP valide

Étape 2 : Examiner les résultats

1. Lisez les rapports JSON et Markdown générés
2. Chargez references/vcp_methodology.md pour le contexte d'interprétation des motifs
3. Chargez references/scoring_system.md pour les conseils sur les seuils de score

Étape 3 : Présenter l'analyse

Pour chaque candidat principal, présentez :

• Qualité (composite_score / évaluation) — à quel point le motif VCP est bien formé ?
• État d'exécution (execution_state) — est-il achetable maintenant ? (Pre-breakout / Breakout = actionnable)
• Type de motif (pattern_type) — VCP textbook / VCP adjacent / Post-breakout / Leader étendu / Endommagé
• Marqueur ★ si un plafond d'état a été appliqué (score brut réduit)
• Détails de contraction (profondeurs et ratios T1/T2/T3)
• Configuration de trade : prix pivot, stop-loss, pourcentage de risque
• Ratio d'assèchement de volume et score de volume de breakout
• Rang de force relative

Étape 4 : Fournir des conseils actionnables

Par état d'exécution (filtre principal) :

• Pre-breakout / Breakout : Le motif est dans la fenêtre d'entrée active — appliquez un dimensionnement basé sur l'évaluation
• Early-post-breakout : Breakout en cours mais au-dessus de l'entrée idéale — taille réduite ou attendez un pullback
• Extended / Overextended : Trade manqué — ajouter à la liste de surveillance pour la prochaine base
• Damaged / Invalid : Setup invalidé — ne pas entrer

Par évaluation (secondaire, après que l'état confirme l'actionnabilité) :

• VCP textbook (90+) : Acheter au pivot avec un dimensionnement agressif (1.5-2x)
• VCP fort (80-89) : Acheter au pivot avec un dimensionnement standard (1x)
• Bon VCP (70-79) : Acheter sur confirmation de volume au-dessus du pivot (0.75x)
• En développement (60-69) : Ajouter à la liste de surveillance, attendre une contraction plus serrée
• VCP faible/aucun (<60) : Surveiller uniquement ou passer

Pipeline en 3 phases

1. Pré-filtre - Screening basé sur les cotations (prix, volume, position sur 52 semaines) ~101 appels API
2. Modèle de tendance - Filtre Stage 2 en 7 points avec historiques sur 260 jours ~100 appels API
3. Détection VCP - Analyse de motif, notation, génération de rapport (aucun appel API supplémentaire)

Sortie

• vcp_screener_YYYY-MM-DD_HHMMSS.json - Résultats structurés
• vcp_screener_YYYY-MM-DD_HHMMSS.md - Rapport lisible par un humain

Ressources

• references/vcp_methodology.md - Théorie VCP et explication du modèle de tendance
• references/scoring_system.md - Seuils de score et pondérations des composants
• references/fmp_api_endpoints.md - Points de terminaison API et limites de taux