# ๐Ÿš€ AI-Trader: Can AI Beat the Market? [![Python](https://img.shields.io/badge/Python-3.8+-blue.svg)](https://python.org) [![License](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE) [![Feishu](https://img.shields.io/badge/๐Ÿ’ฌFeishu-Group-blue?style=flat)](./Communication.md) [![WeChat](https://img.shields.io/badge/WeChat-Group-green?style=flat&logo=wechat)](./Communication.md) **Five AIs battle for NASDAQ 100 supremacy. Zero human input. Pure competition.** ## ๐Ÿ† Current Championship Leaderboard ๐Ÿ† [*click me to check*](https://hkuds.github.io/AI-Trader/)
### **Championship Period: (Last Update 2025/10/24)** | ๐Ÿ† Rank | ๐Ÿค– AI Model | ๐Ÿ“ˆ Total Earnings | |---------|-------------|----------------| | **๐Ÿฅ‡ 1st** | **DeepSeek** | ๐Ÿš€ +10.61% | | ๐Ÿฅˆ 2nd | Claude-3.7 | ๐Ÿ“Š +4.03% | | ๐Ÿฅ‰ 3rd | GPT-5 | ๐Ÿ“Š +3.89% | | 4th | Qwen3-max | ๐Ÿ“Š +2.49% | | Baseline | QQQ | ๐Ÿ“Š +2.30%| | 5th | Gemini-2.5-flash | ๐Ÿ“Š -2.73% | ### ๐Ÿ“Š **Live Performance Dashboard** ![rank](assets/rank.png) *Daily Performance Tracking of AI Models in NASDAQ 100 Trading*
[๐Ÿš€ 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 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 to trade NASDAQ 100 stocks in a controlled environment with real market data and historical replay capabilities. - ๐Ÿ’ฐ **Initial Capital**: $10,000 USD starting balance - ๐Ÿ“ˆ **Trading Universe**: NASDAQ 100 component stocks (top 100 technology stocks) - โฐ **Trading Schedule**: Weekday market hours 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 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/ # ๐Ÿง  AI agent core โ”‚ โ””โ”€โ”€ configs/ # โš™๏ธ Configuration files โ”‚ โ”œโ”€โ”€ ๐Ÿ› ๏ธ MCP Toolchain โ”‚ โ”œโ”€โ”€ agent_tools/ โ”‚ โ”‚ โ”œโ”€โ”€ tool_trade.py # ๐Ÿ’ฐ Trade execution โ”‚ โ”‚ โ”œโ”€โ”€ tool_get_price_local.py # ๐Ÿ“Š Price queries โ”‚ โ”‚ โ”œโ”€โ”€ tool_jina_search.py # ๐Ÿ” Information search โ”‚ โ”‚ โ””โ”€โ”€ tool_math.py # ๐Ÿงฎ Mathematical calculations โ”‚ โ””โ”€โ”€ tools/ # ๐Ÿ”ง Auxiliary tools โ”‚ โ”œโ”€โ”€ ๐Ÿ“Š Data System โ”‚ โ”œโ”€โ”€ data/ โ”‚ โ”‚ โ”œโ”€โ”€ daily_prices_*.json # ๐Ÿ“ˆ Stock price data โ”‚ โ”‚ โ”œโ”€โ”€ merged.jsonl # ๐Ÿ”„ Unified data format โ”‚ โ”‚ โ””โ”€โ”€ agent_data/ # ๐Ÿ“ AI trading records โ”‚ โ””โ”€โ”€ calculate_performance.py # ๐Ÿ“ˆ Performance analysis โ”‚ โ”œโ”€โ”€ ๐ŸŽจ Frontend Interface โ”‚ โ””โ”€โ”€ frontend/ # ๐ŸŒ Web dashboard โ”‚ โ””โ”€โ”€ ๐Ÿ“‹ Configuration & Documentation โ”œโ”€โ”€ configs/ # โš™๏ธ System configuration โ”œโ”€โ”€ prompts/ # ๐Ÿ’ฌ AI prompts โ””โ”€โ”€ calc_perf.sh # ๐Ÿš€ Performance calculation script ``` ### ๐Ÿ”ง Core Components Details #### ๐ŸŽฏ Main Program (`main.py`) - **Multi-Model Concurrency**: Run multiple AI models simultaneously for trading - **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 #### ๐Ÿ› ๏ธ MCP Toolchain | Tool | Function | API | |------|----------|-----| | **Trading Tool** | Buy/sell stocks, position management | `buy()`, `sell()` | | **Price Tool** | Real-time and historical price queries | `get_price_local()` | | **Search Tool** | Market information search | `get_information()` | | **Math Tool** | Financial calculations and analysis | Basic mathematical operations | #### ๐Ÿ“Š Data System - **๐Ÿ“ˆ Price Data**: Complete OHLCV data for NASDAQ 100 component stocks - **๐Ÿ“ Trading Records**: Detailed trading history for each AI model - **๐Ÿ“Š Performance Metrics**: Sharpe ratio, maximum drawdown, annualized returns, etc. - **๐Ÿ”„ Data Synchronization**: Automated data acquisition and update mechanisms ## ๐Ÿš€ Quick Start ### ๐Ÿ“‹ Prerequisites - **Python 3.8+** - **API Keys**: OpenAI, Alpha Vantage, Jina AI ### โšก 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 JINA_API_KEY=your_jina_api_key # โš™๏ธ 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 # ๐Ÿง  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 ``` ## ๐ŸŽฎ Running Guide ### ๐Ÿ“Š Step 1: Data Preparation (`./fresh_data.sh`) ```bash # ๐Ÿ“ˆ Get NASDAQ 100 stock data cd data python get_daily_price.py # ๐Ÿ”„ Merge data into unified format python merge_jsonl.py ``` ### ๐Ÿ› ๏ธ Step 2: Start MCP Services ```bash cd ./agent_tools python start_mcp_services.py ``` ### ๐Ÿš€ Step 3: Start AI Arena ```bash # ๐ŸŽฏ Run main program - let AIs start trading! python main.py # ๐ŸŽฏ Or use custom configuration python main.py configs/my_config.json ``` ### โฐ Time Settings Example #### ๐Ÿ“… Create Custom Time Configuration ```json { "agent_type": "BaseAgent", "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 } ] } ``` ### ๐Ÿ“ˆ Start Web Interface ```bash cd docs python3 -m http.server 8000 # Visit http://localhost:8000 ``` ## ๐Ÿ“ˆ Performance Analysis ### ๐Ÿ† Competition Rules | Rule Item | Setting | Description | |-----------|---------|-------------| | **๐Ÿ’ฐ Initial Capital** | $10,000 | Starting capital for each AI model | | **๐Ÿ“ˆ Trading Targets** | NASDAQ 100 | 100 top tech stocks | | **โฐ Trading Hours** | Weekdays | Monday to Friday | | **๐Ÿ’ฒ Price Benchmark** | Opening Price | Trade using daily opening price | | **๐Ÿ“ Recording Method** | JSONL Format | Complete trading history records | ## โš™๏ธ Configuration Guide ### ๐Ÿ“‹ Configuration File Structure ```json { "agent_type": "BaseAgent", "date_range": { "init_date": "2025-01-01", "end_date": "2025-01-31" }, "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 | Default Value | |-----------|-------------|---------------| | `agent_type` | AI agent type | "BaseAgent" | | `max_steps` | Maximum reasoning steps | 30 | | `max_retries` | Maximum retry attempts | 3 | | `base_delay` | Operation delay (seconds) | 1.0 | | `initial_cash` | Initial capital | $10,000 | ### ๐Ÿ“Š 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" }, "CustomAgent": { # New addition "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 - [ ] **๐Ÿ‡จ๐Ÿ‡ณ A-Share Support** - Extend to Chinese stock market - [ ] **๐Ÿ“Š Post-Market Statistics** - Automatic profit analysis - [ ] **๐Ÿ”Œ Strategy Marketplace** - Add third-party strategy sharing platform - [ ] **๐ŸŽจ Cool Frontend Interface** - Modern web dashboard - [ ] **โ‚ฟ Cryptocurrency** - Support digital currency trading - [ ] **๐Ÿ“ˆ 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 ## ๐Ÿค Contributing Guide We welcome contributions of all kinds! Especially AI trading strategies and agent implementations. ### ๐Ÿง  AI Strategy Contributions - **๐ŸŽฏ Trading Strategies**: Contribute your AI trading strategy implementations - **๐Ÿค– Custom Agents**: Implement new AI agent types - **๐Ÿ“Š Analysis Tools**: Add new market analysis tools - **๐Ÿ” Data Sources**: Integrate new data sources and APIs ### ๐Ÿ› Issue Reporting - Use GitHub Issues to report bugs - Provide detailed reproduction steps - Include system environment information ### ๐Ÿ’ก Feature Suggestions - Propose new feature ideas in Issues - Describe use cases in detail - Discuss implementation approaches ### ๐Ÿ”ง Code Contributions 1. Fork the project 2. Create a feature branch 3. Implement your strategy or feature 4. Add test cases 5. Create a Pull Request ### ๐Ÿ“š Documentation Improvements - Improve README documentation - Add code comments - Write usage tutorials - Contribute strategy documentation ### ๐Ÿ† Strategy Sharing - **๐Ÿ“ˆ Technical Analysis Strategies**: AI strategies based on technical indicators - **๐Ÿ“Š Quantitative Strategies**: Multi-factor models and quantitative analysis - **๐Ÿ” Fundamental Strategies**: Analysis strategies based on financial data - **๐ŸŒ Macro Strategies**: Strategies based on macroeconomic data ## ๐Ÿ“ž Support & Community - **๐Ÿ’ฌ Discussions**: [GitHub Discussions](https://github.com/HKUDS/AI-Trader/discussions) - **๐Ÿ› Issues**: [GitHub Issues](https://github.com/HKUDS/AI-Trader/issues) - **๐Ÿ“ง Contact**: your-email@example.com ## ๐Ÿ“„ 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/) - Financial data API - [Jina AI](https://jina.ai/) - Information search service ---
**๐ŸŒŸ If this project helps you, please give us a Star!** [![GitHub stars](https://img.shields.io/github/stars/HKUDS/AI-Trader?style=social)](https://github.com/HKUDS/AI-Trader) [![GitHub forks](https://img.shields.io/github/forks/HKUDS/AI-Trader?style=social)](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!** ๐Ÿš€

โค๏ธ Thanks for visiting โœจ AI-Trader!

Views