GitHub - HKUDS/AI-Trader: "AI-Trader: Can AI Beat the Market?" Live Trading Bench: https://ai4trade.ai Tech Report Link: https://arxiv.org/abs/2512.10971

🚀 AI-Trader: Can AI Beat the Market?

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

{
  "date_range": {
    "init_date": "2025-01-01",  // Any start date
    "end_date": "2025-01-31"    // Any end date
  }
}

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

# 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

# 🤖 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

# 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

# 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

# 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

# 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

# Start web interface
bash scripts/start_ui.sh
# Visit: http://localhost:8888

# 📈 Get NASDAQ 100 stock data
cd data
python get_daily_price.py

# 🔄 Merge data into unified format
python merge_jsonl.py

# 📈 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

# 📈 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

cd ./agent_tools
python start_mcp_services.py

# 🎯 Run with default configuration
python main.py

# 🎯 Or specify US stock config
python main.py configs/default_config.json

# 🎯 Run A-share trading
python main.py configs/astock_config.json

# 🎯 Run cryptocurrency trading
python main.py configs/default_crypto_config.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
  }
}

{
  "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
  }
}

{
  "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
  }
}

{
  "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
  }
}

cd docs
python3 -m http.server 8000
# Visit http://localhost:8000

{
  "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"
  }
}

{
  "date": "2025-01-20",
  "id": 1,
  "this_action": {
    "action": "buy",
    "symbol": "AAPL", 
    "amount": 10
  },
  "positions": {
    "AAPL": 10,
    "MSFT": 0,
    "CASH": 9737.6
  }
}

{
  "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"
    }
  }
}

data/agent_data/
├── claude-3.7-sonnet/
│   ├── position/
│   │   └── position.jsonl      # 📝 Position records
│   └── log/
│       └── 2025-01-20/
│           └── log.jsonl       # 📊 Trading logs
├── gpt-4o/
│   └── ...
└── qwen3-max/
    └── ...

# Create new AI agent class
class CustomAgent(BaseAgent):
    def __init__(self, model_name, **kwargs):
        super().__init__(model_name, **kwargs)
        # Add custom logic

# 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"
    },
}

{
  "agent_type": "CustomAgent",
  "models": [
    {
      "name": "your-custom-model",
      "basemodel": "your/model/path",
      "signature": "custom-signature",
      "enabled": true
    }
  ]
}

# 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

🌟 If this project helps you, please give us a Star!

🤖 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! 🚀

@article{fan2025ai,
  title={AI-Trader: Benchmarking Autonomous Agents in Real-Time Financial Markets},
  author={Fan, Tianyu and Yang, Yuhao and Jiang, Yangqin and Zhang, Yifei and Chen, Yuxuan and Huang, Chao},
  journal={arXiv preprint arXiv:2512.10971},
  year={2025}
}

❤️ Thanks for visiting ✨ AI-Trader!