Local-first, multi-agent LLM paper-trading backtest simulator. Three specialized LLM advisor agents debate every trade — and a deterministic, hard-coded risk gate gets the final word.
LLMs propose. Code disposes.
Letting a probabilistic model make final financial decisions is a failure mode, not a feature. Paperclaw is built around that constraint: the LLM agents are advisory-only and never have unilateral authority to execute a trade. Every proposal passes through a rule-based risk layer with veto power before the simulated broker ever sees it.
It's also local-first: all inference runs on your machine via Ollama using qwen2.5:1.5b — no API keys for the LLM layer, no per-call costs, no external rate limits while looping over thousands of simulated trading days. The tradeoff (a 1.5B model is far weaker than a frontier model) is deliberate: the system compensates with structure — agent decomposition plus a deterministic gate — instead of raw model intelligence.
┌──────────────┐
market data ───▶ │ Chart agent │──┐
(Alpaca API) ├──────────────┤ │ proposals ┌────────────────┐ ┌──────────────┐
───▶ │ News agent │──┼───────────────▶ │ Deterministic │ ───▶ │ Simulated │
├──────────────┤ │ │ risk gate │ │ execution │
───▶ │ Macro agent │──┘ │ (final say) │ │ (paper only)│
└──────────────┘ └────────────────┘ └──────────────┘
- Chart agent reasons over price action and technical signals
- News agent reasons over news-driven sentiment and events
- Macro agent reasons over the broader macroeconomic context
Each agent weighs in independently on every prospective trade. Their combined input is then evaluated by the risk gate — a non-LLM, rule-based layer that can block or modify any proposal. This bounds the blast radius of any single bad LLM judgment.
Describe a strategy in natural language and Paperclaw compiles it into an executable definition the backtest engine can run — a small DSL-generation layer over natural-language input, conceptually similar to text-to-SQL but targeting trading logic.
"Buy when the 20-day moving average crosses above the 50-day,
only in liquid large caps, max 5% of portfolio per position,
exit on a 7% trailing stop."
│
▼ StrategySpec compiler
executable strategy definition → backtest engine
| Layer | Technology |
|---|---|
| LLM inference | Ollama · qwen2.5:1.5b (local) |
| Market data / simulated execution | Alpaca API |
| Backend | FastAPI |
| Frontend | Next.js |
| Storage | SQLite |
| API contract | OpenAPI spec (contract-first monorepo) |
The repo is a contract-first monorepo: the OpenAPI spec is the source of truth, and both the FastAPI backend and the Next.js frontend are generated/validated against that shared contract, eliminating client–server drift.
Prerequisites: Python 3.11+, Node 18+, Ollama running locally, and an Alpaca paper-trading API key.
# 1. Pull the local model
ollama pull qwen2.5:1.5b
# 2. Backend
cd backend
pip install -r requirements.txt
uvicorn app.main:app --reload
# 3. Frontend
cd frontend
npm install
npm run devSet your Alpaca paper-trading credentials in .env (never use live-trading keys — Paperclaw is simulation-only by design).
- Advisory-only LLMs - no model output executes without passing the deterministic gate
- Local-first - reproducible inference environment, zero external LLM dependencies
- Paper trading only - no live-broker execution paths exist
- Contract-first - the OpenAPI spec drives both sides of the stack
Paperclaw is a research and educational tool for simulated paper trading. Nothing in this repository is financial advice, and it is not designed to place real trades.
MIT