Value Dividend Screener
Overview
This skill identifies high-quality dividend stocks that combine value characteristics, attractive income generation, and consistent growth using a two-stage screening approach:
- FINVIZ Elite API (Optional but Recommended): Pre-screen stocks with basic criteria (fast, cost-effective)
- Financial Modeling Prep (FMP) API: Detailed fundamental analysis of candidates
Screen US equities based on quantitative criteria including valuation ratios, dividend metrics, financial health, and profitability. Generate comprehensive reports ranking stocks by composite quality scores with detailed fundamental analysis.
Efficiency Advantage: Using FINVIZ pre-screening can reduce FMP API calls by 90% and keeps API usage low. The stock-screener endpoint used by FMP-only mode is not on the free plan (2026-11); use --use-finviz or a plan that includes it (see docs/en/getting-started.md#fmp-plans).
When to Use
Invoke this skill when the user requests:
- "Find high-quality dividend stocks"
- "Screen for value dividend opportunities"
- "Show me stocks with strong dividend growth"
- "Find income stocks trading at reasonable valuations"
- "Screen for sustainable high-yield stocks"
- Any request combining dividend yield, valuation metrics, and fundamental analysis
Prerequisites
- FMP API key: Required. Set
FMP_API_KEYor pass--fmp-api-key. The stock-screener endpoint is not on the free plan (2026-11); use--use-finvizor an FMP plan that includes it (seedocs/en/getting-started.md#fmp-plans). - FINVIZ Elite API key: Recommended, not required. Set
FINVIZ_API_KEYor pass--finviz-api-keyand use--use-finvizfor two-stage screening. Without it the screener runs FMP-only and uses more API calls. - Python: 3.9+ with
requests>=2.31.0(seerequirements.txt).
Price-history quality
RSI screening needs at least 20 returned closing-price observations. Every close
in that history must be numeric, finite and positive. A candidate with missing
or invalid closes is skipped with RSI unavailable on stderr; valid candidates
continue. The full chronology and raw-close price basis are preserved. This
exclusion means the candidate could not be evaluated, not that it passed or
failed the oversold test.
Workflow
Step 1: Verify API Key Availability
For Two-Stage Screening (Recommended):
Check if both API keys are available:
import os
fmp_api_key = os.environ.get('FMP_API_KEY')
finviz_api_key = os.environ.get('FINVIZ_API_KEY')If not available, ask user to provide API keys or set environment variables:
export FMP_API_KEY=your_fmp_key_here
export FINVIZ_API_KEY=your_finviz_key_hereFor FMP-Only Screening:
Check if FMP API key is available:
import os
api_key = os.environ.get('FMP_API_KEY')If not available, ask user to provide API key or set environment variable:
export FMP_API_KEY=your_key_hereFINVIZ Elite API Key:
- Requires FINVIZ Elite subscription (~$40/month or ~$330/year)
- Provides access to CSV export of pre-screened results
- Highly recommended for reducing FMP API usage
Provide instructions from references/fmp_api_guide.md if needed.
Step 2: Execute Screening Script
Run the screening script with appropriate parameters:
Two-Stage Screening (RECOMMENDED)
Uses FINVIZ for pre-screening, then FMP for detailed analysis:
Default execution (Top 20 stocks):
python3 scripts/screen_dividend_stocks.py --use-finvizWith explicit API keys:
python3 scripts/screen_dividend_stocks.py --use-finviz \
--fmp-api-key $FMP_API_KEY \
--finviz-api-key $FINVIZ_API_KEYCustom top N:
python3 scripts/screen_dividend_stocks.py --use-finviz --top 50Custom output location:
python3 scripts/screen_dividend_stocks.py --use-finviz --output /path/to/results.jsonScript behavior (Two-Stage):
- FINVIZ Elite pre-screening:
- Market cap: Mid-cap or higher
- Dividend yield: 3%+
- Dividend growth (3Y): 5%+
- EPS growth (3Y): Positive
- P/B: Under 2
- P/E: Under 20
- Sales growth (3Y): Positive
- Geography: USA
- FMP detailed analysis of FINVIZ results (typically 20-50 stocks):
- Dividend growth rate calculation (3-year CAGR)
- Revenue and EPS trend analysis
- Dividend sustainability assessment (payout ratios, FCF coverage)
- Financial health metrics (debt-to-equity, current ratio)
- Quality scoring (ROE, profit margins)
- Composite scoring and ranking
- Output top N stocks to JSON file
Expected runtime (Two-Stage): 2-3 minutes for 30-50 FINVIZ candidates (much faster than FMP-only)
FMP-Only Screening (Original Method)
Uses only FMP Stock Screener API (higher API usage):
Default execution:
python3 scripts/screen_dividend_stocks.pyWith explicit API key:
python3 scripts/screen_dividend_stocks.py --fmp-api-key $FMP_API_KEYScript behavior (FMP-Only):
- Initial screening using FMP Stock Screener API (dividend yield >=3.0%, P/E <=20, P/B <=2)
- Detailed analysis of candidates (typically 100-300 stocks):
- Same detailed analysis as two-stage approach
- Composite scoring and ranking
- Output top N stocks to JSON file
Expected runtime (FMP-Only): 5-15 minutes for 100-300 candidates (rate limiting applies)
API Usage Comparison:
- Two-Stage: ~50-100 FMP API calls (FINVIZ pre-filters to ~30 stocks)
- FMP-Only: ~500-1500 FMP API calls (analyzes all screener results)
Step 3: Parse and Analyze Results
Read the generated JSON file:
import json
with open('dividend_screener_results.json', 'r') as f:
data = json.load(f)
metadata = data['metadata']
stocks = data['stocks']Key data points per stock:
- Basic info:
symbol,company_name,sector,market_cap,price - Valuation:
dividend_yield,pe_ratio,pb_ratio - Growth metrics:
dividend_cagr_3y,revenue_cagr_3y,eps_cagr_3y - Sustainability:
payout_ratio,fcf_payout_ratio,fcf_amount,fcf_status,fcf_coverage_status,sustainability_basis,dividend_sustainable,sustainability_bonus,sustainability_note - Financial health:
debt_to_equity,current_ratio,financially_healthy - Quality:
roe,profit_margin,quality_score - Overall ranking:
composite_score
Step 4: Generate Markdown Report
Create structured markdown report for user with following sections:
Report Structure
Read references/report_template.md for the full markdown report template.
In the human report, keep observed FCF and dividend coverage separate. Negative FCF means an observed shortfall; zero FCF means no cash coverage; MISSING_DATA means the source fields were unavailable. None proves a future dividend cut. AT_LIMIT means FCF equals dividends with no buffer and earns no bonus. For confirmed REITs, use FFO as the decision basis and show FCF status as context even when it is negative; do not apply FFO treatment to a company solely because its sector is Real Estate. Copy sustainability_note into the explanation rather than replacing an unknown status with a sustainability claim.
Step 5: Provide Context and Methodology
Reference screening methodology when explaining results:
Key concepts to explain:
- Why these specific thresholds (3.5% yield, P/E 20, P/B 2)
- Importance of dividend growth vs. static high yield
- How composite score balances value, growth, and quality
- Dividend sustainability vs. dividend trap distinction
- Financial health metrics significance
Load references/screening_methodology.md to provide detailed explanations of:
- Phase 1: Initial quantitative filters
- Phase 2: Growth quality filters
- Phase 3: Sustainability and quality analysis
- Composite scoring system
- Investment philosophy and limitations
Step 6: Answer Follow-up Questions
Read references/follow_up_questions.md for answers to common follow-up questions.
Resources
Read references/resource_descriptions.md for the description of the screening script and of each reference file.
Advanced Usage
Read references/advanced_usage.md to customize criteria, screen a sector, exclude REITs and financials or export CSV.
Troubleshooting
"ERROR: requests library not found"
The script prints this error to stderr and exits with status 2. The message includes the full path of this skill's requirements.txt, so the hint works from any directory.
Solution: Install the skill's dependencies
pip install -r skills/value-dividend-screener/requirements.txt"ERROR: FMP API key required"
Solution: Set environment variable or provide via command-line
export FMP_API_KEY=your_key_here
# OR
python3 scripts/screen_dividend_stocks.py --fmp-api-key your_key_here"ERROR: FINVIZ API key required when using --use-finviz"
Solution: Set environment variable or provide via command-line
export FINVIZ_API_KEY=your_key_here
# OR
python3 scripts/screen_dividend_stocks.py --use-finviz --finviz-api-key your_key_hereNote: FINVIZ Elite subscription required (~$40/month or ~$330/year)
"ERROR: FINVIZ API authentication failed"
Possible causes:
- Invalid FINVIZ API key
- FINVIZ Elite subscription expired
- API key format incorrect
Solution:
- Verify FINVIZ Elite subscription is active
- Check API key for typos (should be alphanumeric string)
- Log into FINVIZ Elite account and verify API key in settings
- Try accessing FINVIZ Elite screener manually to confirm subscription
"ERROR: FINVIZ pre-screening failed or returned no results"
Possible causes:
- FINVIZ API connection issue
- Screening criteria too restrictive (no stocks match)
- Market conditions (bear market may yield fewer results)
Solution:
- Check internet connection
- Verify FINVIZ Elite website is accessible
- Try FMP-only method as fallback:
python3 scripts/screen_dividend_stocks.py
"WARNING: Rate limit exceeded"
Solution: Script automatically retries after 60 seconds. If persistent:
- Wait until next day (free tier resets daily)
- Reduce number of stocks analyzed (modify line 394 limit)
- Consider upgrading to paid FMP tier
"No stocks found matching all criteria"
Solution: Criteria may be too restrictive
- Relax P/E threshold (increase from 20)
- Lower dividend yield requirement (decrease from 3.5%)
- Reduce dividend growth requirement (decrease from 5%)
- Check market conditions (bear markets may have fewer qualifiers)
Script runs slowly
Expected behavior: Script includes 0.3s delay between API calls for rate limiting
- 100 stocks analyzed = ~8-10 minutes
- First 20-30 qualifying stocks usually found within first 50-70 analyzed
Performance & Cost Optimization
Read references/performance_and_cost.md for API call comparison and cost analysis.
Version History
- v1.1 (November 2025): Added FINVIZ Elite integration for two-stage screening
- v1.0 (November 2025): Initial release with comprehensive multi-phase screening
Shared FMP client
FMP data access uses the bundled generated scripts/fmp_client.py. Existing CLI
key/environment precedence, financial calculations and successful output shapes
are preserved. The migrated paths use stable endpoints only; a denied or failed
stable request does not fall back to retired v3 URLs. The shared client masks raw
and URL-encoded key echoes, retries malformed JSON once, and retries a 429 once
with a 60-second wait before stopping on a repeated rate limit. FINVIZ, where
used, remains a separate client.