Scorched — Your AI Trading Assistant

An AI-powered stock trading bot you can actually talk to. Every weekday, Scorched researches the market, generates trade recommendations through a multi-stage Claude pipeline, and manages a portfolio — all on its own. Check in through a live dashboard, or open Claude Desktop and ask your bot what it's thinking in plain English.

Starts as paper trading with simulated money. When you're ready, connect an Alpaca brokerage account to trade for real.

Who this is for: Developers, hobbyist traders, and AI tinkerers who want to experiment with an autonomous trading system they fully control. This is a personal trading framework for learning and experimentation — not financial advice, not a production trading platform, and not a substitute for professional investment management. Past performance of any trading system does not guarantee future results. Use at your own risk.

Safe defaults: Scorched starts in paper-trading mode with simulated money. Before doing anything else: set SETTINGS_PIN in your .env, do not expose port 8000 to the public internet, and use a VPN or IP allowlist if running on a cloud VM. See DEPLOY.md for full security guidance.

New here? Start with START_HERE.md

---

Two Ways to Use It

1. Talk to Your Bot (MCP)

Scorched runs a built-in MCP server — the open protocol that lets AI assistants use external tools. Point Claude Desktop (or any MCP client) at your bot and have a conversation:

You: "What did you buy today and why?" You: "How's the portfolio doing?" You: "What does your playbook say about tech stocks?" You: "Run today's analysis — what looks good?"

Claude calls the bot's tools behind the scenes and answers in plain English. No commands to memorize, no API knowledge needed. This is the easiest way to get started.

Quick setup (Claude Desktop):

{
  "mcpServers": {
    "tradebot": {
      "url": "http://localhost:8000/mcp"
    }
  }
}

That's it. Open Claude Desktop and start asking questions.

2. Set It and Forget It (Dashboard + Cron)

The bot also runs fully autonomously on a daily schedule — no manual intervention required. Cron jobs trigger each phase of the trading day, and a live dashboard at http://host:8000 shows your portfolio, today's picks, and performance history. Auto-refreshes every 5 minutes.

Cron (VM)
    │
    │  9:35 AM ET  — Phase 0: post-open data prefetch (zero LLM cost)
    │  9:45 AM ET  — Phase 1: Claude analysis + recommendations
    │  9:55 AM ET  — Phase 1.5: circuit breaker safety gate
    │  10:15 AM ET — Phase 2: submit approved orders
    │  10:45 AM ET — Phase 2.5: reconcile Alpaca fills + sync positions
    │  Every 5 min — Intraday position monitoring (9:35 AM–3:55 PM ET)
    │  4:01 PM ET  — Phase 3: EOD review + playbook update
    │
    ▼
Scorched (FastAPI + PostgreSQL)
    │
    ├── Phase 0: Fetches market data (Alpaca, yfinance, FRED, Twelvedata, Alpha Vantage, Finnhub, EDGAR)
    ├── Phase 0: Runs momentum screener (top 20 S&P 500 movers)
    ├── Phase 1: Calls Claude (claude-sonnet-4-6) — multi-call pipeline
    │     Call 1: Analysis w/ extended thinking → structured candidates + position actions
    │     Call 2: Decision → 0–3 concrete trade recommendations
    │     Call 3: Risk committee → challenge and reject weak picks
    │     Call 4: Position management → review open positions EOD
    ├── Phase 2.5: Reconciles pending Alpaca fills + syncs positions vs broker
    ├── Tracks portfolio state in PostgreSQL
    └── Dashboard auto-refreshes at http://host:8000

NYSE holidays are detected automatically — if the market is closed, no Claude calls are made.

---

Stack

Layer	Technology
Runtime	Python 3.11, FastAPI
AI	Anthropic Claude (claude-sonnet-4-6, extended thinking on Call 1)
MCP	mcp[cli] (FastMCP, Streamable HTTP) — talk to your bot from Claude Desktop
Database	PostgreSQL 16 via SQLAlchemy 2.0 async + asyncpg
Migrations	Alembic
Market data	Alpaca Data API — prices, bars (IEX), snapshots, news, screener (Polygon removed Apr 2026)
Fundamentals/options	yfinance — PE, market cap, options chains, earnings dates, insider purchases, index symbols
Macro data	FRED API — Fed rate, CPI, yield curve, PCE, credit spreads, economic calendar
Technicals	Twelvedata RSI(14) for full watchlist + Alpha Vantage fallback for screener picks
Analyst consensus	Finnhub (recommendation trends)
Insider filings	SEC EDGAR Form 4 (free, no key)
Holiday detection	pandas-market-calendars (NYSE calendar)
Automation	cron on the VM
Deployment	Docker Compose

---

MCP Server — Talk to Your Bot

The bot runs a Streamable HTTP MCP server at http://host:8000/mcp. Any MCP-compatible client — Claude Desktop, Cursor, your own agents — can connect and interact with the full trading system through natural language.

Why this matters:

• No technical knowledge required. Ask "what did you buy today?" and get a plain-English answer. The AI client calls the right tools automatically.
• The heavy lifting is behind the tools. A single question like "what looks good today?" triggers a multi-stage pipeline that pulls from 7+ data sources, runs technical analysis, and passes picks through a risk committee. You just ask.
• Human-in-the-loop by default. Recommendations come back as pending. Nothing executes without explicit confirmation.
• Works with any MCP client. Claude Desktop, Cursor, Claude Code, or any tool that speaks the MCP protocol.

Connect Claude Desktop — add this to your Claude Desktop MCP config:

{
  "mcpServers": {
    "tradebot": {
      "url": "http://your-server:8000/mcp"
    }
  }
}

Things you can ask:

• "How's my portfolio doing?" — pulls live positions, P&L, and tax status
• "Run today's analysis" — triggers the full research + recommendation pipeline
• "What does the playbook say?" — reads the bot's evolving strategy document
• "Show me the market summary" — end-of-day index and sector performance
• "Confirm trade #42 at $185.50 for 10 shares" — executes a specific recommendation
• "Reject recommendation #43" — skips a pick while keeping the audit trail clean

Available tools (7):

Tool	What it does
get_recommendations	Research stocks + generate up to 3 trade picks via Claude pipeline
get_opening_prices	Fetch actual opening auction prices for any symbols
confirm_trade	Execute a trade — updates portfolio, tracks P&L and taxes
reject_recommendation	Skip a pick (audit trail stays clean)
get_portfolio	Live portfolio snapshot — positions, unrealized P&L, tax classification
get_market_summary	EOD performance for major indices + all S&P 500 sector ETFs
read_playbook	Read the bot's living strategy doc — lessons learned from past trades

---

REST API

Method	Path	Description
GET	/	Dashboard (HTML)
GET	/health	Health check
GET	/api/v1/portfolio	Portfolio snapshot
GET	/api/v1/portfolio/history	Trade history (paginated)
GET	/api/v1/portfolio/tax-summary	YTD realized gains by ST/LT
GET	/api/v1/recommendations	List past sessions
POST	/api/v1/recommendations/generate	Trigger recommendation run
POST	/api/v1/trades/confirm	Confirm a trade
POST	/api/v1/trades/{rec_id}/reject	Reject a recommendation
GET	/api/v1/market/summary	EOD market + sector summary
GET	/api/v1/strategy	Read strategy settings
PUT	/api/v1/strategy	Update strategy settings (PIN-protected if configured)
GET	/api/v1/playbook	Read strategy playbook
POST	/api/v1/intraday/evaluate	Intraday trigger check + Claude exit evaluation
GET	/api/v1/costs	Claude API cost tracker

---

Database Schema

8 tables in PostgreSQL:

Table	Purpose
portfolio	Single-row: cash balance, starting capital, peak value (drawdown tracking), benchmark start prices
positions	One row per held ticker; avg cost basis updated on each buy
recommendation_sessions	One row per trading day; caches raw research + Claude response + analysis thinking
trade_recommendations	Up to 3 rows per session; status: pending → confirmed/rejected
trade_history	Append-only audit log of executed trades
playbook	Single-row living strategy document (updated by Claude before each session)
token_usage	Per-call Claude API token tracking (input, output, thinking tokens)
api_call_log	External API call tracking — service, endpoint, status, response time, errors

Tax model: simplified ST/LT classification based on first_purchase_date (no per-lot tracking). ST rate: 37%, LT rate: 20%.

---

Project Structure

scorched/
├── Dockerfile
├── docker-compose.yml
├── entrypoint.sh           # Runs alembic upgrade then starts uvicorn
├── pyproject.toml
├── strategy.md             # Human-readable strategy reference
├── analyst_guidance.md     # Signal interpretation tables + hard rules for Claude prompts
├── advisor.md              # CPA/financial advisor reference document
├── DEPLOY.md               # Full deployment + cron guide
├── alembic/
│   ├── env.py
│   └── versions/           # Migration files
├── cron/                   # Cron job scripts (phase 0, intraday monitor, etc.)
├── scripts/                # Utility scripts (setup_cron.py, etc.)
└── src/
    └── scorched/
        ├── main.py         # FastAPI app; mounts MCP at /mcp
        ├── config.py       # pydantic-settings Settings
        ├── database.py     # Async SQLAlchemy engine + session
        ├── models.py       # 8 ORM models
        ├── schemas.py      # Pydantic request/response schemas
        ├── mcp_tools.py    # 7 MCP tool definitions (FastMCP)
        ├── tax.py          # classify_gain(), estimate_tax()
        ├── cost.py         # Claude token cost calculator
        ├── tz.py           # market_today(), market_now(), MARKET_TZ
        ├── api_tracker.py  # External API call tracking + health aggregation
        ├── correlation.py  # 20-day return correlation check
        ├── circuit_breaker.py  # Pre-execution gate (gap-down, SPY, VIX)
        ├── drawdown_gate.py    # Portfolio drawdown enforcement
        ├── trailing_stops.py   # ATR-based trailing stop logic
        ├── intraday.py     # Pure intraday trigger check functions
        ├── http_retry.py   # Retry wrapper for external HTTP APIs
        ├── static/
        │   └── dashboard.html
        ├── broker/         # BrokerAdapter ABC, PaperBroker, AlpacaBroker
        ├── api/            # FastAPI routers
        │   ├── costs.py
        │   ├── market.py
        │   ├── playbook.py
        │   ├── portfolio.py
        │   ├── recommendations.py
        │   ├── strategy.py
        │   ├── trades.py
        │   ├── system.py       # /system/health, /system/errors, /system/trend
        │   ├── intraday.py     # Intraday trigger eval + auto-sell
        │   ├── prefetch.py     # Phase 0 data prefetch
        │   ├── onboarding.py
        │   └── broker_status.py  # Position reconciliation
        └── services/
            ├── portfolio.py      # apply_buy(), apply_sell(), get_portfolio_state()
            ├── recommender.py    # Claude 4-call pipeline + NYSE holiday check
            ├── research.py       # Data orchestration: Alpaca, yfinance, FRED, Twelvedata, Alpha Vantage, Finnhub, EDGAR
            ├── alpaca_data.py    # Alpaca Data API: snapshots, bars (IEX), news, screener
            ├── technicals.py     # MACD, Bollinger, MA crossover, support/resistance, ATR
            ├── finnhub_data.py   # Analyst consensus, recommendation trends
            ├── economic_calendar.py  # FRED-based upcoming release tracking
            ├── risk_review.py    # Call 3: adversarial risk committee review
            ├── position_mgmt.py  # Call 4: EOD position management review
            ├── reflection.py     # Weekly trade reflection + learnings
            ├── playbook.py       # Playbook read/update
            └── strategy.py       # load_strategy() from strategy.json

---

Quick Start (Local)

Prerequisites

• Docker + Docker Compose
• An Anthropic API key

1. Clone and configure

git clone https://github.com/willcassell/scorched.git
cd scorched
cp .env.example .env
# Edit .env — at minimum set ANTHROPIC_API_KEY

2. Start everything

docker compose up -d --build

This starts PostgreSQL, waits for it to be healthy, then starts the app (Alembic migrations run automatically at startup).

3. Verify

curl http://localhost:8000/health
# {"status":"ok","db":"connected"}

# Open dashboard
open http://localhost:8000

4. Trigger a recommendation run manually

curl -s -X POST http://localhost:8000/api/v1/recommendations/generate \
  -H "Content-Type: application/json" \
  -d '{}'

---

Environment Variables

Create .env in the project root (see .env.example for full template):

# Required
ANTHROPIC_API_KEY=sk-ant-api03-...

# Portfolio
STARTING_CAPITAL=100000          # Starting cash in dollars

# Tax rates (optional — these are the defaults)
SHORT_TERM_TAX_RATE=0.37
LONG_TERM_TAX_RATE=0.20

# Server
PORT=8000
HOST=0.0.0.0

# Optional data sources (enable richer context)
FRED_API_KEY=                    # Free: https://fredaccount.stlouisfed.org
TWELVEDATA_API_KEY=              # Free tier: 800 calls/day, RSI for full watchlist
ALPHA_VANTAGE_API_KEY=           # Free tier: 25 calls/day, RSI fallback for screener
FINNHUB_API_KEY=                 # Free: analyst consensus
# (Polygon.io was removed April 2026 — Alpaca news replaced it)

# Optional: require a PIN to update strategy via dashboard
SETTINGS_PIN=

# Optional broker (default: paper trading, no broker needed)
BROKER_MODE=paper                # "paper", "alpaca_paper", or "alpaca_live"
ALPACA_API_KEY=
ALPACA_SECRET_KEY=

# Optional notifications
TELEGRAM_BOT_TOKEN=
TELEGRAM_CHAT_ID=

Note: DATABASE_URL is not needed in .env when using Docker Compose — it's set automatically via the environment block in docker-compose.yml.

---

Deployment (Oracle Cloud / Ubuntu VM)

See DEPLOY.md for the full guide, including:

• rsync command to copy files to the VM
• .env setup on the VM
• Firewall / port configuration
• Cron job setup for the automated daily cycle
• DST time adjustments

Cron timezone: Crontab entries use Eastern Time (NYSE local) directly — no DST math required. The Docker container sets TZ=America/New_York. Each cron script runs a sanity check that warns via Telegram if it fires at the wrong ET hour.

---

Dashboard

The web dashboard at http://host:8000 shows:

• Portfolio performance and today's picks
• Open positions with buy thesis, P&L, and tax classification
• Today's market analysis (with extended thinking toggle)
• Recent closed trades
• Tax summary (ST/LT breakdown)
• Living strategy playbook
• Claude API cost tracker (with daily spend progress bar)

Auto-refreshes every 5 minutes.

---

Useful Commands

# Logs
docker compose logs tradebot -f
docker compose logs tradebot --tail=50

# Rebuild after code changes (keeps postgres data)
docker compose up -d --build tradebot

# Shell into the app container
docker compose exec tradebot sh

# PostgreSQL shell
docker compose exec postgres psql -U scorched scorched

# Force a fresh recommendation run (bypass today's cache)
curl -s -X POST http://localhost:8000/api/v1/recommendations/generate \
  -H "Content-Type: application/json" \
  -d '{"force": true}'

# Wipe database (destructive!)
docker compose down -v

---

Security

If running on a public VM, do not expose port 8000 directly to the internet.

The recommended setup is one of:

• Tailscale or WireGuard VPN — only your devices can reach the bot
• Reverse proxy with auth — nginx or Caddy with basic auth or client certificates
• Cloud firewall — restrict port 8000 to your IP only (sudo ufw allow from YOUR_IP to any port 8000)

MCP mutation tools (confirm_trade, reject_recommendation, get_recommendations) require the owner PIN when SETTINGS_PIN is configured. Read-only tools (get_portfolio, get_market_summary, read_playbook, get_opening_prices) do not require a PIN.

REST mutation endpoints also require the PIN via the X-Owner-Pin header.