Your entire pre-market routine — automated, scored, and delivered to your phone.
Tired of checking a dozen different websites before the market opens?
Market Digest does it for you. It grabs live prices, analyzes every instrument, gives each one a score from 0 to 100, and sends you a clean summary on Telegram.
It also reads options flow — sweep orders, dark pool activity, institutional trades — and turns it into a plain-English conviction signal.
Then it tracks whether those picks actually worked — so your results improve over time.
| 📱 | A market summary on your phone every morning Before you even open your laptop, a scored brief — morning, afternoon, weekly, or day trade — is already waiting in Telegram. |
| 🎯 | Clear entry, target, and stop levels Every instrument gets a grade from A+ to F, plus exact price levels: where to buy, where to take profit, and where to cut your loss. |
| 📊 | See which picks actually worked The Retrace system saves every pick you get, then checks the next day — did it hit the target? Did it hit the stop? You'll see your actual win rate. |
| 📈 | Options flow intelligence See where the big money is moving. Market Digest reads sweep orders, dark pool prints, and institutional block trades, then boils it all down to one conviction signal — bullish, bearish, or neutral — with a plain-English explanation. |
| 🧠 | Optional AI analysis Connect Claude, ChatGPT, or Gemini and get AI-written commentary alongside your data. Or skip it entirely — the core system needs zero AI to work. |
| 🖥️ | A full control panel in your browser The Command Center lets you tweak settings, preview digests, see scorecards, and track performance — all from a clean web interface. |
| 🔒 | Runs on your computer. Nobody else's. No cloud service. No monthly fee. No company storing your data. Everything stays on your machine. |
New to trading terms? Don't worry — this README explains everything in plain English. If you see something you don't understand, open a discussion and we'll help.
📸 Command Center Dashboard — click to expand
The home page shows you which data sources are connected (green = good), quick buttons to run digests, and a snapshot of your setup.
📊 Multi-Timeframe ScoreCard — click to expand
Every instrument gets three grades: one for day trading (daily analysis), one for swing trading (weekly), and one for long-term (monthly). Click any instrument to see exactly why it scored the way it did — RSI, trend direction, how close it is to key price levels, and more.
📱 What the Telegram Message Looks Like — click to expand
A clean, formatted message on your phone with your top picks, scores, entry/target/stop levels, and market context. Ready to read in under a minute.
📈 Options Flow — Conviction Signals — click to expand
Pick any stock and instantly see where the smart money is moving — sweep orders, dark pool activity, institutional blocks, and a conviction meter that reads "Strong Bull" or "Strong Bear" with a plain-English breakdown of why.
🔄 Retrace — Performance Tracking — click to expand
After a few days of running, you'll see your actual hit rate: how often picks reached their target, how often they hit the stop, and how the scoring is performing. Use this to fine-tune your settings.
Just two things:
- A computer — Mac, Windows, or Linux all work
- Python — this is a free programming tool that runs Market Digest behind the scenes. You don't need to learn it — you just need it installed.
How to check if you already have Python:
- On Mac: open the Terminal app (press
Cmd + Space, typeTerminal, hit Enter), then typepython3 --versionand press Enter. If you see a number likePython 3.12.0, you're good. - On Windows: open PowerShell (click the Start menu, type
PowerShell, hit Enter), then typepython --versionand press Enter. If you see a number, you're good.
Don't have Python? Download it free from python.org/downloads — click the big yellow button, run the installer, and accept the defaults. Windows users: make sure to check the box that says "Add Python to PATH" during installation.
That's all you need. No other software required.
Easiest way — download as a ZIP file (no extra software needed):
- Click this link: Download Market Digest ZIP
- Your browser will download a
.zipfile - Find the downloaded file and unzip it (double-click it on Mac, or right-click → "Extract All" on Windows)
- You'll get a folder called
market-digest-main— move it somewhere easy to find, like your Desktop
Now you need to open a Terminal (Mac/Linux) or PowerShell (Windows). This is just a text-based way to talk to your computer — you'll copy and paste a few commands.
How to open it:
- Mac: Press
Cmd + Spaceto open Spotlight, typeTerminal, press Enter - Windows: Click the Start menu, type
PowerShell, press Enter - Linux: Press
Ctrl + Alt + T
Once it's open, type these commands one at a time, pressing Enter after each one:
First, navigate to the folder you just unzipped:
On Mac/Linux (if you put it on your Desktop):
cd ~/Desktop/market-digest-mainOn Windows (if you put it on your Desktop):
cd ~\Desktop\market-digest-mainWhat this does: tells your computer to look inside the Market Digest folder.
Next, run the setup:
On Mac/Linux:
chmod +x setup.sh
./setup.shOn Windows:
.\setup.batWhat this does: installs everything Market Digest needs. It will ask you about some optional account passwords (called "API keys") — you can skip all of them for now by pressing Enter. You can always add them later.
What you should see: text scrolling by as it installs. This takes 1-2 minutes. When it's done, you'll see a success message.
On Mac:
./start.commandYou can also just double-click the
start.commandfile in the folder — it does the same thing.
On Windows:
.venv\Scripts\python scripts\start_ui.pyOn Linux:
.venv/bin/python scripts/start_ui.pyWhat happens: a page will open in your browser automatically — that's the Command Center, your control panel for everything. If it doesn't open automatically, go to localhost:8550 in your browser.
That's it — you're running! 🎉
No accounts or extra setup needed. In the same Terminal/PowerShell window, run:
On Mac/Linux:
.venv/bin/python scripts/run_digest.py --type daytrade --mode facts --dry-runOn Windows:
.venv\Scripts\python scripts\run_digest.py --type daytrade --mode facts --dry-runWhat this does: pulls free stock data and shows you a scored day trade digest right in your Terminal. It's a preview — to get digests on your phone, set up Telegram below (free, takes 2 minutes).
| Problem | Fix |
|---|---|
"permission denied" when running setup.sh |
Run chmod +x setup.sh first, then try again |
| "python3 not found" or "python not found" | Python isn't installed yet — download it here |
| Windows: "running scripts is disabled" | Run Set-ExecutionPolicy -Scope CurrentUser RemoteSigned in PowerShell, then try again |
| The browser page didn't open | Open your browser and go to localhost:8550 |
| Something else went wrong | Open an issue — tell us what happened and what system you're on, and we'll help |
🛠️ For techies: Git clone, Docker, and manual setup
Git clone (instead of ZIP download):
git clone https://github.com/mutaaf/market-digest.git
cd market-digest
./setup.shDocker:
git clone https://github.com/mutaaf/market-digest.git
cd market-digest
cp .env.example .env # Optional: edit .env with your API keys
docker compose up --buildOpen localhost:8550 in your browser. Done.
Full manual setup:
git clone https://github.com/mutaaf/market-digest.git
cd market-digest
# Create an isolated Python environment
python3 -m venv .venv
source .venv/bin/activate # On Windows: .venv\Scripts\activate
# Install Python packages
pip install -r requirements.txt
# Create your config file
cp .env.example .env
# Build the web interface (needs Node.js — https://nodejs.org)
cd ui/frontend && npm install && npm run build && cd ../..
# Start everything
python scripts/start_ui.pyMakefile shortcuts (requires make, which is pre-installed on Mac/Linux):
make setup # Full setup (venv + deps + frontend build)
make ui # Start the web UI
make dev # Start with hot-reload (development)
make digest-dry # Quick dry-run daytrade digest
make test # Run tests
make lint # Run linter
make clean # Remove build artifacts and cache
make help # Show all available targetsThink of Market Digest as a robot assistant that does your pre-market homework:
You sleep Market Digest works You wake up
┌──────────┐ ┌──────────────────────┐ ┌────────────┐
│ 😴 zzz │ │ 1. Grab live prices │ │ 📱 Phone │
│ │ │ 2. Run analysis │ ───▶ │ buzzes │
│ │ │ 3. Score everything │ │ "Here are │
│ │ │ 4. Pick the best │ │ today's │
│ │ │ 5. Send to Telegram │ │ top picks"│
└──────────┘ └──────────────────────┘ └────────────┘
Here's what happens under the hood:
-
Grabs data from 8+ free sources — live prices (yfinance), intraday data (TwelveData), earnings info (Finnhub), economic indicators like interest rates and GDP (FRED), financial news (NewsAPI), market fear/greed levels, options chain data (Alpha Vantage), and institutional flow data (Unusual Whales).
-
Analyzes everything across 3 timeframes:
- Daily — for day trades (buying and selling the same day)
- Weekly — for swing trades (holding for days to weeks)
- Monthly — for long-term positions (holding for weeks to months)
-
Scores each instrument from 0 to 100 using:
- RSI (Relative Strength Index) — measures if something is overbought (too expensive, might drop) or oversold (cheap, might bounce)
- Trend direction — is the price going up, down, or sideways?
- Pivot proximity — how close is the price to key support/resistance levels (floors and ceilings)?
- Volatility — how wild are the price swings?
- Volume — are more people trading it than usual?
- Gap analysis — did the price jump overnight?
-
For stocks, it also checks the business fundamentals:
- Is the company fairly valued? (valuation)
- Is it making good money? (profitability)
- Is it growing? (growth)
- Is it financially healthy? (debt, cash flow)
-
Reads the options flow (for stocks) — scans sweep orders, dark pool prints, and institutional block trades. Combines 7 conviction factors (call/put ratio, sweep ratio, dark pool signal, institutional alignment, IV skew, flow momentum, open interest changes) into a single directional signal: bullish, bearish, or neutral.
-
Sends you a formatted summary on Telegram with the top picks, their scores, and exact entry/target/stop price levels.
-
Tracks accuracy — the Retrace system records every pick and checks the next day: did the price hit the target? Over time, you'll see which types of picks work best and can adjust the scoring weights.
84 instruments come pre-loaded across 7 categories. You can add, remove, or toggle any of them:
| Category | What's Included | Count |
|---|---|---|
| US Stocks | Apple, NVIDIA, Tesla, Meta, Amazon, JPMorgan, Eli Lilly, Palantir, and 40 more | 48 |
| US Indices | S&P 500, NASDAQ, Dow Jones, VIX (the "fear index") | 6 |
| Forex | EUR/USD, GBP/USD, USD/JPY (currency pairs) | 8 |
| Commodities | Gold, Silver, Oil, Natural Gas, Coffee, Copper, Wheat, and more | 14 |
| Crypto | Bitcoin, Ethereum, Solana, XRP, Cardano | 5 |
| Futures | S&P 500 Futures, NASDAQ Futures, Dow Futures | 3 |
| Economic Data | Fed interest rate, CPI (inflation), GDP, unemployment | 8 |
Want to add something? Open the Command Center → Instruments page, and add any ticker. Or edit
config/instruments.yamldirectly.
Market Digest works right away with zero API keys and zero signups. The core data source (yfinance) is completely free and built in.
Everything else is optional — add keys later to unlock more data. (API keys are like free account passwords that let Market Digest connect to extra data services.)
| Service | Do I Need It? | Cost | What It Adds | Sign Up |
|---|---|---|---|---|
| yfinance | Already included | Free | Stock prices, fundamentals, options chains — this is the engine | No signup needed |
| Telegram | Only if you want phone delivery | Free | Get digests sent to your phone | See setup guide below |
| TwelveData | No | Free (800 calls/day) | Better real-time and intraday prices | Sign up |
| Finnhub | No | Free (60 calls/min) | Earnings dates, economic events | Sign up |
| FRED | No | Free (unlimited) | Fed rate, GDP, inflation, unemployment | Get key |
| NewsAPI | No | Free (100 calls/day) | Financial news headlines | Sign up |
| Alpha Vantage | No | Free (25 calls/day) | Historical options data, IV surface | Sign up |
| Unusual Whales | No | Paid | Institutional flow, dark pool, sweep alerts | Sign up |
| Claude / ChatGPT / Gemini | No | Varies (has free tiers) | AI-written commentary on digests | Anthropic / OpenAI / Google |
How to add keys: Open the Command Center (Settings page) to enter them through the web interface. Or edit the
.envfile in the project folder. Or re-run./setup.shand enter them when prompted.Our recommendation: Start with zero keys. Run a sample digest to see how it works. Then add Telegram when you're ready for phone delivery. Add the rest whenever you feel like it.
Telegram is free and takes about 2 minutes to set up. Once connected, Market Digest will send formatted digests directly to your phone — no app to open, no website to check.
- Open Telegram on your phone or computer (download it from telegram.org if you don't have it — it's free)
- Search for
@BotFatherin Telegram and open a chat with it (BotFather is Telegram's official tool for creating bots) - Send the message:
/newbot - BotFather will ask you two things:
- A name for your bot (this is a display name, e.g.,
My Market Digest) - A username for your bot (must end in
bot, e.g.,my_market_digest_bot)
- A name for your bot (this is a display name, e.g.,
- BotFather will reply with a token — a long string that looks like
123456789:ABCdefGHIjklMNOpqrsTUVwxyz. Copy this token. You'll need it in Step 3.
Your Chat ID tells Market Digest where to send messages (your personal chat).
- Open a chat with your new bot in Telegram — search for the username you just created
- Send it any message (just say "hello" — the bot won't reply yet, that's normal)
- Open this URL in your browser (replace
YOUR_TOKENwith the token from Step 1):https://api.telegram.org/botYOUR_TOKEN/getUpdates - Look for
"chat":{"id":in the response — the number after it is your Chat ID (e.g.,987654321)
Can't find your Chat ID? An easier method: search for
@userinfoboton Telegram, start a chat, and it'll tell you your ID.
Open the Command Center (Settings page) and enter your Bot Token and Chat ID there. Or, if you prefer, edit the .env file in the project folder:
TELEGRAM_BOT_TOKEN=123456789:ABCdefGHIjklMNOpqrsTUVwxyz
TELEGRAM_CHAT_ID=987654321In your Terminal/PowerShell, run:
On Mac/Linux:
.venv/bin/python scripts/test_telegram.pyOn Windows:
.venv\Scripts\python scripts\test_telegram.pyIf it works, you'll get a test message on Telegram. If not, double-check that you messaged the bot first (Step 2) and that the token and chat ID are correct.
That's it — you're connected. Now any digest you run will be delivered to your phone.
Want to send to multiple people? Add more chat IDs separated by commas:
TELEGRAM_CHAT_ID=987654321,111222333,444555666Each person needs to have opened a chat with your bot first.
Market Digest comes with 8 built-in data sources, but you can add your own — any HTTP API, RSS feed, or CSV file — through the Command Center or the API. No code required.
- Open the Command Center (double-click
start.commandon Mac, or runstart_ui.py— see How to Install) - Go to the Data Sources page
- Click Add Custom Source
- Fill in the details:
- Name — whatever you want to call it (e.g., "Alpha Vantage", "My RSS Feed")
- Type —
HTTP API,RSS Feed, orCSV File - URL — the endpoint or feed URL
- Authentication — API key, Bearer token, or custom header (if needed)
- Click Test to verify it connects
- Enable it — the data will now appear in your digests
HTTP API — connect to any JSON API
Point it at any REST API that returns JSON. Market Digest handles:
- URL templates — use
{symbol}and{api_key}placeholders (e.g.,https://api.example.com/quote/{symbol}?key={api_key}) - Authentication — API key in URL, Bearer token, or custom header
- Response mapping — tell it which fields in the API response map to
price,open,high,low, etc. - Per-symbol fetching — specify a list of symbols and it'll call the API for each one
RSS Feed — pull in any news feed
Point it at any RSS or Atom feed URL (e.g., a financial news RSS feed, a subreddit feed, a blog). Market Digest will:
- Parse the feed automatically
- Pull title, summary, and link from each item
- Include the latest items in your digest
CSV File — use your own local data
Point it at a CSV file on your computer. Useful for:
- Proprietary data you export from another tool
- Watchlists from your broker
- Custom research data
Market Digest reads the CSV, maps columns to fields, and auto-converts numbers.
Example: Adding an HTTP API Source via the API
Here's what it looks like to add Alpha Vantage as a custom source programmatically:
curl -X POST http://localhost:8550/api/sources/custom \
-H "Content-Type: application/json" \
-d '{
"name": "Alpha Vantage",
"type": "http",
"url": "https://www.alphavantage.co/query?function=GLOBAL_QUOTE&symbol={symbol}&apikey={api_key}",
"auth": {
"env_var": "ALPHA_VANTAGE_KEY"
},
"instruments": ["AAPL", "MSFT"],
"response_root": "Global Quote",
"response_mapping": {
"price": "05. price",
"open": "02. open",
"high": "03. high",
"low": "04. low",
"volume": "06. volume"
}
}'Bottom line: If it's on the internet and returns data, you can probably plug it in. No need to write code or modify source files — the Command Center handles everything.
Start it by double-clicking start.command (Mac) or running the start command from How to Install. A page will open in your browser — that's the Command Center.
| Page | What You'll Do There |
|---|---|
| Dashboard | See which data sources are connected, quick-launch digests |
| Digest | Preview any digest (morning, afternoon, weekly, day trade) and send it |
| Instruments | Turn instruments on/off, add new tickers, organize by category |
| Data Sources | Manage built-in sources, add custom APIs/RSS/CSV feeds, test connections |
| ScoreCard | See every instrument's grade (A+ to F) across all three timeframes |
| Options Flow | View options activity for any stock — sweep orders, dark pool prints, institutional trades, and a conviction signal that tells you where the big money is leaning |
| Weights | Adjust how much each factor matters in the scoring (e.g., "care more about trends, less about volume") |
| Prompts | Customize the AI prompts if you're using Claude/GPT/Gemini |
| Retrace | See your pick accuracy — which calls hit, which missed |
| Settings | Change your timezone, delivery preferences, enter API keys, and more |
| Cache | See what data is cached and clear it if needed |
| Logs | Browse past digests and system logs |
Access from your phone or tablet: If your computer and phone are on the same Wi-Fi, you can open the Command Center on your phone's browser too. On your computer, find your IP address (Mac: open Terminal and run
ipconfig getifaddr en0/ Windows: open PowerShell and runipconfig), then on your phone go tohttp://YOUR_IP:8550.
The real power is automation. Set up a schedule and digests arrive on your phone without you lifting a finger.
Mac
In Terminal, navigate to your Market Digest folder and run:
.venv/bin/python scripts/setup_launchd.pyThis sets up automatic runs:
| Digest | When |
|---|---|
| Morning brief | 6:30 AM CT |
| Day trade picks | 8:15 AM CT |
| Afternoon recap | 4:30 PM CT |
| Weekly summary | Friday 5:30 PM CT |
Your computer needs to be awake at those times for the digests to run.
Windows / Any system
You can run any digest from PowerShell or Terminal:
.venv/bin/python scripts/run_digest.py --type daytrade --mode factsDigest types: morning, afternoon, weekly, daytrade
Modes: facts (data only), full (data + AI commentary), both (sends both separately)
Use Windows Task Scheduler (or cron on Mac/Linux) to run these commands automatically at whatever times you choose.
Do I need to know how to code?
Nope. If you can copy-paste a few commands, you can run Market Digest. The setup script handles everything. The Command Center (web interface) handles all configuration — no code editing required.
Is this free?
Yes, completely. Market Digest is open source under the MIT license. No premium tier, no trial period, no catch. The data sources it uses have generous free tiers. You can run it forever without paying anything.
Is this financial advice?
No. Market Digest is a data analysis tool. It scores instruments based on technical and fundamental indicators, but it doesn't tell you what to buy or sell. Always do your own research and never trade money you can't afford to lose.
What's "self-hosted" mean?
It means the software runs on your own computer, not on someone else's server. Your data stays with you. There's no company collecting your information or charging you monthly. The downside: you have to run the setup yourself (but it's a one-time thing).
Can I run this on a Raspberry Pi / VPS / server?
Yes — anywhere that runs Python 3.10+ and has internet access. A Raspberry Pi 4, a $5/month VPS, an old laptop — all work great. Docker makes it especially easy on servers.
What if something breaks?
Open an issue with what happened and we'll help. Include your operating system and Python version.
Can I add my own stocks/instruments?
Yes, two ways: through the Command Center (Instruments page → Add), or by editing config/instruments.yaml. Any ticker that works on Yahoo Finance works here.
My Telegram bot isn't sending messages
The most common fixes:
- Did you message the bot first? Open Telegram, find your bot by its username, and send it any message (even just "hi"). The bot can't message you until you've started a conversation with it.
- Is your token correct? Copy it again from BotFather — make sure there are no extra spaces.
- Is your Chat ID correct? Try the
@userinfobotmethod: search for@userinfoboton Telegram, send it a message, and it'll reply with your ID. - Run the test: In Terminal/PowerShell, run
.venv/bin/python scripts/test_telegram.py(on Windows:.venv\Scripts\python scripts\test_telegram.py) — it'll tell you exactly what's wrong.
Can I use Discord / Email / Slack instead of Telegram?
Not yet built in, but Telegram is free and takes 2 minutes to set up. Discord and email delivery are on the roadmap. If you're a developer, the delivery system in src/delivery/ is modular — adding a new delivery method is a great first contribution.
Can I plug in my own data source?
Yes — any HTTP API, RSS feed, or CSV file. No code needed. Use the Command Center's Data Sources page or the REST API. See the Bring Your Own Data Sources section for details and examples.
Configuration
All config is in YAML files under config/. Edit by hand or through the web UI — changes apply instantly, no restart needed.
| File | Controls |
|---|---|
config/instruments.yaml |
Which instruments to track (tickers, names, categories) |
config/scoring.yaml |
Scoring weights for day trade, swing, and long-term timeframes |
config/prompts.yaml |
LLM prompt templates and AI provider settings |
config/digests.yaml |
Digest sections, modes, and delivery schedules |
config/options.yaml |
Options flow providers, cache TTLs, and conviction weights |
Architecture
┌─────────────────────────────────────────────────────────────┐
│ Web UI (React + Vite) │
│ localhost:8550 — Command Center │
├─────────────────────────────────────────────────────────────┤
│ FastAPI Server (70 endpoints) │
├──────────┬──────────┬───────────┬───────────┬───────────────┤
│ Fetchers │ Analysis │ Digest │ Retrace │ Config │
│ yfinance │ RSI/MACD │ Morning │ Snapshot │ instruments │
│ 12Data │ Pivots │ Afternoon │ Grading │ prompts │
│ Finnhub │ Trend │ Weekly │ Scoring │ digests │
│ FRED │ Scoring │ Daytrade │ Tracking │ scoring wts │
│ NewsAPI │ LLM │ Options │ │ options │
│ F&G │ Fundmtls │ Formatter │ │ │
│ AlphaV │ Options │ │ │ │
│ UW Flow │ Flow │ │ │ │
├──────────┴──────────┴───────────┴───────────┴───────────────┤
│ Cache (memory + JSON) │ Telegram Delivery │
└─────────────────────────────────┴───────────────────────────┘
Tech stack: Python 3.12 + FastAPI (70 endpoints), React 18 + TypeScript + Vite + Tailwind (web UI), yfinance + TwelveData + Finnhub + FRED + NewsAPI + Alpha Vantage + Unusual Whales (data), dual-tier cache (memory + JSON files), Telegram for delivery. No database — all persistence is YAML configs and JSON files.
Project Structure
market-digest/
├── config/ # YAML configs (instruments, prompts, scoring weights, options)
├── src/
│ ├── analysis/ # Technical analysis, scoring, LLM, fundamentals, options flow
│ ├── cache/ # Dual-tier cache (memory + JSON files)
│ ├── delivery/ # Telegram delivery
│ ├── digest/ # Digest builders (morning, afternoon, weekly, daytrade, options)
│ ├── fetchers/ # Data fetchers (yfinance, TwelveData, Finnhub, Alpha Vantage, UW, etc.)
│ ├── retrace/ # Pick snapshot & grading system
│ └── utils/ # Logging, rate limiting, timezone helpers
├── ui/
│ ├── server.py # FastAPI app (13 route groups)
│ ├── routes/ # API route handlers
│ └── frontend/ # React + TypeScript + Tailwind (11 pages)
├── scripts/ # CLI tools (run_digest, start_ui, setup_launchd, etc.)
├── tests/ # Test suite
├── logs/ # Runtime logs, retrace snapshots & options flow history
└── cache/ # File-backed JSON cache
Want to help make Market Digest better? See CONTRIBUTING.md for development setup, code style, and how to add new features.
MIT — use it however you want, for free, forever.