| name | quant-scanner |
| description | Quantitative stock scanner with model-driven adaptive factor scoring. Scans ~100 US large/mid-cap stocks via Finnhub API, detects market regime (volatility, momentum, breadth), dynamically adjusts factor weights, and produces ranked selection/anomaly lists with HTML reports. Use for US stock screening, quantitative stock picking, factor analysis, market regime detection, stock scoring, building a model portfolio, or finding momentum/value/quality plays. |
| version | 1.0.0 |
| homepage | https://finnhub.io |
| commands | ["/quant_scan - Run full US stock quantitative scan with HTML report","/quant_top - Quick top-10 stock picks","/quant_regime - Show current market regime analysis","/quant_analyze - Deep factor analysis on specific tickers"] |
| metadata | {"clawdbot":{"emoji":"📊","requires":{"bins":["python3"],"env":["FINNHUB_API_KEY"]},"install":[]}} |
Quant Scanner v1.0
Model-driven quantitative stock scanner for US equities. Scans ~100 large/mid-cap stocks, detects the current market regime, adaptively adjusts 5-factor scoring weights, and outputs ranked picks with an HTML report.
Setup
Required: A free Finnhub API key.
- Go to https://finnhub.io and sign up (free)
- Copy your API key from the dashboard
- Set it as an environment variable:
export FINNHUB_API_KEY="your_key_here"
Or pass it directly via --api-key:
python3 {baseDir}/scripts/quant_scan.py --api-key YOUR_KEY
Quick Commands
Full Scan (HTML + JSON report)
python3 {baseDir}/scripts/quant_scan.py
This will:
- Fetch quote, metrics, profile, and analyst recommendations for ~100 stocks
- Detect market regime (volatility, momentum, breadth)
- Score each stock on 5 adaptive factors
- Output a ranked list + HTML report
Quick Top 10
python3 {baseDir}/scripts/quant_scan.py --top 10
Specific Tickers Only
python3 {baseDir}/scripts/quant_scan.py --tickers AAPL,NVDA,TSLA,GOOGL,META
Custom Universe File
python3 {baseDir}/scripts/quant_scan.py --universe my_watchlist.txt
Where my_watchlist.txt has one ticker per line.
JSON Output Only (for piping)
python3 {baseDir}/scripts/quant_scan.py --format json
How It Works
5-Factor Adaptive Scoring
Each stock is scored on 5 factors. The weights adapt to the detected market regime:
| Factor | Base Weight | Bullish Adj | Bearish Adj | High-Vol Adj |
|---|
| Momentum (5D/13W/MTD return + relative strength vs S&P 500) | 30% | x1.3 boost | x0.7 dampen | — |
| Value (P/E, forward P/E, PEG, dividend yield) | 20% | x0.8 reduce | x1.3 boost | — |
| Quality (ROE, net margin, revenue growth, EPS growth) | 25% | — | — | x1.2 boost |
| Analyst Sentiment (buy/hold/sell consensus ratio) | 10% | — | — | — |
| Risk-Adjusted (beta, volatility, leverage, liquidity) | 15% | — | — | x1.4 penalty |
Market Regime Detection
The scanner analyzes the full universe to determine:
- Volatility Level — HIGH / MEDIUM / LOW (3-month average annualized std dev)
- Momentum Regime — BULLISH / NEUTRAL / BEARISH (13-week return distribution)
- Market Breadth — BROAD RALLY / MIXED / BROAD DECLINE (5-day positive percentage)
Data Sources (all free-tier Finnhub)
| Endpoint | Data |
|---|
quote | Current price, daily change, high/low |
stock/metric | 5D/13W/26W/52W/YTD returns, P/E, ROE, margins, beta, volatility, growth rates, relative to S&P 500 |
stock/profile2 | Company name, sector, market cap |
stock/recommendation | Analyst buy/hold/sell consensus |
Default Universe (~100 stocks)
Mega Tech: AAPL, MSFT, GOOGL, AMZN, NVDA, META, TSLA
Semiconductors: AVGO, AMD, INTC, QCOM, MU, MRVL, AMAT, LRCX, KLAC, ON, ARM
Software/Cloud: CRM, ORCL, ADBE, NOW, SNOW, PLTR, PANW, CRWD, DDOG, NET, ZS, SHOP
Financials: JPM, V, MA, BAC, GS, MS, BLK, SCHW, AXP, C
Healthcare: UNH, LLY, JNJ, ABBV, PFE, MRK, TMO, ABT, BMY, GILD, AMGN, ISRG, VRTX
Consumer: WMT, COST, HD, MCD, NKE, SBUX, TGT, LOW, PG, KO, PEP
Energy: XOM, CVX, COP, SLB, EOG, OXY
Industrials: CAT, GE, HON, UNP, BA, RTX, LMT, DE
Others: NFLX, DIS, ABNB, UBER, COIN, SOFI, SMCI, MSTR
China ADR: BABA, PDD, JD, BIDU, NIO, LI, XPEV
Output
HTML Report (default)
A styled, responsive HTML file with:
- KPI dashboard (top pick, market regime, key metrics)
- Market regime detection panel
- Model portfolio (top 5 with factor decomposition)
- Full selection ranking (top 30)
- Anomaly ranking (top 20)
- Sector distribution
- Regime-adaptive weight explanation table
JSON Report
Machine-readable output with all scored stocks, regime detection, and portfolio.
Limitations
- Finnhub free tier: 60 API calls/minute — scanning 100 stocks takes ~2 minutes
- No intraday candle data on free tier — uses metric endpoint for returns
- Returns are point-in-time snapshots, not a real backtest
- Not investment advice — research and monitoring only
Examples
User: scan the market and find me the best momentum plays
→ /quant_scan
User: what's the market regime right now?
→ /quant_regime
User: analyze NVDA AVGO AMD in detail
→ /quant_analyze NVDA AVGO AMD
User: give me a quick top 10 stock ranking
→ /quant_top
Use with Lynn (Zero Config)
Part of Lynn — a personal AI agent with memory and soul. Lynn has this built-in by default.
With Lynn desktop agent, quant-scanner works seamlessly:
- Natural language — just say "scan US stocks" or "what should I buy", Lynn auto-triggers the skill
- Memory integration — Lynn remembers your preferred tickers, past scan results, and investment style
- Multi-model routing — Lynn uses the best model for analysis (reasoning model for factor interpretation, fast model for data fetching)
- Scheduled scans — set up daily pre-market scans that run automatically
- Combined with A-share scanner — Lynn also has a Tushare-powered A-share quantitative scanner for Chinese stocks
git clone https://github.com/MerkyorLynn/Lynn.git
cd Lynn && npm install
