# 📊 Market Sentiment Briefing — System Documentation

## Overview

Daily market sentiment briefing delivered to Matt's DM. Fetches analyst recommendations, insider sentiment, earnings surprises, and price data from Finnhub (free tier).

## Commands

| Command | Description |
|---------|-------------|
| `/briefing` | Generate and send market briefing on-demand |
| `/watchlist` | Show current watchlist |
| `watchlist TICKER TICKER ...` | Update watchlist |

## Architecture

```
┌─────────────────┐     ┌──────────────┐     ┌──────────────┐
│   Cron Job      │────▶│  Finnhub API │────▶│  Telegram DM │
│  (daily 3PM CT) │     │  (60 calls/m)│     │   (Matt)     │
└─────────────────┘     └──────────────┘     └──────────────┘
         │
         ▼
┌─────────────────┐
│  watchlist.json │  ← Configurable ticker list
└─────────────────┘
```

## Files

| File | Purpose |
|------|---------|
| `core/market/sentiment.py` | Finnhub API client + briefing generator |
| `core/handlers/market_briefing.py` | Telegram command handlers |
| `jobs/daily_briefing.py` | Cron job entrypoint |

## API Endpoints (Free Tier)

- `/quote` — Real-time price and change
- `/stock/insider-sentiment` — Monthly insider buying/selling sentiment
- `/stock/recommendation` — Analyst buy/sell/hold consensus
- `/stock/earnings` — Earnings surprise history
- `/company-news` — Recent headlines (not yet used)

## Signal Logic

| Signal | Condition |
|--------|-----------|
| 🟢 Bullish | >60% analyst buy OR insider MSPR >0.2 |
| 🔴 Bearish | >40% analyst sell OR insider MSPR <-0.2 |
| ⚪ Neutral | Neither condition met |

## Alerts

- 💰 Earnings surprise >10%
- 📊 Analyst consensus change ≥2 buys

## Cron Setup

```bash
# Add to crontab (3:00 PM CT = market close)
0 15 * * 1-5 cd /home/hoffmann_admin/.openclaw/workspace/services/icarus && ICARUS_ENV=staging python3 jobs/daily_briefing.py
```

## Environment Variables

| Variable | Required | Description |
|----------|----------|-------------|
| `FINNHUB_API_KEY` | ✅ | Finnhub API key (free tier) |
| `TELEGRAM_BOT_TOKEN` | ✅ | Bot token for sending DMs |
| `TELEGRAM_CHAT_ID_MATT` | ✅ | Matt's chat ID |

## Watchlist

Default: `AAPL MSFT GOOGL AMZN TSLA NVDA META JPM`

Stored in: `~/.icarus/staging/watchlist.json`

## Rate Limits

- Free tier: 60 calls/minute
- Per-ticker cost: 4 calls (quote, sentiment, recommendations, earnings)
- 8 tickers = 32 calls = well within limit

## Future Enhancements

- [ ] News sentiment (requires paid tier or alternative source)
- [ ] Sector rotation signals
- [ ] Technical indicators (RSI, MACD)
- [ ] Portfolio tracking (if Matt adds holdings)