AI-TRADER: open-source paper trading so your AI agents compete first

Here is the quick start I use. Get Python 3.11 and Git installed, then set up a clean project folder. On macOS with Homebrew:

bash
brew install [email protected] git

Create a workspace, grab the AI-TRADER repo from GitHub as a ZIP, and unzip it into that folder. Open a terminal in the project root, then create a virtual env and install deps:

bash
python3.11 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install -r requirements.txt

Register the built-in paper account in the tool, pick two or three starter strategies, and run a short session to make sure it streams data and logs trades. Quick verify step:

bash
python scripts/run.py --list-strategies

You should see a list like "mean_reversion", "breakout", "rsi_cross" with IDs. Stop here for now. The next part covers per-OS setup, expected outputs, and the config tweaks that make the competition fair.

Here is the quick start I use. Get Python 3.11 and Git installed, then set up a clean project folder. On macOS with Homebrew:

bash
brew install [email protected] git

Create a workspace, grab the AI-TRADER repo from GitHub as a ZIP, and unzip it into that folder. Open a terminal in the project root, then create a virtual env and install deps:

bash
python3.11 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install -r requirements.txt

Register the built-in paper account in the tool, pick two or three starter strategies, and run a short session to make sure it streams data and logs trades. Quick verify step:

bash
python scripts/run.py --list-strategies

You should see a list like "mean_reversion", "breakout", "rsi_cross" with IDs. Stop here for now. The next part covers per-OS setup, expected outputs, and the config tweaks that make the competition fair.

Setup

macOS

• Install Python and Git.

bash
brew install [email protected] git
python3.11 --version

• Make a workspace and unpack the repo ZIP you downloaded from GitHub.

bash
mkdir -p ~/ai-lab && cd ~/ai-lab
unzip ~/Downloads/ai-trader-main.zip -d .
cd ai-trader-main

• Create a virtual environment and install dependencies.

bash
python3.11 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip wheel
python -m pip install -r requirements.txt

Linux (Debian/Ubuntu)

• Install Python, venv tools, Git, and unzip.

bash
sudo apt update
sudo apt install -y python3.11 python3.11-venv python3-pip git unzip
python3.11 --version

• Unpack the repo ZIP and install deps.

bash
mkdir -p ~/ai-lab && cd ~/ai-lab
unzip ~/Downloads/ai-trader-main.zip -d .
cd ai-trader-main
python3.11 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip wheel
python -m pip install -r requirements.txt

Windows 11

• Install Python 3.11 from the Store or use winget.

bash
winget install --id Python.Python.3.11 -e
winget install --id Git.Git -e
python --version

• Unzip the repo to a folder, then in PowerShell:

bash
cd $HOME\Downloads\ai-trader-main
python -m venv .venv
. .\.venv\Scripts\Activate.ps1
python -m pip install --upgrade pip wheel
python -m pip install -r requirements.txt

Initialize paper trading

• From the project root, run the built-in init. It creates a local config and opens the paper account sign-up in your browser.

bash
python scripts/run.py --init-paper

• After sign-up, the tool writes a config file at config/paper.yaml with your paper API key and secret stored locally.

• Add two or more starter strategies. You can point to the included examples in strategies/.

bash
python scripts/run.py --add-strategy strategies/mean_reversion.yaml
python scripts/run.py --add-strategy strategies/breakout.yaml
python scripts/run.py --add-strategy strategies/rsi_cross.yaml

Verify

List strategies and run a short backfill to confirm data access and logging.

bash
python scripts/run.py --list-strategies

Expected output snippet:

Strategies:
- id: s1  name: mean_reversion  markets: AAPL, MSFT, BTC-USD
- id: s2  name: breakout        markets: NVDA, ETH-USD
- id: s3  name: rsi_cross       markets: SPY, BTC-USD

Start a 15 minute paper session with all strategies competing. This streams live ticks where available and minute bars for equities.

bash
python scripts/run.py --paper --duration 15m --concurrency 3

Expect log lines like:

[paper] 09:31:02 AAPL s1 ENTER long 10 @ 212.34
[paper] 09:34:15 AAPL s1 EXIT  long 10 @ 213.02 PnL +$6.80
[paper] 09:36:00 BTC-USD s3 ENTER short 0.01 @ 66542.1
[paper] 09:44:00 BTC-USD s3 EXIT  short 0.01 @ 66310.4 PnL +$2.32
[summary] s1: +$6.80, s2: -$3.10, s3: +$2.32  Winner: s1

If you see PnL and a winner summary at the end, you are set.

Configuration tips

• Set a fair fee model. Edit config/paper.yaml and set realistic fees per venue. Example: 0.0035 for crypto taker, $0.005 per share for equities. This changes who actually wins.
• Add slippage. Set slippage_bps to 5 to punish strategies that rely on perfect fills. It helps filter out overfit scalpers.
• Warm-up period. In each strategy YAML, add warmup_bars: 100 so indicators have history before the first trade.
• Risk per trade. Use risk_fixed_usd: 50 or risk_fraction: 0.01 to keep losers small while strategies compete.
• Expand universes. Keep equities to 5 to 10 tickers per strategy at first. For crypto, start with BTC-USD and ETH-USD before adding more.

Troubleshooting

• Error: "No module named '...'"

Fix: your virtual env is not active. Reactivate it and reinstall.

bash
source .venv/bin/activate  # macOS/Linux
. .\.venv\Scripts\Activate.ps1  # Windows
python -m pip install -r requirements.txt

• Error: "Paper API auth failed"

Fix: re-run init and verify keys in config/paper.yaml. Delete the file if needed and initialize again.

bash
rm -f config/paper.yaml
python scripts/run.py --init-paper

• Error: "No strategies found"

Fix: add at least one strategy YAML or point to a folder.

bash
python scripts/run.py --add-strategy strategies/mean_reversion.yaml
python scripts/run.py --list-strategies

When it beats paid copy-trading platforms

• You want to compare idea quality, not influencer volume. AI-TRADER runs identical sessions across the same symbols and fee model, then ranks winners by realized PnL.
• You need to see entries and exits. It logs every fill, stop, and exit with timestamps. You can replay why a strategy won instead of trusting a screenshot.
• You build your own agent. Plug it in, run it against baselines like breakout and RSI cross on the same market set, and keep it only if it wins over a week of paper trades.
• You want crypto and US stocks in one place. One session runs both, then reports a single leaderboard.

Sources