Vcp Screener
Screen S&P 500 names for volatility-contraction-pattern setups using Financial Modeling Prep quotes and ~260-day price history within a daily API budget.
Overview
vcp-screener is an agent skill for the Idea phase that maps FMP API calls and budgets for volatility-contraction-pattern screening of S&P 500 stocks.
Install
npx skills add https://github.com/tradermonty/claude-trading-skills --skill vcp-screenerWhat is this skill?
- Documents four FMP endpoints: S&P 500 constituents, batch quotes (5 symbols per call), and 260-day historical price seri
- Default run budgets ~203 API calls (up to ~350 with --full-sp500)
- Three-phase flow: universe definition, pre-filter via batch quotes, trend template plus VCP detection on histories
- Built-in rate limiting with 0.3s delay between requests and retry on HTTP 429
- In-memory session cache to avoid duplicate API requests
- ~203 API calls on default screening path
- ~350 API calls with --full-sp500
- 250 API calls per day on FMP free tier
Adoption & trust: 567 installs on skills.sh; 1.8k GitHub stars; 3/3 security scanners passed (skills.sh audits).
What problem does it solve?
You want systematic VCP candidates from large-cap U.S. equities but lack a documented FMP call plan, endpoints, and daily API limits.
Who is it for?
Solo traders or builders automating equity idea generation who already use or plan FMP and need VCP-style screening with explicit API math.
Skip if: Builders without market-data API access, non-U.S. universes, or teams that need live execution, brokerage integration, or compliance review in this skill.
When should I use this skill?
When implementing or operating a VCP stock screener that pulls S&P 500 constituents, batch quotes, and one-year histories from Financial Modeling Prep.
What do I get? / Deliverables
You get a phase-by-phase endpoint map, expected call counts, caching, and rate-limit rules so an agent can run or implement the screener within FMP quotas.
- Documented FMP endpoint usage by screener phase
- API budget table for default vs full S&P 500 runs
Recommended Skills
Journey fit
Canonical shelf is Idea because the skill’s output is a ranked trade-research universe before you commit capital or automate execution. Research subphase fits discovery scans and trend-template filtering rather than shipping code or running live monitoring.
How it compares
Use for FMP-backed equity scan orchestration instead of generic web-research prompts with no call budget or endpoint contract.
Common Questions / FAQ
Who is vcp-screener for?
Independent builders and traders who want agent-guided VCP screening over S&P 500 names using Financial Modeling Prep with predictable daily API usage.
When should I use vcp-screener?
Use during Idea research when you need constituents, batch quotes, and one-year histories to filter trends and VCP setups, or when implementing the screener pipeline in your repo.
Is vcp-screener safe to install?
Review the Security Audits panel on this Prism page and treat any market-data API keys as secrets; the skill implies network calls to third-party financial APIs.
SKILL.md
READMESKILL.md - Vcp Screener
# FMP API Endpoints Used by VCP Screener ## Endpoints ### 1. S&P 500 Constituents - **URL:** `GET /api/v3/sp500_constituent` - **Calls:** 1 (cached) - **Returns:** `[{symbol, name, sector, subSector}, ...]` - **Used in:** Phase 1 - Universe definition ### 2. Batch Quote - **URL:** `GET /api/v3/quote/{symbols}` (comma-separated, max 5) - **Calls:** ~101 (503 stocks / 5 per batch) - **Returns:** `[{symbol, price, yearHigh, yearLow, avgVolume, marketCap, ...}]` - **Used in:** Phase 1 - Pre-filter ### 3. Historical Prices - **URL:** `GET /api/v3/historical-price-full/{symbol}?timeseries=260` - **Calls:** 1 (SPY) + up to 100 (candidates) - **Returns:** `{symbol, historical: [{date, open, high, low, close, adjClose, volume}, ...]}` - **Used in:** Phase 2 - Trend Template, Phase 3 - VCP detection ## API Budget Summary | Phase | Operation | API Calls | |-------|-----------|-----------| | 1 | S&P 500 constituents | 1 | | 1 | Batch quotes (503 / 5) | ~101 | | 2 | SPY 260-day history | 1 | | 2 | Candidate histories (max 100) | 100 | | **Total (default)** | | **~203** | | **Total (--full-sp500)** | | **~350** | ## Rate Limits - **Free tier:** 250 API calls/day - Default screening fits within this limit - **Starter tier ($29.99/mo):** 750 calls/day - **Rate limiting:** 0.3s delay between requests, automatic retry on 429 - **Caching:** In-memory session cache prevents duplicate requests ## Notes - All historical data uses `timeseries=260` parameter (260 trading days = ~1 year) - Phase 3 (VCP detection, scoring, reporting) requires NO additional API calls - The `--full-sp500` flag fetches histories for all pre-filter passers (~250 stocks) # VCP Screener Scoring System ## 5-Component Composite Score | Component | Weight | Source | |-----------|--------|--------| | Trend Template (Stage 2) | 25% | 7-point Minervini criteria | | Contraction Quality | 25% | VCP pattern detection | | Volume Pattern | 20% | Volume dry-up analysis | | Pivot Proximity | 15% | Distance from breakout level | | Relative Strength | 15% | Minervini-weighted RS vs S&P 500 | ## Component Scoring Details ### 1. Trend Template (0-100) Each of the 7 criteria contributes 14.3 points: | Criteria Passed | Score | Status | |-----------------|-------|--------| | 7/7 | 100 | Perfect Stage 2 | | 6/7 | 85.8 | Pass (minimum threshold) | | 5/7 | 71.5 | Borderline | | <= 4/7 | <= 57 | Fail | **Pass threshold:** Raw score >= 85 (6+ criteria) to proceed to VCP analysis. **SMA200 Extension Penalty** (metadata only -- NOT applied to the trend template score): | Price above SMA200 | Penalty (stored as metadata) | |--------------------|------------------------------| | > 70% | -20 | | > 60% | -15 | | > 50% | -10 | | > 40% | -5 | The SMA200 penalty is computed and stored in `sma200_penalty` / `sma200_distance_pct` for downstream use by the Execution State engine (Overextended classification). It is intentionally excluded from the trend template score to avoid double-penalizing with state caps. ### 2. Contraction Quality (0-100) | # Contractions | Base Score | |----------------|-----------| | 4 | 90 | | 3 | 80 | | 2 | 60 | | 1 or invalid | 0-40 | **Modifiers:** - Tight final contraction (< 5% depth): +10 - Good average contraction ratio (< 0.4 of T1): +10 - Deep T1 (> 30%): -10 ### 3. Volume Pattern (0-100) Based on dry-up ratio (`Zone B avg volume / 50-day avg`): | Dry-Up Ratio | Base Score | |-------------|-----------| | < 0.30 | 90 | | 0.30-0.50 | 75 | | 0.50-0.70 | 60 | | 0.70-1.00 | 40 | | > 1.00 | 20 | **Zone-based analysis (when contractions are provided):** - **Zone A**: Last contraction period (volume during tightening) - **Zone B**: Pivot approach — bars 1-10 (bar[0] excluded to avoid breakout contamination) - **Zone C**: Bar[0] if price > pivot (breakout bar volume) **Zone B is the dry-up source.** Bar[0] (potential breakout bar) is intentionally excluded from the dry-up calculation. Its quality is tracked separately via `breakout_volume_score`. **Break