# Stock Monitoring API Research
*Compiled 2026-01-29 8pm ET*

## Goal
Automated alerts for:
- Price movements >5% daily
- News headlines for specific tickers (NABL, MSFT, S, etc.)

## API Comparison

| API | Free Tier | Rate Limit | Real-time | News | Best For |
|-----|-----------|------------|-----------|------|----------|
| **Finnhub** | ✅ Yes | 60/min | ✅ | ✅ | Best free option |
| **Alpha Vantage** | ✅ Yes | 25/day | ❌ (15min delay) | ✅ | Technical indicators |
| **Polygon.io** | ✅ Yes | 5/min | ❌ (EOD) | ✅ | Historical data |
| **yfinance** | ✅ Free | ~2000/hr | ✅ | ❌ | Quick polling |
| **TradingView** | ❌ Paid ($15/mo) | N/A | ✅ | ❌ | Visual alerts |

## Recommendation: Finnhub + yfinance combo

### Finnhub (news + fundamentals)
- Free API key: https://finnhub.io/register
- 60 calls/minute = plenty for monitoring
- Has company news endpoint
- Has price target / analyst ratings

```python
import finnhub
client = finnhub.Client(api_key="YOUR_KEY")

# Get quote
quote = client.quote('NABL')  # c=current, pc=previous close, dp=% change

# Get news
news = client.company_news('NABL', _from="2026-01-01", to="2026-01-30")
```

### yfinance (quick price checks, no API key)
```python
import yfinance as yf

# Single quote
stock = yf.Ticker("NABL")
info = stock.info
price = info.get('currentPrice')
prev_close = info.get('previousClose')
pct_change = ((price - prev_close) / prev_close) * 100

# Multiple stocks at once
data = yf.download(['NABL', 'MSFT', 'S'], period='1d')
```

## Implementation Plan

### Simple cron-based monitor
1. Run every 30 min during market hours (9:30am-4pm ET)
2. Poll prices for watchlist
3. Calculate daily % change
4. If >5% move OR significant news → ping Signal

### Watchlist
- **NABL** - Johan's ex-employer, PE takeover watch
- **S** - Johan's short position
- **MSFT, NVDA, TSLA** - Big tech moves
- **GLD, SLV** - Metals
- **BTC** - Crypto

## No Built-in Webhooks
None of the free tiers offer "push when price hits X" functionality.
Must poll and compare ourselves.

## Next Steps
1. Get free Finnhub API key
2. Create `/home/johan/clawd/scripts/stock-monitor.py`
3. Add cron job for market hours
4. Integrate with James dashboard news feed

---
*Research by James, ready for Johan's review*