# AI-Trader2
**Repository Path**: janl/ai-trader2
## Basic Information
- **Project Name**: AI-Trader2
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No
## Statistics
- **Stars**: 0
- **Forks**: 2
- **Created**: 2025-11-30
- **Last Updated**: 2025-11-30
## Categories & Tags
**Categories**: Uncategorized
**Tags**: None
## README
# ๐ AI-Trader: Can AI Beat the Market?
[](https://python.org)
[](LICENSE)
[](https://github.com/HKUDS/AI-Trader)
[](./Communication.md)
[](./Communication.md)
**AI agents battle for supremacy in NASDAQ 100, SSE 50, and cryptocurrency markets. Zero human input. Pure competition.**
## ๐ Current Championship Leaderboard ๐
[*Click Here: AI Live Trading*](https://ai4trade.ai)
---
## Friends of AI-Trader: Other Interesting Projects
- [TradeTrap](https://github.com/Yanlewen/TradeTrap): A security-focused toolkit to evaluate and harden LLM-based trading agents, featuring prompt injection and MCP hijacking attack modules for resilience testing.
- [RockAlpha](https://rockalpha.rockflow.ai/): The investment arena launched by RockFlow. LLM inputs include trading rules, market data, account status and buying power, as well as news; the output is the order-execution decision.
- [TwinMarket](https://github.com/FreedomIntelligence/TwinMarket): A multi-agent framework that leverages LLMs to simulate investor behavior and emergent socio-economic phenomena in A-share stock market.
---
## ๐ Weekly Update
### ๐ Market Expansion
- โ
**A-Share Market Support** - Extended our trading capabilities to include Chinese A-share markets, expanding our global market coverage.
- โ
**Cryptocurrency Market Support** - Added support for trading major cryptocurrencies including Bitcoin, Ethereum, and 8 other leading digital assets.
### โฐ Enhanced Trading Capabilities
- โ
**Hourly Trading Support** - We've upgraded from daily to hourly trading intervals, enabling more precise and responsive market participation with granular timing control.
### ๐จ User Experience Improvements
- โ
**Live Trading Dashboard** - Introduced real-time visualization of all agent trading activities: https://ai4trade.ai.
- โ
**Agent Reasoning Display** - Implemented complete transparency into AI decision-making processes, featuring detailed reasoning chains that show how each trading decision is formed.
- โ
**Interactive Leaderboard** - Launched a dynamic performance ranking system with live updates, allowing users to track and compare agent performance in real-time.
- โฐ **Important Notice** - To maintain a well-managed repository, we no longer upload runtime data to the repo, as it would make it very bloated. If you need to view runtime data, we will upload it to Hugging Face on a monthly basis. You can view real-time runtime data here: https://ai4trade.ai.
---
## **How to use this dataset**
It's simple!
You just need to submit a PR that includes at least: `./agent/{your_strategy}.py` (you can inherit from Basemodel to create your strategy!), `./configs/{yourconfig}`, and instructions on how to run your strategy. As long as we can run it, we will run it on our platform for more than a week and continuously update your results!
---
[๐ Quick Start](#-quick-start) โข [๐ Performance Analysis](#-performance-analysis) โข [๐ ๏ธ Configuration Guide](#-configuration-guide) โข [ไธญๆๆๆกฃ](README_CN.md)
## ๐ Project Introduction
> **AI-Trader enables five distinct AI models, each employing unique investment strategies, to compete autonomously in the same market and determine which can generate the highest profits in NASDAQ 100, SSE 50, or cryptocurrency trading!**
### ๐ฏ Core Features
- ๐ค **Fully Autonomous Decision-Making**: AI agents perform 100% independent analysis, decision-making, and execution without human intervention
- ๐ ๏ธ **Pure Tool-Driven Architecture**: Built on MCP toolchain, enabling AI to complete all trading operations through standardized tool calls
- ๐ **Multi-Model Competition Arena**: Deploy multiple AI models (GPT, Claude, Qwen, etc.) for competitive trading
- ๐ **Real-Time Performance Analytics**: Comprehensive trading records, position monitoring, and profit/loss analysis
- ๐ **Intelligent Market Intelligence**: Integrated Jina search for real-time market news and financial reports
- โก **MCP Toolchain Integration**: Modular tool ecosystem based on Model Context Protocol
- ๐ **Extensible Strategy Framework**: Support for third-party strategies and custom AI agent integration
- โฐ **Historical Replay Capability**: Time-period replay functionality with automatic future information filtering
---
### ๐ฎ Trading Environment
Each AI model starts with $10,000, 100,000ยฅ, or 50,000 USDT to trade NASDAQ 100 stocks, SSE 50 stocks, or major cryptocurrencies in a controlled environment with real market data and historical replay capabilities.
- ๐ฐ **Initial Capital**: $10,000 USD (US stocks), 100,000ยฅ CNY (A-shares), or 50,000 USDT (cryptocurrencies) starting balance
- ๐ **Trading Universe**:
- NASDAQ 100 component stocks (top 100 technology stocks)
- SSE 50 component stocks
- Major cryptocurrencies (BTC, ETH, XRP, SOL, ADA, SUI, LINK, AVAX, LTC, DOT)
- โฐ **Trading Schedule**: Entire Week for cryptocurrencies, weekday market hours for stocks with historical simulation support
- ๐ **Data Integration**: Alpha Vantage API combined with Jina AI market intelligence
- ๐ **Time Management**: Historical period replay with automated future information filtering
---
### ๐ง Agentic Trading Capabilities
AI agents operate with complete autonomy, conducting market research, making trading decisions, and continuously evolving their strategies without human intervention.
- ๐ฐ **Autonomous Market Research**: Intelligent retrieval and filtering of market news, analyst reports, and financial data
- ๐ก **Independent Decision Engine**: Multi-dimensional analysis driving fully autonomous buy/sell execution
- ๐ **Comprehensive Trade Logging**: Automated documentation of trading rationale, execution details, and portfolio changes
- ๐ **Adaptive Strategy Evolution**: Self-optimizing algorithms that adjust based on market performance feedback
---
### ๐ Competition Rules
All AI models compete under identical conditions with the same capital, data access, tools, and evaluation metrics to ensure fair comparison.
- ๐ฐ **Starting Capital**: $10,000 USD or 100,000ยฅ CNY initial investment
- ๐ **Data Access**: Uniform market data and information feeds
- โฐ **Operating Hours**: Synchronized trading time windows
- ๐ **Performance Metrics**: Standardized evaluation criteria across all models
- ๐ ๏ธ **Tool Access**: Identical MCP toolchain for all participants
๐ฏ **Objective**: Determine which AI model achieves superior investment returns through pure autonomous operation!
### ๐ซ Zero Human Intervention
AI agents operate with complete autonomy, making all trading decisions and strategy adjustments without any human programming, guidance, or intervention.
- โ **No Pre-Programming**: Zero preset trading strategies or algorithmic rules
- โ **No Human Input**: Complete reliance on inherent AI reasoning capabilities
- โ **No Manual Override**: Absolute prohibition of human intervention during trading
- โ
**Tool-Only Execution**: All operations executed exclusively through standardized tool calls
- โ
**Self-Adaptive Learning**: Independent strategy refinement based on market performance feedback
---
## โฐ Historical Replay Architecture
A core innovation of AI-Trader Bench is its **fully replayable** trading environment, ensuring scientific rigor and reproducibility in AI agent performance evaluation on historical market data.
### ๐ Temporal Control Framework
#### ๐
Flexible Time Settings
```json
{
"date_range": {
"init_date": "2025-01-01", // Any start date
"end_date": "2025-01-31" // Any end date
}
}
```
---
### ๐ก๏ธ Anti-Look-Ahead Data Controls
AI can only access market data from current time and before. No future information allowed.
- ๐ **Price Data Boundaries**: Market data access limited to simulation timestamp and historical records
- ๐ฐ **News Chronology Enforcement**: Real-time filtering prevents access to future-dated news and announcements
- ๐ **Financial Report Timeline**: Information restricted to officially published data as of current simulation date
- ๐ **Historical Intelligence Scope**: Market analysis constrained to chronologically appropriate data availability
### ๐ฏ Replay Advantages
#### ๐ฌ Empirical Research Framework
- ๐ **Market Efficiency Studies**: Evaluate AI performance across diverse market conditions and volatility regimes
- ๐ง **Decision Consistency Analysis**: Examine temporal stability and behavioral patterns in AI trading logic
- ๐ **Risk Management Assessment**: Validate effectiveness of AI-driven risk mitigation strategies
#### ๐ฏ Fair Competition Framework
- ๐ **Equal Information Access**: All AI models operate with identical historical datasets
- ๐ **Standardized Evaluation**: Performance metrics calculated using uniform data sources
- ๐ **Full Reproducibility**: Complete experimental transparency with verifiable results
---
## ๐ Project Architecture
```
AI-Trader Bench/
โโโ ๐ค Core System
โ โโโ main.py # ๐ฏ Main program entry
โ โโโ agent/
โ โ โโโ base_agent/ # ๐ง Generic AI trading agent (US stocks)
โ โ โ โโโ base_agent.py # Base agent class (daily)
โ โ โ โโโ base_agent_hour.py # Hourly trading agent (US stocks)
โ โ โ โโโ __init__.py
โ โ โโโ base_agent_astock/ # ๐จ๐ณ A-share specific trading agent
โ โ โ โโโ base_agent_astock.py # A-share agent class (daily)
โ โ โ โโโ base_agent_astock_hour.py # A-share hourly trading agent
โ โ โ โโโ __init__.py
โ โ โโโ base_agent_crypto/ # โฟ Cryptocurrency specific trading agent
โ โ โโโ base_agent_crypto.py # Crypto agent class
โ โ โโโ __init__.py
โ โโโ configs/ # โ๏ธ Configuration files
โ
โโโ ๐ ๏ธ MCP Toolchain
โ โโโ agent_tools/
โ โ โโโ tool_trade.py # ๐ฐ Trade execution (auto-adapts market rules)
โ โ โโโ tool_get_price_local.py # ๐ Price queries (supports US + A-shares)
โ โ โโโ tool_jina_search.py # ๐ Information search
โ โ โโโ tool_math.py # ๐งฎ Mathematical calculations
โ โ โโโ start_mcp_services.py # ๐ MCP service startup script
โ โโโ tools/ # ๐ง Auxiliary tools
โ
โโโ ๐ Data System
โ โโโ data/
โ โ โโโ daily_prices_*.json # ๐ NASDAQ 100 stock price data
โ โ โโโ merged.jsonl # ๐ US stocks daily unified data format
โ โ โโโ get_daily_price.py # ๐ฅ US stocks data fetching script
โ โ โโโ merge_jsonl.py # ๐ US stocks data format conversion
โ โ โโโ A_stock/ # ๐จ๐ณ A-share market data
โ โ โ โโโ A_stock_data/ # ๐ A-share data storage directory
โ โ โ โ โโโ sse_50_weight.csv # ๐ SSE 50 constituent weights
โ โ โ โ โโโ daily_prices_sse_50.csv # ๐ Daily price data (CSV)
โ โ โ โ โโโ A_stock_hourly.csv # โฐ 60-minute K-line data (CSV)
โ โ โ โ โโโ index_daily_sse_50.json # ๐ SSE 50 index benchmark data
โ โ โ โโโ merged.jsonl # ๐ A-share daily unified data format
โ โ โ โโโ merged_hourly.jsonl # โฐ A-share hourly unified data format
โ โ โ โโโ get_daily_price_tushare.py # ๐ฅ A-share daily data fetching (Tushare API)
โ โ โ โโโ get_daily_price_alphavantage.py # ๐ฅ A-share daily data fetching (Alpha Vantage API)
โ โ โ โโโ get_interdaily_price_astock.py # โฐ A-share hourly data fetching (efinance)
โ โ โ โโโ merge_jsonl_tushare.py # ๐ A-share daily data format conversion (Tushare API)
โ โ โ โโโ merge_jsonl_alphavantage.py # ๐ A-share daily data format conversion (Alpha Vantage API)
โ โ โ โโโ merge_jsonl_hourly.py # โฐ A-share hourly data format conversion (efinance)
โ โ โโโ crypto/ # โฟ Cryptocurrency market data
โ โ โ โโโ coin/ # ๐ Individual crypto price files
โ โ โ โ โโโ daily_prices_BTC.json # Bitcoin price data
โ โ โ โ โโโ daily_prices_ETH.json # Ethereum price data
โ โ โ โ โโโ ... # Other cryptocurrency data
โ โ โ โโโ crypto_merged.jsonl # ๐ Crypto unified data format
โ โ โ โโโ get_daily_price_crypto.py # ๐ฅ Crypto data fetching script
โ โ โ โโโ merge_crypto_jsonl.py # ๐ Crypto data format conversion
โ โ โโโ agent_data/ # ๐ AI trading records (NASDAQ 100)
โ โ โโโ agent_data_astock/ # ๐ A-share AI trading records
โ โ โโโ agent_data_crypto/ # ๐ Cryptocurrency AI trading records
โ โโโ calculate_performance.py # ๐ Performance analysis
โ
โโโ ๐ฌ Prompt System
โ โโโ prompts/
โ โโโ agent_prompt.py # ๐ Generic trading prompts (US stocks)
โ โโโ agent_prompt_astock.py # ๐จ๐ณ A-share specific trading prompts
โ
โโโ ๐จ Frontend Interface
โ โโโ frontend/ # ๐ Web dashboard
โ
โโโ ๐ Configuration & Documentation
โ โโโ configs/ # โ๏ธ System configuration
โ โ โโโ default_config.json # US stocks default configuration
โ โ โโโ astock_config.json # A-share configuration example
โ โโโ calc_perf.sh # ๐ Performance calculation script
โ
โโโ ๐ Quick Start Scripts
โโโ scripts/ # ๐ ๏ธ Convenient startup scripts
โโโ main.sh # One-click complete workflow (US stocks)
โโโ main_step1.sh # US stocks: Data preparation
โโโ main_step2.sh # US stocks: Start MCP services
โโโ main_step3.sh # US stocks: Run trading agent
โโโ main_a_stock_step1.sh # A-shares: Data preparation
โโโ main_a_stock_step2.sh # A-shares: Start MCP services
โโโ main_a_stock_step3.sh # A-shares: Run trading agent
โโโ main_crypto_step1.sh # Crypto: Data preparation
โโโ main_crypto_step2.sh # Crypto: Start MCP services
โโโ main_crypto_step3.sh # Crypto: Run trading agent
โโโ start_ui.sh # Start web UI interface
```
### ๐ง Core Components Details
#### ๐ฏ Main Program (`main.py`)
- **Multi-Model Concurrency**: Run multiple AI models simultaneously for trading
- **Dynamic Agent Loading**: Automatically load corresponding agent type based on configuration
- **Configuration Management**: Support for JSON configuration files and environment variables
- **Date Management**: Flexible trading calendar and date range settings
- **Error Handling**: Comprehensive exception handling and retry mechanisms
#### ๐ค AI Agent System
| Agent Type | Module Path | Use Case | Features |
|-----------|-------------|----------|----------|
| **BaseAgent** | `agent.base_agent.base_agent` | US stocks daily trading | Flexible market switching, configurable stock pool |
| **BaseAgent_Hour** | `agent.base_agent.base_agent_hour` | US stocks hourly trading | Hourly data support, fine-grained trading timing |
| **BaseAgentAStock** | `agent.base_agent_astock.base_agent_astock` | A-shares daily trading | Built-in A-share rules, SSE 50 default pool, Chinese prompts |
| **BaseAgentAStock_Hour** | `agent.base_agent_astock.base_agent_astock_hour` | A-shares hourly trading | A-share hourly data (10:30/11:30/14:00/15:00), T+1 rules |
| **BaseAgentCrypto** | `agent.base_agent_crypto.base_agent_crypto` | Cryptocurrency trading | BITWISE10 crypto pool, USDT denominated |
**Architecture Advantages**:
- ๐ **Clear Separation**: US, A-share, and cryptocurrency agents independently maintained without interference
- ๐ฏ **Specialized Optimization**: Each agent deeply optimized for specific market characteristics
- ๐ **Easy Extension**: Support adding more market-specific agents (e.g., Hong Kong stocks, commodities)
#### ๐ ๏ธ MCP Toolchain
| Tool | Function | Market Support | API |
|------|----------|----------------|-----|
| **Trading Tool** | Buy/sell assets, position management | ๐บ๐ธ US / ๐จ๐ณ A-shares / โฟ Crypto | `buy()`, `sell()` / `buy_crypto()`, `sell_crypto()` (For Crypto)|
| **Price Tool** | Real-time and historical price queries | ๐บ๐ธ US / ๐จ๐ณ A-shares / โฟ Crypto | `get_price_local()` |
| **Search Tool** | Market information search | Global markets | `get_information()` |
| **Math Tool** | Financial calculations and analysis | Generic | Basic mathematical operations |
**Tool Features**:
- ๐ **Auto-Recognition**: Automatically select data source based on symbol format (stock codes or crypto symbols)
- ๐ **Rule Adaptation**: Auto-apply corresponding market trading rules (T+0/T+1, lot sizes etc.)
- ๐ **Unified Interface**: Same API interface supports multi-market trading across stocks and cryptocurrencies
#### ๐ Data System
- **๐ Price Data**:
- ๐บ๐ธ Complete OHLCV data for NASDAQ 100 component stocks (Alpha Vantage)
- ๐จ๐ณ A-share market data (SSE 50 Index) via Tushare API
- โฟ Cryptocurrency market data (BITWISE10) via Alpha Vantage
- ๐ Unified JSONL format for efficient reading
- **๐ Trading Records**:
- Detailed trading history for each AI model
- Stored separately by market: `agent_data/` (US), `agent_data_astock/` (A-shares), `agent_data_crypto/` (Crypto)
- **๐ Performance Metrics**:
- Sharpe ratio, maximum drawdown, annualized returns, etc.
- Support multi-market performance comparison analysis
- **๐ Data Synchronization**:
- Automated data acquisition and update mechanisms
- Independent data fetching scripts with incremental update support
## ๐ Quick Start
### ๐ Prerequisites
- **Python 3.10+**
- **API Keys**:
- OpenAI (for AI models)
- Alpha Vantage (for NASDAQ 100 data)
- Jina AI (for market information search)
- Tushare (for A-share market data, optional)
### โก One-Click Installation
```bash
# 1. Clone project
git clone https://github.com/HKUDS/AI-Trader.git
cd AI-Trader
# 2. Install dependencies
pip install -r requirements.txt
# 3. Configure environment variables
cp .env.example .env
# Edit .env file and fill in your API keys
```
### ๐ Environment Configuration
Create `.env` file and configure the following variables:
```bash
# ๐ค AI Model API Configuration
OPENAI_API_BASE=https://your-openai-proxy.com/v1
OPENAI_API_KEY=your_openai_key
# ๐ Data Source Configuration
ALPHAADVANTAGE_API_KEY=your_alpha_vantage_key # For NASDAQ 100 and cryptocurrency data
JINA_API_KEY=your_jina_api_key
TUSHARE_TOKEN=your_tushare_token # For A-share data
# โ๏ธ System Configuration
RUNTIME_ENV_PATH=./runtime_env.json # Recommended to use absolute path
# ๐ Service Port Configuration
MATH_HTTP_PORT=8000
SEARCH_HTTP_PORT=8001
TRADE_HTTP_PORT=8002
GETPRICE_HTTP_PORT=8003
CRYPTO_HTTP_PORT=8005
# ๐ง AI Agent Configuration
AGENT_MAX_STEP=30 # Maximum reasoning steps
```
### ๐ฆ Dependencies
```bash
# Install production dependencies
pip install -r requirements.txt
# Or manually install core dependencies
pip install langchain langchain-openai langchain-mcp-adapters fastmcp python-dotenv requests numpy pandas tushare
```
## ๐ฎ Running Guide
### ๐ Quick Start with Scripts
We provide convenient shell scripts in the `scripts/` directory for easy startup:
#### ๐บ๐ธ US Market (NASDAQ 100)
```bash
# One-click startup (complete workflow)
bash scripts/main.sh
# Or run step by step:
bash scripts/main_step1.sh # Step 1: Prepare data
bash scripts/main_step2.sh # Step 2: Start MCP services
bash scripts/main_step3.sh # Step 3: Run trading agent
```
#### ๐จ๐ณ A-Share Market (SSE 50)
```bash
# Run step by step:
bash scripts/main_a_stock_step1.sh # Step 1: Prepare A-share data
bash scripts/main_a_stock_step2.sh # Step 2: Start MCP services
bash scripts/main_a_stock_step3.sh # Step 3: Run A-share trading agent
```
#### โฟ Cryptocurrency Market (BITWISE10)
```bash
# Run step by step:
bash scripts/main_crypto_step1.sh # Step 1: Prepare crypto data
bash scripts/main_crypto_step2.sh # Step 2: Start MCP services
bash scripts/main_crypto_step3.sh # Step 3: Run crypto trading agent
```
#### ๐ Web UI
```bash
# Start web interface
bash scripts/start_ui.sh
# Visit: http://localhost:8888
```
---
### ๐ Manual Setup Guide
If you prefer to run commands manually, follow these steps:
### ๐ Step 1: Data Preparation
#### ๐บ๐ธ NASDAQ 100 Data
```bash
# ๐ Get NASDAQ 100 stock data
cd data
python get_daily_price.py
# ๐ Merge data into unified format
python merge_jsonl.py
```
#### ๐จ๐ณ A-Share Market Data (SSE 50)
```bash
# ๐ Get Chinese A-share daily market data (SSE 50 Index)
cd data/A_stock
# ๐ Method 1: Get daily data using Tushare API (Recommended)
python get_daily_price_tushare.py
python merge_jsonl_tushare.py
# ๐ Method 2: Get daily data using Alpha Vantage API (Alternative)
python get_daily_price_alphavantage.py
python merge_jsonl_alphavantage.py
# ๐ Daily data will be saved to: data/A_stock/merged.jsonl
# โฐ Get 60-minute K-line data (hourly trading)
python get_interdaily_price_astock.py
python merge_jsonl_hourly.py
# ๐ Hourly data will be saved to: data/A_stock/merged_hourly.jsonl
```
#### โฟ Cryptocurrency Market Data (BITWISE10)
```bash
# ๐ Get cryptocurrency market data (BITWISE10)
cd data/crypto
# ๐ Get daily price data for major cryptocurrencies
python get_daily_price_crypto.py
# ๐ Merge data into unified format
python merge_crypto_jsonl.py
# ๐ Crypto data will be saved to: data/crypto/crypto_merged.jsonl
```
### ๐ ๏ธ Step 2: Start MCP Services
```bash
cd ./agent_tools
python start_mcp_services.py
```
### ๐ Step 3: Start AI Arena
#### For US Stocks (NASDAQ 100):
```bash
# ๐ฏ Run with default configuration
python main.py
# ๐ฏ Or specify US stock config
python main.py configs/default_config.json
```
#### For A-Shares (SSE 50):
```bash
# ๐ฏ Run A-share trading
python main.py configs/astock_config.json
```
#### For Cryptocurrencies (BITWISE10):
```bash
# ๐ฏ Run cryptocurrency trading
python main.py configs/default_crypto_config.json
```
### โฐ Time Settings Example
#### ๐
US Stock Configuration Example (Using BaseAgent)
```json
{
"agent_type": "BaseAgent",
"market": "us", // Market type: "us" for US stocks
"date_range": {
"init_date": "2024-01-01", // Backtest start date
"end_date": "2024-03-31" // Backtest end date
},
"models": [
{
"name": "claude-3.7-sonnet",
"basemodel": "anthropic/claude-3.7-sonnet",
"signature": "claude-3.7-sonnet",
"enabled": true
}
],
"agent_config": {
"initial_cash": 10000.0 // Initial capital: $10,000
}
}
```
#### ๐
A-Share Daily Configuration Example (Using BaseAgentAStock)
```json
{
"agent_type": "BaseAgentAStock", // A-share daily specific agent
"market": "cn", // Market type: "cn" A-shares (optional, will be ignored, always uses cn)
"date_range": {
"init_date": "2025-10-09", // Backtest start date
"end_date": "2025-10-31" // Backtest end date
},
"models": [
{
"name": "claude-3.7-sonnet",
"basemodel": "anthropic/claude-3.7-sonnet",
"signature": "claude-3.7-sonnet",
"enabled": true
}
],
"agent_config": {
"initial_cash": 100000.0 // Initial capital: ยฅ100,000
},
"log_config": {
"log_path": "./data/agent_data_astock" // A-share daily data path
}
}
```
#### ๐
A-Share Hourly Configuration Example (Using BaseAgentAStock_Hour)
```json
{
"agent_type": "BaseAgentAStock_Hour", // A-share hourly specific agent
"market": "cn", // Market type: "cn" A-shares (optional, will be ignored, always uses cn)
"date_range": {
"init_date": "2025-10-09 10:30:00", // Backtest start time (hourly)
"end_date": "2025-10-31 15:00:00" // Backtest end time (hourly)
},
"models": [
{
"name": "claude-3.7-sonnet",
"basemodel": "anthropic/claude-3.7-sonnet",
"signature": "claude-3.7-sonnet-astock-hour",
"enabled": true
}
],
"agent_config": {
"initial_cash": 100000.0 // Initial capital: ยฅ100,000
},
"log_config": {
"log_path": "./data/agent_data_astock_hour" // A-share hourly data path
}
}
```
> ๐ก **Tip**: A-share hourly trading time points: 10:30, 11:30, 14:00, 15:00 (4 time points per day)
> ๐ก **Tip**: When using `BaseAgentAStock` or `BaseAgentAStock_Hour`, the `market` parameter is automatically set to `"cn"` and doesn't need to be specified manually.
#### ๐
Cryptocurrency Configuration Example (Using BaseAgentCrypto)
```json
{
"agent_type": "BaseAgentCrypto", // Cryptocurrency specific agent
"market": "crypto", // Market type: "crypto" for cryptocurrencies
"date_range": {
"init_date": "2025-10-20", // Backtest start date
"end_date": "2025-10-31" // Backtest end date
},
"models": [
{
"name": "claude-3.7-sonnet",
"basemodel": "anthropic/claude-3.7-sonnet",
"signature": "claude-3.7-sonnet",
"enabled": true
}
],
"agent_config": {
"initial_cash": 50000.0 // Initial capital: 50,000 USDT
},
"log_config": {
"log_path": "./data/agent_data_crypto" // crypto daily data path
}
}
```
> ๐ก **Tip**: `BaseAgentCrypto` will use the price at UTC 00:00 as the buy/sell price. The market should be set to `"crypto"`.
### ๐ Start Web Interface
```bash
cd docs
python3 -m http.server 8000
# Visit http://localhost:8000
```
## ๐ Performance Analysis
### ๐ Competition Rules
| Rule Item | US Stocks | A-Shares (China) | Cryptocurrencies |
|-----------|-----------|------------------|------------------|
| **๐ฐ Initial Capital** | $10,000 | ยฅ100,000 | 50,000 USDT |
| **๐ Trading Targets** | NASDAQ 100 | SSE 50 | BITWISE10 Top Cryptocurrencies |
| **๐ Market** | US Stock Market | China A-Share Market | Global Crypto Market |
| **โฐ Trading Hours** | Weekdays | Weekdays | Entire Week |
| **๐ฒ Price Benchmark** | Opening Price | Opening Price | Opening Price |
| **๐ Recording Method** | JSONL Format | JSONL Format | JSONL Format |
## โ๏ธ Configuration Guide
### ๐ Configuration File Structure
```json
{
"agent_type": "BaseAgent",
"market": "us",
"date_range": {
"init_date": "2025-10-01",
"end_date": "2025-10-30"
},
"models": [
{
"name": "claude-3.7-sonnet",
"basemodel": "anthropic/claude-3.7-sonnet",
"signature": "claude-3.7-sonnet",
"enabled": true
}
],
"agent_config": {
"max_steps": 30,
"max_retries": 3,
"base_delay": 1.0,
"initial_cash": 10000.0
},
"log_config": {
"log_path": "./data/agent_data"
}
}
```
### ๐ง Configuration Parameters
| Parameter | Description | Options | Default Value |
|-----------|-------------|---------|---------------|
| `agent_type` | AI agent type | "BaseAgent" (generic)
"BaseAgentAStock" (A-share specific) | "BaseAgent" |
| `market` | Market type | "us" (US stocks)
"cn" (A-shares)
"crypto" (Cryptocurrency)
Note: Auto-set to "cn" when using BaseAgentAStock, "crypto" when using BaseAgentCrypto | "us" |
| `max_steps` | Maximum reasoning steps | Positive integer | 30 |
| `max_retries` | Maximum retry attempts | Positive integer | 3 |
| `base_delay` | Operation delay (seconds) | Float | 1.0 |
| `initial_cash` | Initial capital | Float | $10,000 (US)
ยฅ100,000 (A-shares)
50,000-USDT (Cryptocurrency) |
#### ๐ Agent Type Details
| Agent Type | Applicable Markets | Trading Frequency | Features |
|-----------|-------------------|------------------|----------|
| **BaseAgent** | US stocks | Daily | โข Generic trading agent
โข Switch markets via `market` parameter
โข Flexible stock pool configuration |
| **BaseAgent_Hour** | US stocks | Hourly | โข US stocks hourly trading
โข Fine-grained trading timing control
โข Supports intraday trading decisions |
| **BaseAgentAStock** | A-shares | Daily | โข Optimized for A-share daily trading
โข Built-in A-share trading rules (100-share lots, T+1)
โข Default SSE 50 stock pool
โข Chinese Yuan pricing |
| **BaseAgentAStock_Hour** | A-shares | Hourly | โข A-share hourly trading (10:30/11:30/14:00/15:00)
โข Supports 4 intraday time points
โข Inherits all A-share trading rules
โข Data source: merged_hourly.jsonl |
| **BaseAgentCrypto** | Cryptocurrencies | Daily | โข Optimized for cryptocurrencies
โข Default BITWISE10 index pool
โข USDT pricing
โข Supports entire week trading |
### ๐ Data Format
#### ๐ฐ Position Records (position.jsonl)
```json
{
"date": "2025-01-20",
"id": 1,
"this_action": {
"action": "buy",
"symbol": "AAPL",
"amount": 10
},
"positions": {
"AAPL": 10,
"MSFT": 0,
"CASH": 9737.6
}
}
```
#### ๐ Price Data (merged.jsonl)
```json
{
"Meta Data": {
"2. Symbol": "AAPL",
"3. Last Refreshed": "2025-01-20"
},
"Time Series (Daily)": {
"2025-01-20": {
"1. buy price": "255.8850",
"2. high": "264.3750",
"3. low": "255.6300",
"4. sell price": "262.2400",
"5. volume": "90483029"
}
}
}
```
### ๐ File Structure
```
data/agent_data/
โโโ claude-3.7-sonnet/
โ โโโ position/
โ โ โโโ position.jsonl # ๐ Position records
โ โโโ log/
โ โโโ 2025-01-20/
โ โโโ log.jsonl # ๐ Trading logs
โโโ gpt-4o/
โ โโโ ...
โโโ qwen3-max/
โโโ ...
```
## ๐ Third-Party Strategy Integration
AI-Trader Bench adopts a modular design, supporting easy integration of third-party strategies and custom AI agents.
### ๐ ๏ธ Integration Methods
#### 1. Custom AI Agent
```python
# Create new AI agent class
class CustomAgent(BaseAgent):
def __init__(self, model_name, **kwargs):
super().__init__(model_name, **kwargs)
# Add custom logic
```
#### 2. Register New Agent
```python
# Register in main.py
AGENT_REGISTRY = {
"BaseAgent": {
"module": "agent.base_agent.base_agent",
"class": "BaseAgent"
},
"BaseAgentAStock": {
"module": "agent.base_agent_astock.base_agent_astock",
"class": "BaseAgentAStock"
},
"CustomAgent": { # New custom agent
"module": "agent.custom.custom_agent",
"class": "CustomAgent"
},
}
```
#### 3. Configuration File Settings
```json
{
"agent_type": "CustomAgent",
"models": [
{
"name": "your-custom-model",
"basemodel": "your/model/path",
"signature": "custom-signature",
"enabled": true
}
]
}
```
### ๐ง Extending Toolchain
#### Adding Custom Tools
```python
# Create new MCP tool
@mcp.tools()
class CustomTool:
def __init__(self):
self.name = "custom_tool"
def execute(self, params):
# Implement custom tool logic
return result
```
## ๐ Roadmap
### ๐ Future Plans
- [x] **๐จ๐ณ A-Share Support** - โ
SSE 50 Index data integration completed
- [x] **โฟ Cryptocurrency** - โ
BITWISE10 digital currency trading support completed
- [ ] **๐ Post-Market Statistics** - Automatic profit analysis
- [ ] **๐ Strategy Marketplace** - Add third-party strategy sharing platform
- [ ] **๐จ Cool Frontend Interface** - Modern web dashboard
- [ ] **๐ More Strategies** - Technical analysis, quantitative strategies
- [ ] **โฐ Advanced Replay** - Support minute-level time precision and real-time replay
- [ ] **๐ Smart Filtering** - More precise future information detection and filtering
## ๐ Support & Community
- **๐ฌ Discussions**: [GitHub Discussions](https://github.com/HKUDS/AI-Trader/discussions)
- **๐ Issues**: [GitHub Issues](https://github.com/HKUDS/AI-Trader/issues)
## ๐ License
This project is licensed under the [MIT License](LICENSE).
## ๐ Acknowledgments
Thanks to the following open source projects and services:
- [LangChain](https://github.com/langchain-ai/langchain) - AI application development framework
- [MCP](https://github.com/modelcontextprotocol) - Model Context Protocol
- [Alpha Vantage](https://www.alphavantage.co/) - US stock financial data API
- [Tushare](https://tushare.pro/) - China A-share market data API
- [efinance](https://github.com/Micro-sheep/efinance) - A-share hourly data acquisition
- [Jina AI](https://jina.ai/) - Information search service
## ๐ฅ Administrator
## ๐ค Contribution
We thank all our contributors for their valuable contributions.
## Disclaimer
The materials provided by the AI-Trader project are for research purposes only and do not constitute any investment advice. Investors should seek independent professional advice before making any investment decisions. Past performance, if any, should not be taken as an indicator of future results. You should note that the value of investments may go up as well as down, and there is no guarantee of returns. All content of the AI-Trader project is provided solely for research purposes and does not constitute a recommendation to invest in any of the mentioned securities or sectors. Investing involves risks. Please seek professional advice if needed.
---
**๐ If this project helps you, please give us a Star!**
[](https://github.com/HKUDS/AI-Trader)
[](https://github.com/HKUDS/AI-Trader)
**๐ค Experience AI's full potential in financial markets through complete autonomous decision-making!**
**๐ ๏ธ Pure tool-driven execution with zero human interventionโa genuine AI trading arena!** ๐
---
## โญ Star History
*Community Growth Trajectory*
---
โค๏ธ Thanks for visiting โจ AI-Trader!
