AI-Trader Gives Trading Agents Their Own Platform

Reference: HKUDS/AI-Trader — MIT (README badge; no LICENSE file) · Python

AI-Trader is an agent-native trading platform from HKU's Data Intelligence Lab. Any LLM agent joins by reading a single SKILL.md file, then publishes signals, copies top traders, and competes. A server-side price guard sets every fill, so an agent cannot fabricate its returns. The interesting part is the architecture, not the trading.

Not financial advice. This is an architecture review of an open-source research project, not a recommendation to trade. Trading carries real risk of loss; backtests and paper trading overfit and do not guarantee live results. Any performance language is the project's own. As the U.S. SEC's investor bulletin puts it, "back-tested performance is hypothetical and does not reflect actual performance."¹

What problem is AI-Trader actually solving?

AI-Trader starts from one sentence in its README: "Just like humans have their trading platforms, AI agents need their own."² Brokers, dashboards, and order tickets were all built for human hands and eyes. An autonomous LLM agent has no use for a login screen or a chart — it needs an API, a contract, and an event loop.

The repo's traction says the framing landed: 19,290 stars and 2,928 forks as of June 5, 2026.³ AI-Trader, built by the HKU Data Intelligence Lab (the team behind LightRAG and DeepTutor), supplies the agent-shaped substrate: registration, signals, copy trading, a competition layer, and a research harness that turns the whole thing into a study.

So the engineering question is narrow and concrete. How do you let an arbitrary AI agent — Claude Code, Codex, Cursor, or a custom bot — join a live market in seconds, behave well, and produce numbers you can trust?

How does an agent join with one file?

An agent joins AI-Trader by reading one Markdown file. The onboarding instruction in the README is literally a sentence you paste to your agent: "Read https://ai4trade.ai/SKILL.md and register."⁴ No SDK install, no client library — the SKILL.md is the SDK. The agent reads it, self-registers over HTTP, and gets a token.

That file is a Claude-Code-style skill, and its first job is routing. The main skill states the pattern directly: "Use this main skill as the bootstrap and routing layer."⁵ It handles register, login, and token, then points the agent at smaller child skills only when needed.

flowchart TD
    AGENT[LLM Agent: Claude Code / Codex / Cursor]
    MAIN[ai4trade SKILL.md - bootstrap + routing]
    subgraph CHILD[Specialized skills - fetched on demand]
        CP[copytrade]
        TS[tradesync]
        HB[heartbeat]
        MI[market-intel]
        PM[polymarket]
    end
    API[FastAPI service + Postgres]
    GUARD{{Server-side price guard}}

    AGENT -->|read one file| MAIN
    MAIN -->|register, get token| API
    MAIN -->|route to capability| CHILD
    CHILD --> API
    API --> GUARD

This is progressive disclosure applied to an API. The agent loads a thin bootstrap, not a 2,000-line spec, and pulls detail just-in-time. The skill is strict about it: "Do not infer undocumented endpoints or payloads when a child skill exists."⁶ That single rule turns an LLM's worst habit — confidently inventing an endpoint — into a fetch instruction.

How does an agent stay in the loop?

After registration, an agent does not sit idle waiting for a callback — it polls. The heartbeat skill makes the model explicit: "AI-Trader uses a pull-based polling mechanism for notifications."⁷ Replies, mentions, new followers, and tasks all arrive through heartbeat, on a 30-to-60-second cadence.

The design deliberately demotes WebSockets. The skill notes WebSocket "is available but not guaranteed to deliver all notifications reliably," and warns that an agent that skips heartbeat "will miss important platform interactions and will not behave like a fully participating market agent."⁷ Pull beats push here because an agent's runtime is often ephemeral and stateless between turns — a poll it controls survives restarts better than a socket it must hold open.

# the agent's whole event loop, distilled
while True:
    r = post("/api/claw/agents/heartbeat",
             json={"agent_id": AGENT_ID, "status": "alive"},
             headers={"X-Claw-Token": TOKEN})
    for msg in r.json().get("messages", []):
        handle(msg)        # reply, mention, new follower, accepted answer
    sleep(60)              # 30s min, 5min max

The agent's life is a loop: poll, react, act, repeat. It is the same shape as a game-server tick, rebuilt for an autonomous trader.

How does AI-Trader stop agents from faking returns?

A leaderboard of AI traders is worthless if an agent can post its own fill price. AI-Trader's answer is a server-side price guard, and the repo ships a test that proves it. The server — never the client — decides the price at which a trade books.

The behavior is pinned by test_realtime_trade_price_guard.py. When an agent submits a trade for TSLA with a price of 10, the server ignores it and fetches the authoritative quote of 403.08, books the position at 403.08, and charges cash of 403.08 * 10 * 1.001 — a 0.1% fee baked in.

# the client claims price=10; the server overrides it
with patch("price_fetcher.get_price_from_market", return_value=403.08):
    response = client.post("/api/signals/realtime", json=trade_payload)  # price: 10
assert response.json()["price"] == 403.08              # server quote wins
# cash debited = 403.08 * 10 * 1.001  (price * qty * fee)

The stricter half is the failure path. If the server cannot fetch a quote, it refuses to guess: the trade is rejected with HTTP 400 and the message "Unable to fetch historical price for TSLA," and the agent's signal count, position count, and cash all stay exactly where they were.⁸ No quote, no trade — integrity over availability. That is the small, unglamorous decision that makes an agent leaderboard mean anything.

What turns this into a research instrument?

AI-Trader is not just a sandbox — it is a measurement rig. Its research/ directory exists to turn platform data into "reproducible paper datasets, metrics, statistical tables, and figures for the 4k+ agent competition and cooperation study."⁹ The lab is studying how thousands of agents behave when you change their incentives.

The statistics are not hand-waved. analyze_experiments.py runs A/B tests, difference-in-differences, regression with controls, and heterogeneous treatment effects, then corrects for multiple comparisons with a Benjamini-Hochberg pass and reports bootstrap confidence intervals.¹⁰ The experiment log defines four reward variants — control, competition, cooperation, hybrid — over a frozen cohort, with a dry run completed before any real notification went out.

Exports default to anonymized: agent names are hashed and metadata is redacted for token, email, wallet, password, and auth fields. This is the same instinct behind keeping your own notes on your own device — when the data is sensitive, the safe default is to strip identity before anything leaves the building, a principle we explore in how QuantDinger keeps AI away from live capital.

What I'd steal from AI-Trader

Three ideas travel well beyond trading. First, skill-as-SDK: onboard an agent with one readable file plus a hard rule against inventing endpoints. Second, server-as-source-of-truth: never trust a client number that money or rank depends on. Third, instrument from day one so research is a query, not a rebuild.

Each is portable. The skill-as-SDK pattern beats shipping a client library; the server guard recomputes anything sensitive and rejects when it cannot; and one export layer feeding both product and study means a paper is a query away.

It pairs naturally with the model-side and platform-side stories in this corpus — see Kronos, the foundation model for financial markets and TradeMaster's RL quant platform.

Verdict — worth reading, regardless of trading

AI-Trader is worth studying even if you never place a trade. Treat it as a reference design for agent-native services: a one-file onboarding contract, a pull-based event loop, a server-side integrity guard, and a research harness on the same data.

One caveat for would-be users — the README badge says MIT, but the repo ships no LICENSE file, so confirm terms with the maintainers before you build on it.

Frequently Asked Questions

What is HKUDS AI-Trader?

AI-Trader is an open-source, agent-native trading platform from the HKU Data Intelligence Lab. Instead of a human dashboard, it gives LLM agents an API, a skill contract, and an event loop so they can register, publish signals, copy top traders, and compete — and it doubles as a research rig for studying agent behavior.

How does an AI agent join AI-Trader?

You send your agent one instruction: "Read https://ai4trade.ai/SKILL.md and register."⁴ The agent reads that skill file, self-registers over HTTP, and receives a token. There is no SDK to install — the SKILL.md document itself is the integration layer, and it routes the agent to smaller child skills as needed.

Is AI-Trader open source, and what license is it?

The code is public on GitHub and the README displays an MIT badge. However, as of June 5, 2026, the repository ships no LICENSE file, so the GitHub API reports no detected license.³ Treat it as MIT-by-README-badge only, and confirm the terms with the maintainers before depending on it commercially.

Does AI-Trader trade real money?

The repository is an architecture and research project, and this article is not financial advice. The hosted platform offers simulated paper trading. Any returns, backtests, or paper-trading results overfit and do not guarantee live performance — the SEC notes "back-tested performance is hypothetical and does not reflect actual performance."¹

How does AI-Trader stop agents from faking their returns?

A server-side price guard decides every fill. When an agent submits a trade, the server fetches the authoritative quote, books the position at that price regardless of what the agent sent, and applies a fee. If no server quote is available, the trade is rejected with HTTP 400 and nothing changes — verified by the repo's price-guard test.⁸

What is the AI-Trader heartbeat?

Heartbeat is the agent's primary event loop. The skill states AI-Trader "uses a pull-based polling mechanism for notifications,"⁷ so agents poll every 30 to 60 seconds for replies, mentions, followers, and tasks. WebSockets exist but are not guaranteed to deliver everything, so polling is the reliable path for ephemeral agent runtimes.

Can I learn the architecture without trading anything?

Yes. The repo is the open-source half of the platform: read the skills/ files for the agent contract, service/server for the FastAPI backend, and research/ for the experiment pipeline. The price-guard test alone is a clean lesson in trusting the server over the client.

If your work should stay yours, keep it local and yours by default — mnmnote.com.