ai-trader
Backtrader-powered backtesting framework for algorithmic trading, featuring 20+ strategies, multi-market support, CLI tools, and an integrated MCP server for professional traders.
Safety scan
A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.
Badge for your README
Markdown
[](/listings/whchien--ai-trader)HTML
<a href="/listings/whchien--ai-trader"><img src="/api/listings/whchien--ai-trader/badge.svg" alt="findsafeskills safety rating" /></a>Install
Install instructions from the README
As written by the repo's author. findsafeskills has not verified these steps.
**1. Installation**
**Option A: Install from PyPI (Recommended for using the CLI)**
pip install ai-trader
Use this if you want to: - Use the CLI commands: `ai-trader run`, `ai-trader fetch`, `ai-trader quick` - Run backtests on your own data files - Use as a library in your Python projects
**Option B: Install from Source (Recommended for examples and config templates)**
git clone https://github.com/whchien/ai-trader.git cd ai-trader # Install dependencies (choose one method) uv sync # Recommended (fastest, modern tool) # poetry install # Or use Poetry # pip install -e . # Or traditional pip with editable install
Use this if you want to: - Run the config-based examples in `config/backtest/` - Use the example data files in `data/` - Run the example scripts in `scripts/examples/` - Contribute or customize strategies
**2. Run a Backtest via CLI**
**If you cloned from source**, run a predefined backtest using a configuration file:
# Run a backtest from a config file (requires source installation) ai-trader run config/backtest/classic/sma_example.yaml
Or, run a quick backtest on any data file (works with both pip and source installation):
# Quick backtest on your own data file ai-trader quick CrossSMAStrategy your_data.csv --cash 100000
**3. Fetch Market Data**
Download historical data for any supported market:
# US Stock (default: saves to CSV) ai-trader fetch TSM --market us_stock --start-date 2020-01-01 # Taiwan Stock (台灣股票) ai-trader fetch 2330 --market tw_stock --start-date 2020-01-01 # Cryptocurrency ai-trader fetch BTC-USD --market crypto --start-date 2020-01-01 # With SQLite persistent caching (NEW!) ai-trader fetch AAPL --market us_stock --start-date 2024-01-01 --storage sqlite # Save to both CSV and SQLite ai-trader fetch AAPL --market us_stock --start-date 2024-01-01 --storage both
**Persistent Data Storage with SQLite**
By default, `ai-trader fetch` saves data to CSV. For faster repeated backtests, use SQLite:
# First fetch: Downloads from API and caches in SQLite (~2-3 seconds) ai-trader fetch AAPL --market us_stock --start-date 2024-01-01 --storage sqlite # Repeated fetch: Loads from cache (~50ms, no API call) ai-trader fetch AAPL --market us_stock --start-date 2024-01-01 --storage sqlite # Check cached data ai-trader data list ai-trader data info # Clean old data ai-trader data clean --market us_stock --before 2020-01-01
[**Learn more about SQLite Storage →**](agentic_ai_trader/trading-backtester/README.md#persistent-data-storage-with-sqlite)
What was scanned
The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.
README.md · README · 266 lines
View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)
- # AI-Trader
- [](https://www.python.org/downloads/)
- [](LICENSE)
- [中文版說明 (Chinese Subpage)](README_zh.md)
- A professional, config-driven backtesting framework for algorithmic trading, built on Backtrader. Seamlessly test, optimize, and integrate trading strategies with Large Language Models (LLMs) across stocks, crypto, and forex markets.
- 
- ## Key Features
- - **Config-Driven Workflows**: Define and manage backtests with version-controllable YAML files for reproducible results.
- - **Seamless LLM Integration**: Built-in MCP (Model Context Protocol) server allows AI assistants like Claude to run backtests, fetch data, and analyze strategies.
- - **Multi-Market Support**: Test strategies on US stocks, Taiwan stocks, cryptocurrencies, and forex.
- - **Extensive Strategy Library**: Comes with over 20 built-in strategies, from classic indicators to advanced adaptive models.
- - **Powerful CLI**: A rich command-line interface to run backtests, fetch market data, and list strategies.
- - **Developer Friendly**: Easily create and test custom strategies with simple helpers and a clear structure.
- ## Quick Start
- **1. Installation**
- **Option A: Install from PyPI (Recommended for using the CLI)**
- ```bash
- pip install ai-trader
- ```
- Use this if you want to:
- - Use the CLI commands: `ai-trader run`, `ai-trader fetch`, `ai-trader quick`
- - Run backtests on your own data files
- - Use as a library in your Python projects
- **Option B: Install from Source (Recommended for examples and config templates)**
- ```bash
- git clone https://github.com/whchien/ai-trader.git
- cd ai-trader
- # Install dependencies (choose one method)
- uv sync # Recommended (fastest, modern tool)
- # poetry install # Or use Poetry
- # pip install -e . # Or traditional pip with editable install
- ```
- Use this if you want to:
- - Run the config-based examples in `config/backtest/`
- - Use the example data files in `data/`
- - Run the example scripts in `scripts/examples/`
- - Contribute or customize strategies
- **2. Run a Backtest via CLI**
- **If you cloned from source**, run a predefined backtest using a configuration file:
- ```bash
- # Run a backtest from a config file (requires source installation)
- ai-trader run config/backtest/classic/sma_example.yaml
- ```
- Or, run a quick backtest on any data file (works with both pip and source installation):
- ```bash
- # Quick backtest on your own data file
- ai-trader quick CrossSMAStrategy your_data.csv --cash 100000
- ```
- **3. Fetch Market Data**
- Download historical data for any supported market:
- ```bash
- # US Stock (default: saves to CSV)
- ai-trader fetch TSM --market us_stock --start-date 2020-01-01
- # Taiwan Stock (台灣股票)
- ai-trader fetch 2330 --market tw_stock --start-date 2020-01-01
- # Cryptocurrency
- ai-trader fetch BTC-USD --market crypto --start-date 2020-01-01
- # With SQLite persistent caching (NEW!)
- ai-trader fetch AAPL --market us_stock --start-date 2024-01-01 --storage sqlite
- # Save to both CSV and SQLite
- ai-trader fetch AAPL --market us_stock --start-date 2024-01-01 --storage both
- ```
- **Persistent Data Storage with SQLite**
- By default, `ai-trader fetch` saves data to CSV. For faster repeated backtests, use SQLite:
- ```bash
- # First fetch: Downloads from API and caches in SQLite (~2-3 seconds)
- ai-trader fetch AAPL --market us_stock --start-date 2024-01-01 --storage sqlite
- # Repeated fetch: Loads from cache (~50ms, no API call)
- ai-trader fetch AAPL --market us_stock --start-date 2024-01-01 --storage sqlite
- # Check cached data
- ai-trader data list
- ai-trader data info
- # Clean old data
- ai-trader data clean --market us_stock --before 2020-01-01
- ```
- [**Learn more about SQLite Storage →**](agentic_ai_trader/trading-backtester/README.md#persistent-data-storage-with-sqlite)
- ## Core Workflows
- ### 1. Configuration-Based Backtesting
- The most robust way to run backtests is with a YAML config file.
- **`my_backtest.yaml`:**
- ```yaml
- broker:
- cash: 1000000
- commission: 0.001425
- data:
- file: "data/us_stock/TSM.csv"
- start_date: "2020-01-01"
- end_date: "2023-12-31"
- strategy:
- class: "CrossSMAStrategy"
- params:
- fast: 10
- slow: 30
- sizer:
- type: "percent"
- params:
- percents: 95
- ```
- **Run it:**
- ```bash
- ai-trader run my_backtest.yaml
- ```
- See `config/backtest/` for more examples.
- ### 2. Python-Based Backtesting
- For more granular control or integration into other Python scripts.
- **Simple approach:**
- ```python
- from ai_trader import run_backtest
- from ai_trader.backtesting.strategies.classic.sma import CrossSMAStrategy
- # Run backtest with example data
- results = run_backtest(
- strategy=CrossSMAStrategy,
- data_source=None, # Uses built-in example data
- cash=1000000,
- strategy_params={"fast": 10, "slow": 30}
- )
- ```
- **Step-by-step control:**
- See `scripts/examples/02_step_by_step.py` for a detailed example.
- ### 3. LLM Integration (MCP Server)
- Run `ai-trader` as a server to let AI assistants interact with your backtesting engine.
- **Start the Server (for testing):**
- ```bash
- python -m ai_trader.mcp
- ```
- **Configure with Claude Desktop (Recommended):**
- 1. Locate your Claude Desktop configuration file:
- - **macOS/Linux**: `~/.config/Claude/claude_desktop_config.json`
- - **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
- 2. Add the `ai-trader` MCP server to the `mcpServers` section:
- ```json
- {
- "mcpServers": {
- "ai-trader": {
- "command": "python3",
- "args": ["-m", "ai_trader.mcp"],
- "cwd": "/path/to/ai-trader"
- }
- }
- }
- ```
- **Configuration Notes:**
- - Replace `/path/to/ai-trader` with your actual ai-trader project directory
- - If using a virtual environment, use the full path to the Python executable: `/path/to/.venv/bin/python3`
- - Restart Claude Desktop after updating the config file
- Once configured, you can use Claude to interact with your backtesting engine with natural language commands like:
- - *"Run a backtest of the CrossSMAStrategy on TSM data from 2020-2022."*
- - *"List all available trading strategies."*
- - *"Fetch Apple stock data from 2021 to 2024."*
- ## Creating Custom Strategies
- ### Option 1: Using Claude Code Skills (Recommended)
- The fastest way to create a new strategy is with the `/add-strategy` skill in Claude Code. The skill guides you through the process interactively:
- ```bash
- /add-strategy classic
- ```
- This will prompt you for:
- - Strategy name (e.g., "MACDBBands")
- - Description
- - Parameters with defaults
- - Entry and exit conditions
- - Any custom indicators
- The skill automatically handles:
- - File creation with proper naming conventions
- - Comprehensive docstrings
- - Automatic registration in `__init__.py`
- - Syntax validation
- Learn more about Claude Code skills: https://code.claude.com/docs/en/skills
- ### Option 2: Manual Creation
- Create a new file in `ai_trader/backtesting/strategies/classic/` and inherit from `BaseStrategy`.
- ```python
- # ai_trader/backtesting/strategies/classic/my_strategy.py
- import backtrader as bt
- from ai_trader.backtesting.strategies.base import BaseStrategy
- class MyCustomStrategy(BaseStrategy):
- params = dict(period=20)
- def __init__(self):
- self.sma = bt.indicators.SMA(self.data.close, period=self.p.period)
- def next(self):
- if not self.position and self.data.close[0] > self.sma[0]:
- self.buy()
- elif self.position and self.data.close[0] < self.sma[0]:
- self.close()
- ```
- The new strategy is automatically available to the CLI and `run_backtest` function.
- ## Documentation & Resources
- - **[Strategy Examples](ai_trader/backtesting/strategies/README.md)**: Details on built-in strategies.
- - **[Example Scripts](scripts/examples/)**: 5 complete working examples for different use cases.
- - **[Config Templates](config/backtest/)**: YAML configuration templates.
- - **[Migration Guide](docs/MIGRATION_GUIDE.md)**: For upgrading from v0.1.x.
- ## Contributing
- Contributions are welcome! Feel free to report bugs, suggest features, or submit pull requests.
- ## Show Your Support
- If you find this project helpful, please give it a star !
- ## License
- This project is licensed under the GNU General Public License v3 (GPL-3.0). See the [LICENSE](LICENSE) file for details.
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.