Stock Analysis (v5.1)
Analyze US stocks and cryptocurrencies using Yahoo Finance data. Includes portfolio management, crypto support, periodic analysis, and earnings surprise alerts with WhatsApp push.
Quick Start
IMPORTANT: Pass ONLY the stock ticker symbol(s) as arguments. Do NOT add extra text, headers, or formatting in the command.
Analyze a single ticker:
uv run {baseDir}/scripts/analyze_stock.py AAPL
uv run {baseDir}/scripts/analyze_stock.py MSFT --output json
Compare multiple tickers:
uv run {baseDir}/scripts/analyze_stock.py AAPL MSFT GOOGL
Cryptocurrency Analysis (v5.0)
Analyze top 20 cryptocurrencies by market cap:
uv run {baseDir}/scripts/analyze_stock.py BTC-USD
uv run {baseDir}/scripts/analyze_stock.py ETH-USD SOL-USD
Supported Cryptos:
BTC-USD, ETH-USD, BNB-USD, SOL-USD, XRP-USD, ADA-USD, DOGE-USD, AVAX-USD, DOT-USD, MATIC-USD, LINK-USD, ATOM-USD, UNI-USD, LTC-USD, BCH-USD, XLM-USD, ALGO-USD, VET-USD, FIL-USD, NEAR-USD
Crypto Analysis Dimensions:
- Market cap (large/mid/small classification)
- Category (Smart Contract L1, DeFi, Payment, etc.)
- BTC correlation (30-day)
- Momentum (RSI, price range)
- Market context (VIX, general market regime)
Portfolio Management (v5.0)
Create and manage portfolios with mixed assets (stocks + crypto):
# Create portfolio
uv run {baseDir}/scripts/portfolio.py create "My Portfolio"
# Add assets
uv run {baseDir}/scripts/portfolio.py add AAPL --quantity 100 --cost 150.00
uv run {baseDir}/scripts/portfolio.py add BTC-USD --quantity 0.5 --cost 40000 --portfolio "My Portfolio"
# View holdings with current P&L
uv run {baseDir}/scripts/portfolio.py show
# Update/remove assets
uv run {baseDir}/scripts/portfolio.py update AAPL --quantity 150
uv run {baseDir}/scripts/portfolio.py remove BTC-USD
# List/delete portfolios
uv run {baseDir}/scripts/portfolio.py list
uv run {baseDir}/scripts/portfolio.py delete "My Portfolio"
Portfolio Storage: ~/.clawdbot/skills/stock-analysis/portfolios.json
Portfolio Analysis (v5.0)
Analyze all assets in a portfolio with optional period returns:
# Analyze portfolio
uv run {baseDir}/scripts/analyze_stock.py --portfolio "My Portfolio"
# With period returns (daily/weekly/monthly/quarterly/yearly)
uv run {baseDir}/scripts/analyze_stock.py --portfolio "My Portfolio" --period weekly
uv run {baseDir}/scripts/analyze_stock.py -p "My Portfolio" --period monthly
Portfolio Summary includes:
- Total cost, current value, P&L
- Period return (if specified)
- Concentration warnings (>30% in single asset)
- Recommendation summary (BUY/HOLD/SELL counts)
Examples:
- ✅ CORRECT:
uv run {baseDir}/scripts/analyze_stock.py BAC - ✅ CORRECT:
uv run {baseDir}/scripts/analyze_stock.py BTC-USD - ❌ WRONG:
uv run {baseDir}/scripts/analyze_stock.py === BANK OF AMERICA (BAC) - Q4 2025 EARNINGS === - ❌ WRONG:
uv run {baseDir}/scripts/analyze_stock.py "Bank of America"
Use the ticker symbol only (e.g., BAC, not "Bank of America"). For crypto, use the -USD suffix (e.g., BTC-USD).
Analysis Components
The script evaluates eight key dimensions:
- Earnings Surprise (30% weight): Actual vs expected EPS, revenue beats/misses
- Fundamentals (20% weight): P/E ratio, profit margins, revenue growth, debt levels
- Analyst Sentiment (20% weight): Consensus ratings, price target vs current price
- Historical Patterns (10% weight): Past earnings reactions, volatility
- Market Context (10% weight): VIX, SPY/QQQ trends, market regime
- Sector Performance (15% weight): Stock vs sector comparison, sector trends
- Momentum (15% weight): RSI, 52-week range, volume, relative strength
- Sentiment Analysis (10% weight): Fear/Greed Index, short interest, VIX term structure, insider trading, put/call ratio
Sentiment Sub-Indicators:
- Fear & Greed Index (CNN): Contrarian signal (extreme fear = buy opportunity, extreme greed = caution)
- Short Interest: High shorts + squeeze potential = bullish; justified shorts = bearish
- VIX Term Structure: Contango = complacency/bullish; backwardation = stress/bearish
- Insider Activity: Net buying/selling from SEC Form 4 filings (90-day window)
- Put/Call Ratio: High ratio = excessive fear/bullish; low ratio = complacency/bearish
Weights auto-normalize if some components unavailable.
Special Timing Checks:
- Pre-earnings warning (< 14 days): Recommends HOLD instead of BUY
- Post-earnings spike detection (> 15% in 5 days): Flags "gains priced in"
- Overbought conditions (RSI > 70 + near 52w high): Reduces confidence
Timing Warnings & Risk Flags
The script detects high-risk scenarios:
Earnings Timing
- Pre-Earnings Period: If earnings < 14 days away, BUY signals become HOLD
- Post-Earnings Spike: If stock up > 15% in 5 days after earnings, warns "gains may be priced in"
Technical Risk
- Overbought Conditions: RSI > 70 + near 52-week high = high-risk entry
Market Risk
- High VIX: Market fear (VIX > 30) reduces confidence in BUY signals
- Risk-Off Mode (v4.0.0): When safe-havens (GLD, TLT, UUP) rise together, reduces BUY confidence by 30%
- Detects flight to safety across gold, treasuries, and USD
- Triggers when GLD ≥ +2%, TLT ≥ +1%, UUP ≥ +1% (5-day change)
Sector Risk
- Sector Weakness: Stock may look good but sector is rotating out
Geopolitical Risk (v4.0.0)
The script now scans breaking news (last 24h) for crisis keywords and automatically flags affected stocks:
- Taiwan Conflict: Semiconductors (NVDA, AMD, TSM, INTC, etc.) → 30% confidence penalty
- China Tensions: Tech/Consumer (AAPL, QCOM, NKE, SBUX, etc.) → 30% confidence penalty
- Russia-Ukraine: Energy/Materials (XOM, CVX, MOS, CF, etc.) → 30% confidence penalty
- Middle East: Oil/Defense (XOM, LMT, RTX, etc.) → 30% confidence penalty
- Banking Crisis: Financials (JPM, BAC, WFC, C, etc.) → 30% confidence penalty
If a ticker is not in the affected list but its sector is exposed, applies a 15% confidence penalty.
Example Alert:
⚠️ SECTOR RISK: Tech supply chain and consumer market exposure (detected: china, tariff)
Breaking News Alerts (v4.0.0)
- Scans Google News RSS for crisis keywords (war, recession, sanctions, disasters, etc.)
- Displays up to 2 breaking news alerts in caveats (last 24 hours)
- Uses 1-hour cache to avoid excessive API calls
Output Format
Default (text): Concise buy/hold/sell signal with 3-5 bullet points and caveats
JSON: Structured data with scores, metrics, and raw data for further analysis
Limitations
- Data freshness: Yahoo Finance may lag 15-20 minutes
- Sentiment data staleness:
- Short interest data lags ~2 weeks (FINRA reporting schedule)
- Insider trades may lag filing by 2-3 days
- VIX term structure only updates during futures trading hours
- Breaking news limitations (v4.0.0):
- Google News RSS may lag by 15-60 minutes
- Keyword matching may have false positives/negatives
- Does not analyze sentiment, only detects keywords
- 1-hour cache means alerts may be slightly stale
- Missing data: Not all stocks have analyst coverage, options chains, or complete fundamentals
- Execution time: 3-5s per stock with async parallel fetching and caching (shared indicators cached for 1h)
- Disclaimer: All outputs include prominent "not financial advice" warning
- US markets only: Non-US tickers may have incomplete data
- Earnings alert limitations (v5.1):
- EPS surprise data depends on Yahoo Finance earnings history availability
- Analyst rating lookback may return fewer results for small-cap stocks
- WhatsApp delivery requires wacli skill or OpenClaw message channel configured
Earnings Surprise Alert Workflow (v5.1)
Scan tickers for EPS surprises exceeding a threshold (default 10%), fetch recent analyst ratings (last 30 days), and generate a WhatsApp-ready alert message.
# Scan specific tickers
uv run {baseDir}/scripts/earnings_alert.py AAPL MSFT GOOGL
# Use a watchlist file
uv run {baseDir}/scripts/earnings_alert.py --watchlist ~/.clawdbot/skills/stock-analysis/watchlist.txt
# Custom threshold and lookback
uv run {baseDir}/scripts/earnings_alert.py AAPL --threshold 15 --days 60
# JSON output for programmatic use
uv run {baseDir}/scripts/earnings_alert.py AAPL --output json
Workflow Steps:
- Fetch most recent quarterly EPS (actual vs estimate) for each ticker
- Filter: only tickers with EPS surprise > threshold (default 10%)
- For qualifying tickers, fetch analyst ratings from last 30 days
- Generate formatted WhatsApp message (text) or JSON payload
WhatsApp Push Integration:
After generating alerts, use the wacli skill or OpenClaw's message tool to push the text output to WhatsApp:
# Generate alert and send via OpenClaw message tool
ALERT=$(uv run {baseDir}/scripts/earnings_alert.py AAPL MSFT 2>/dev/null)
# Then use message tool: action=send, channel=whatsapp, message=$ALERT
Watchlist Format (one ticker per line, # comments supported):
# My earnings watchlist
AAPL
MSFT
GOOGL
NVDA
Default watchlist path: ~/.clawdbot/skills/stock-analysis/watchlist.txt
Error Handling
The script gracefully handles:
- Invalid tickers → Clear error message
- Missing analyst data → Signal based on available metrics only
- API failures → Retry with exponential backoff, fail after 3 attempts