AI-Trader: A Hard-Core Experimental Platform That Ends the 'Black Magic' Era of AI-Powered Stock Trading

{
  "repoFullName": "HKUDS/AI-Trader",
  "repoUrl": "https://github.com/HKUDS/AI-Trader",
  "repoName": "AI-Trader",
  "language": "python",
  "stars": 11286,
  "analysisContent": "Hello everyone, I'm Zhou Xiaoma — a battle-tested Java veteran who’s been tortured by Spring Boot auto-configuration until 3 a.m., surviving on coffee, and also a quiet AI enthusiast secretly using LangChain to build quantitative strategies. Today, we won’t talk about JVM tuning or Spring Cloud Gateway circuit breaker configs. Let’s try something fresh: **AI-Trader** — an AI trading arena where GPT, Claude, and Qwen go head-to-head in real markets: NASDAQ, SSE 50, and even Bitcoin.\n\nHonestly, when I first saw the project name, my hand instinctively reached for my wallet (fearing a rug pull), then clicked the live leaderboard link in the README (https://ai4trade.ai) — and there it was: several AI models actively buying and selling AAPL, Kweichow Moutai, and BTC, complete with full reasoning trace display… In that moment, my Americano suddenly lost its charm. This isn’t just another open-source project — it’s Wall Street’s version of *Squid Game*!\n\nLet me cut to the chase: **This is not a toy, nor a demo — it’s a production-grade, architecturally rigorous, engineering-solid, and boundary-clear AI Agent experimental platform.** It doesn’t promise ‘guaranteed profits’ or sell ‘fully automated wealth’. Instead, it tells you plainly: ‘We’ve built a擂台 (a martial arts arena), five AI contestants enter, rules are transparent, data is reproducible, and winners are decided by real money.’ That restraint — that refusal to overhype — earned instant respect from this old-timer who’s seen too many PPT architecture slides.\n\nSo what problem does it actually solve? In one sentence: **It ends the ‘black magic’ era of ‘AI stock trading’ and brings LLM-powered trading back onto the track of scientific validation.** Too many past projects were either local backtesting + manual hyperparameter tuning Frankenstein monsters, or API-calling + hard-coded strategy script collections. AI-Trader delivers three decisive moves:\n\nFirst, the **Historical Replay architecture** completely seals off the ‘peeking into the future’ loophole. Every AI can only access data up to the current timestamp — news, prices, earnings reports — all filtered by their *actual* publication time. That anti-look-ahead design in the README isn’t decorative — it’s enforced via triple safeguards: `get_daily_price_tushare.py` + `merge_jsonl_hourly.py` + explicit timestamp validation. It’s like giving each AI its own ‘time sandbox’ — no matter how smart, it can’t time-travel.\n\nSecond, the **MCP (Model Context Protocol) toolchain** physically isolates ‘decision-making’ from ‘execution’. You won’t write `if price > 200: buy('AAPL')` in your prompt. Instead, the AI says ‘I want to buy Apple stock’, and `tool_trade.py` automatically calls `buy()` or `buy_crypto()` based on market context — respecting real-world rules like T+1 (A-shares), T+0 (U.S. equities / crypto), and minimum lot sizes (e.g., 100 shares). Brilliant — it preserves the LLM’s high-level semantic understanding while using the tool layer to enforce regulatory and operational compliance — essentially strapping a financial-industry seatbelt onto the large language model.\n\nThird, **modular Agent design segmented by market, granularity, and role**. U.S. equities use `BaseAgent`, A-shares use `BaseAgentAStock_Hour` (with four fixed intraday trading windows hardcoded: 10:30, 11:30, 14:00, and 15:00), and crypto uses `BaseAgentCrypto`. Each Agent directory ships with its own data loader, prompt template, and risk-control logic. This isn’t a ‘one-size-fits-all’ lazy solution — it’s like building cars: chassis, engine, infotainment — all custom-engineered per赛道 (racing category). I browsed the source structure — under `data/A_stock/` alone, you’ll find dual-source ingestion (Tushare + Alpha Vantage), daily/hourly OHLC merging, and pre-loaded SSE 50 weight CSV files… The attention to detail is hair-raising. But it’s precisely these ‘inconveniences’ that uphold the four words: *fair competition*.\n\nNow let’s look at the code — this is where it gets hardcore. Installation? One `pip` command — but the real insight lies in its startup philosophy:\n\n```bash\n# 1. Clone\ngit clone https://github.com/HKUDS/AI-Trader.git\ncd AI-Trader\n\n# 2. Install dependencies (note: not monolithic — install only what you need)\npip install -r requirements.txt\n\n# 3. Configure environment variables (critical!)\ncp .env.example .env\n# Insert keys for OpenAI, Alpha Vantage, Jina, and Tushare\n```\n\nSee that? It won’t apply for your API keys for you, nor wrap them in a black box. You must register yourself at Alpha Vantage to get a key, and sign up at Tushare for a token — **it assumes you’re a competent developer, not a point-and-click investor.** I love that attitude.\n\nNext, the most critical ‘how to run it’ flow:\n\n```bash\n# US market one-click triad (data → service → trade)\nbash scripts/main_step1.sh  # Fetch NASDAQ-100 daily OHLC data\nbash scripts/main_step2.sh  # Launch MCP services (price/search/trade/math on separate ports)\nbash scripts/main_step3.sh  # Launch Claude 3.7 Sonnet and let it decide what to buy\n```\n\nAnd the true hallmark of thoughtful design? Its configuration files. Not YAML. Not `.properties`. But **JSON-driven ‘tournament rulebooks’**:\n\n```json\n{\n  \"agent_type\": \"BaseAgentAStock_Hour\",\n  \"date_range\": {\n    \"init_date\": \"2025-10-09 10:30:00\",\n    \"end_date\": \"2025-10-31 15:00:00\"\n  },\n  \"models\": [{\n    \"name\": \"claude-3.7-sonnet\",\n    \"basemodel\": \"anthropic/claude-3.7-sonnet\",\n    \"signature\": \"claude-3.7-sonnet-astock-hour\",\n    \"enabled\": true\n  }],\n  \"agent_config\": {\n    \"initial_cash\": 100000.0\n  }\n}\n```\n\nNo magic constants. No hidden toggles. `init_date` is precise to the minute. `agent_type` maps directly to the concrete class name. `initial_cash` explicitly states the unit is RMB. It turns ‘how to run an experiment’ into a contract any programmer can read at a glance.\n\nAs a Java veteran, I couldn’t resist comparing it to the Spring ecosystem: If Spring is an enterprise-grade OS, AI-Trader is a race-engine tuned specifically for AI trading — no Hibernate’s elegant abstractions, but `tool_get_price_local.py` nails symbol prefix routing (SH/SZ/BTC-USD); no Spring Security’s complex auth, but `start_mcp_services.py` enforces hard-coded HTTP port isolation (8000 = math, 8001 = search, 8002 = trade…). It doesn’t chase universality — only speed, precision, and stability *on its chosen track*.\n\nOf course, there are pitfalls. Like that line in the README: ‘To maintain a well-managed repository, we no longer upload runtime data to the repo’ — meaning don’t expect to see trade logs in Git; you’ll need Hugging Face or https://ai4trade.ai instead. Also, `.env` requires *four* API keys — miss one, and `start_mcp_services.py` halts. And A-share hourly trading supports only those four fixed time points — want intra-day T+0 high-frequency? You’ll need to modify `get_trading_times()` in `base_agent_astock_hour.py`.\n\nWorth diving deep? My answer is: **If you work in AI engineering, Agent development, or quantitative infrastructure — absolutely yes, you must dig in.** It packs LLMs, Tool Calling, Replay Systems, and Multi-Market adaptation into a single, runnable, debuggable, and contributable Python project. More effective than reading ten arXiv papers.\n\nOne last heartfelt note: This project reminded me of the first time I saw Spring Boot’s `@SpringBootApplication` — not because it’s flashy, but because its minimal entry point wraps an entire industrial-grade stack in disciplined rigor. AI-Trader does the same. It doesn’t shout ‘disrupt finance’ — yet quietly establishes the lab standard for AI trading. It doesn’t promise ‘100% annualized returns’ — yet gives everyone a ruler to measure AI’s true performance in real markets.\n\nSo don’t rush to copy-paste and run strategies. First, open https://ai4trade.ai and watch whether Claude sold Kweichow Moutai *again* today — that’s the most authentic README.\n\n(P.S. I’ve already forked it — currently adding a SOLANA pool to `BaseAgentCrypto`… PRs welcome! But don’t ask me why Solana — if you do, the answer is: ‘Because its RPC response is faster than my boss’s messages.’)", "codeExamples": [{"type": "installation", "description": "Installation", "code": "git clone https://github.com/HKUDS/AI-Trader.git\ncd AI-Trader\npip install -r requirements.txt\ncp .env.example .env\n# Edit .env to fill OPENAI_API_KEY, ALPHAADVANTAGE_API_KEY, JINA_API_KEY, TUSHARE_TOKEN"}, {"type": "quickstart", "description": "Quick Start", "code": "bash scripts/main_step1.sh  # Prepare data\nbash scripts/main_step2.sh  # Launch MCP services\nbash scripts/main_step3.sh  # Run AI trading agent\n# Or run directly:\npython main.py configs/default_config.json"}, {"type": "advanced", "description": "Advanced Usage", "code": "{\n  \"agent_type\": \"BaseAgentAStock_Hour\",\n  \"date_range\": {\n    \"init_date\": \"2025-10-09 10:30:00\",\n    \"end_date\": \"2025-10-31 15:00:00\"\n  },\n  \"models\": [{\n    \"name\": \"claude-3.7-sonnet\",\n    \"basemodel\": \"anthropic/claude-3.7-sonnet\",\n    \"signature\": \"claude-3.7-sonnet-astock-hour\",\n    \"enabled\": true\n  }],\n  \"agent_config\": {\n    \"initial_cash\": 100000.0\n  }\n}"}], "keyFeatures": ["Historical Replay architecture (prevents future-data leakage)", "MCP toolchain-driven fully autonomous trading", "Modular Agent design segmented by market / granularity / role"], "techStack": ["Python 3.10+", "LangChain", "MCP (Model Context Protocol)", "Alpha Vantage/Tushare/Jina AI"], "suggestedTags": "AI trading,quantitative investment,LLM Agent,historical backtesting,MCP"}}