Multi-Agent Paper Trader

AI-powered multi-agent paper trading system for stocks and Polymarket. Rule-based signal agents (Phases 0–5) hand the final trade decision to a Claude arbiter (Phase 6), with correlation analysis and plain-English trade explanations.

Status: 🟡 Built, unconfigured. Awaiting API keys before first live run. Safety: Paper trading only — PAPER_ONLY = True in src/config.py. No real money is ever at risk.

What it does

1. Paper-trades stocks using economic data (FRED), news sentiment (Finnhub + FinBERT), and technical indicators (RSI, MACD, SMA). Orders execute through Alpaca's paper trading API against real market prices.
2. Paper-trades Polymarket by detecting arbitrage (YES+NO < $1.00) and information-lag opportunities in prediction markets.
3. Finds correlations between Polymarket contracts and stock movements (e.g., recession contract vs SPY, Fed rate contract vs bank stocks).
4. Explains itself in plain English — every trade comes with a paragraph you can actually read. Example: "Bought 15 shares of AAPL at $178.50 because RSI hit 28 (oversold) while the long-term trend is still up."
5. Logs to Mission Control — all trades, portfolio snapshots, and correlation alerts POST to a local dashboard.

Quick Start (Mac)

See SETUP.md for full setup instructions.

# Clone, install, configure (one time)
git clone <this-repo> ~/Documents/multi-agent-paper-trader
cd ~/Documents/multi-agent-paper-trader
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
python scripts/setup_secrets.py   # interactive key entry

# Verify everything works
python scripts/check_apis.py

# First read-only snapshot
python scripts/run_trader.py --snapshot

# One live paper-trading cycle (during market hours)
python scripts/run_trader.py --once

# Continuous loop
python scripts/run_trader.py

Architecture

[Alpaca]  [FRED]  [Finnhub]  [Polymarket]
      \      |       |           /
       ---DATA LAYER---
              |
       [STRATEGY ENGINE]
      /       |        \
 Stock   Polymarket  Correlation
 Strats  Strategies   Engine
      \       |        /
       ---EXECUTION LAYER---
              |
         [RISK GUARD]
              |
      [PAPER TRADE + LOG]
              |
      [PLAIN-ENGLISH EXPLAINER]
              |
       POST to Mission Control

See Notion P-OCTRADE for the full project page with learning resources, and R-TRADE101 for 24 educational concept notes (RSI, MACD, Kelly Criterion, etc.).

Risk Guardrails

Limit	Default
Max single position	5% of portfolio
Max daily loss	2% of portfolio
Max open positions	10
Max orders per hour	20
Position sizing	Half-Kelly
Mode	Paper only — real-money URLs are not defined in code

Tech Stack

• Python 3.12 (3.10+ supported)
• Alpaca Markets — stock paper trading
• FRED — economic data (Fed rates, GDP, unemployment, yield curve)
• Finnhub — news + FinBERT sentiment scoring
• Polymarket Gamma API — prediction market data
• pandas-ta — technical indicators
• Backtrader — historical strategy testing
• SQLite — trade journal + API cache
• Mission Control — dashboard at http://localhost:3333 (separate repo)

Project Structure

src/
├── config.py              # Central settings, risk limits, feature flags
├── data/                  # Market/economic/news/polymarket data ingestion
├── strategy/              # Trading logic (mean reversion, momentum, sentiment, arbitrage)
├── execution/             # Order submission + risk guard
├── explain/               # Plain-English trade narrator
├── correlation/           # Polymarket-vs-stocks analysis
├── dashboard/             # Mission Control client
└── backtest/              # Historical strategy testing

scripts/
├── setup_secrets.py       # Interactive API key setup
├── check_apis.py          # Verify all connections
├── run_trader.py          # Main trading bot
└── run_backtest.py        # Historical testing

API Keys Required

All free tier. Setup instructions in SETUP.md.

API	Purpose	Signup
Alpaca	Stock paper trading ($100k virtual)	alpaca.markets
FRED	Economic data	fred.stlouisfed.org/docs/api/api_key.html
Finnhub	News + sentiment	finnhub.io
Polymarket	Prediction markets	No key needed (public API)

Build Phases

• ✅ Phase 0: Foundation (config, secrets, MC client)
• ✅ Phase 1: Data Layer (market, economic, news, technicals, polymarket)
• ✅ Phase 2: Stock Trading Bot (mean reversion + risk guard + narrator)
• ✅ Phase 3: Polymarket Bot (arbitrage + info lag)
• ✅ Phase 4: Correlation Engine
• ✅ Phase 5: Backtesting
• ⏳ Phase 6: Mission Control trading dashboard (Next.js, separate repo)
• ⏳ Phase 7+: Regime detection, trade memory (vector DB), AI trade autopsy, pre-market game plan, trailing stops, scalping strategy

License

Private. Not for redistribution.

Contact

Mike Cutillo · cutillo@gmail.com