📄 market-briefing-system.md 2,991 bytes Apr 27, 2026 📋 Raw

📊 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

# 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)
← Back