An LLM multi-agent stock research framework with an autonomous paper-trading loop.
Part of the Forezai suite alongside the Forezai Polybot console. Local fork of TauricResearch/TradingAgents.
Upstream TauricResearch/TradingAgents is the research framework: four LLM analysts (market, fundamentals, news, social), a bull-vs-bear debate, a trader synthesis, and a portfolio-manager final decision. This fork keeps all of that and adds everything needed to operate it as a closed-loop paper-trading simulator plus a web UI.
| Addition | What it does |
|---|---|
| Codex OAuth provider | Run TradingAgents on your ChatGPT Pro subscription. Zero marginal LLM cost. Cherry-picked from upstream PR #749 plus a CLI login flow. |
| Web UI (FastAPI + React) | Dashboard, paper trading, runs history, performance analytics, settings — all reachable at http://127.0.0.1:8000/ |
| Paper broker abstraction | Local broker (yfinance fills, JSON persistence) + Alpaca paper adapter + Shadow mode (mirror both brokers in parallel) |
| Autonomous loop | Scheduler fires daily analyses on a 65-ticker watchlist · auto-trader maps ratings to orders · position manager exits on TP / SL / max-hold |
| Performance dashboard | Time-range pills (1D / 1W / 1M / 3M / All), SVG equity curve + drawdown, top winners / losers, win-rate by rating / ticker / model, LLM cost vs realized P/L |
| Closed-trades journal | Append-only JSONL with realized P/L, return %, exit reason, alpha vs SPY (or BTC-USD for crypto) |
| Sector risk overlay | GICS sectors + Defense / ETF / Crypto carve-outs · max_sector_pct cap |
| 24/7 crypto scheduler | BTC-USD etc. bypass NYSE calendar · fundamentals analyst skipped for crypto · per-asset-class benchmark |
| Multi-channel alerts | Slack / Discord / SMTP email on rating events and paper-order fills |
| MCP data plug-in framework | Drop in Anthropic FSI MCP servers (Kensho, Aiera, FactSet, Morningstar, LSEG, …) as additional analyst tools |
Kronos forecasts (Phase A · opt-in [kronos] extra) |
Dashboard side panel comparing LLM ratings to OHLCV foundation-model forecasts (Kronos). Research-only — does not drive trades. See LOCAL_NOTES.md. |
| Disclaimer + traceability | Every report prepends "Research, not advice" and appends a footer with version · commit · provider · models |
Test count: 520+ passing across pure services, webapp glue, and HTTP routes.
uv sync # build .venv from uv.lock
uv run python scripts/codex_oauth_login.py # one-time OAuth (browser flow)
uv run python scripts/codex_oauth_smoke.py # verify backend round-trip1. One-shot research (CLI):
uv run tradingagents # interactive CLI; pick ticker + dateOutput: a complete_report.md with structured 5-tier rating (Buy / Overweight / Hold / Underweight / Sell), executive summary, thesis, price target, time horizon.
2. Web UI (recommended):
uv run --extra web python -m uvicorn webapp.backend.main:app --host 127.0.0.1 --port 8000Open http://127.0.0.1:8000/. Dashboard shows live runs, autonomous-mode toggle, trade pipeline view, usage / cost stats.
3. Autonomous paper-trading loop:
Three independent layers, all disabled by default. The Dashboard's "Autonomous paper trading" panel flips them together; safety opt-ins (dry_run, allow_list, kill_switch) stay user-controlled.
# Enable position manager (TP 8% / SL 4% / max-hold 10d pre-filled)
curl -X PUT -H 'Content-Type: application/json' \
-d '{"enabled": true}' \
http://127.0.0.1:8000/api/position-manager/config
# Populate the auto-trader allow-list from the watchlist
ALLOW=$(curl -s http://127.0.0.1:8000/api/watchlist | \
python3 -c 'import json,sys;print(json.dumps([t["ticker"] for t in json.load(sys.stdin)]))')
curl -X PUT -H 'Content-Type: application/json' \
-d "{\"allow_list\": $ALLOW, \"max_sector_pct\": 30}" \
http://127.0.0.1:8000/api/paper/auto/config
# Flip the master toggle (scheduler + auto-trader + position manager)
curl -X POST -H 'Content-Type: application/json' \
-d '{"enabled": true}' \
http://127.0.0.1:8000/api/autonomous/toggle
# Emergency stop
curl -X POST -H 'Content-Type: application/json' \
-d '{"enabled": false}' \
http://127.0.0.1:8000/api/autonomous/toggleFull operator guide: LOCAL_NOTES.md. Change log: CHANGELOG.md.
Every screenshot below is captured from the live system — real positions, real prices, real P/L. No mocks.
Dashboard — autonomous mode toggle, usage cost, live runs strip, and the trade pipeline joining 65 tickers × runs × ratings × positions × P/L in one view.
Performance tab — time-range pills (1D / 1W / 1M / 3M / All), SVG equity curve, rolling-peak drawdown chart, top winners / losers, win-rate by rating / ticker / model, headline narrative summarizing the period.
History — every closed paper trade with return %, exit reason, SPY/BTC benchmark return, and alpha. Append-only journal at ~/.tradingagents/closed_trades.jsonl.
Paper trading positions — live open positions with unrealized P/L, percentage moves, and entry context.
Auto-execute controls — master enable / dry-run / kill switch, allow-list, per-position and per-sector caps, cooldown, and the five-tier rating-to-target-% mapping.
A standalone marketing page with all of these is served at http://127.0.0.1:8000/marketing.html when the webapp is running.
Engine Auto-trader Position manager
(per run) (per RunCompleted) (every 60s)
───────── ────────────────── ──────────────────
4 analysts rating → target % TP / SL / max-hold
bull/bear debate allow-list filter per-position check
trader synthesis cooldown gate place_order(SELL)
risk team sector cap journal closed trade
PM final decision cash check
place_order(BUY/SELL)
Each loop is a separate Python module with its own audit log. Read any one without touching the others. Each is independently testable.
| Loop | Module | Audit file (~/.tradingagents/) |
|---|---|---|
| Engine | tradingagents/graph/trading_graph.py |
(run-level events) |
| Scheduler | tradingagents/services/scheduler.py |
scheduler_audit.jsonl |
| Auto-trader | tradingagents/services/auto_trader.py |
auto_trader_audit.jsonl |
| Position manager | tradingagents/services/position_manager.py |
position_manager_audit.jsonl |
| Closed-trades | tradingagents/services/closed_trades.py |
closed_trades.jsonl |
- Alpaca live trading endpoints are hard-refused at save time and at broker init. The adapter is paper-only by contract.
- Every layer ships disabled by default (
enabled = false). dry_run = trueis the auto-trader default — orders are logged but not placed.- Empty
allow_listis the safe default — nothing is in scope. - Per-position cap (
max_position_pct, default 5%). - Per-sector cap (
max_sector_pct, default 30%, Defense carved out from Industrials). - Per-ticker 24-hour cooldown after each auto-trader action.
- Global kill switch fires instantly via
POST /api/paper/auto/kill.
Research, not advice. Outputs are model-generated; verify against primary sources before acting. Past performance — including any track-record figures shown in this UI — does not predict future results.
| Provider | Cost | Notes |
|---|---|---|
| Codex OAuth | $0 marginal | ChatGPT Pro subscription used directly. Login via scripts/codex_oauth_login.py. |
| OpenAI | API metered | Standard API key |
| Anthropic | API metered | Claude API |
| Google Gemini, DeepSeek, Qwen / DashScope, GLM / Zhipu, Azure OpenAI | various | Configurable in Settings → Provider & models |
This repository keeps the full upstream multi-agent framework: four analysts (market · fundamentals · news · social), a bull/bear research debate, a trader synthesis, a three-voice risk team, and a portfolio-manager final decision. See the upstream framework README for the academic paper and original docs.
The engine's structured-output decision agents (Research Manager, Trader, Portfolio Manager) and persistent decision log are upstream features.
Please cite the upstream paper if you use this work:
@misc{xiao2025tradingagentsmultiagentsllmfinancial,
title={TradingAgents: Multi-Agents LLM Financial Trading Framework},
author={Yijia Xiao and Edward Sun and Di Luo and Wei Wang},
year={2025},
eprint={2412.20138},
archivePrefix={arXiv},
primaryClass={q-fin.TR},
url={https://arxiv.org/abs/2412.20138},
}