AI Trading Agent

Multi-symbol autonomous trading platform powered by Claude AI agents

Trades GOLD · OILCash · BTCUSD · USDJPY through MetaTrader 5

Features · Screenshots · Architecture · Quick Start · Pages

✨ Highlights

Eight specialist Claude agents collaborating on a virtual trading floor — Orchestrator, Technical, Fundamental, Risk, Reflector, Sentiment, Strategy Optimizer, and Single-Agent fallback. Hard guardrails prevent runaway trades. Real-time UI streams every decision, position, and P&L tick.

📑 Table of Contents

• Features
• Screenshots
• Architecture
• Tech Stack
• Pages Overview
• Quick Start
• Project Structure
• Environment Variables

🚀 Features

📸 Screenshots

Drop PNGs into docs/screenshots/ with the filenames below.

🏠 Dashboard — Live Trading View

📈 Backtest Studio

📜 Trade History & Performance

🧠 AI Insights

⚡ AI Activity Timeline

💰 AI Usage & Cost Monitor

🤖 ML Model Monitoring

🌐 Macro Data

🛡️ Quant Risk Dashboard

🏢 AI Trading Floor — Agent Prompts

🔌 Integration Status

🔔 Notifications Center

⚙️ Settings

🏗 Architecture

┌──────────────────────────────────────────────────────────────────────┐
│  Frontend (Next.js 16, Vercel/Railway)                               │
│  Dashboard · Backtest · History · AI Insights · AI Usage · ML        │
└──────────────────────┬───────────────────────────────────────────────┘
                       │  HTTPS + WebSocket
                       ▼
┌──────────────────────────────────────────────────────────────────────┐
│  Backend (FastAPI, Railway)                                          │
│  ├── Auth Layer (JWT cookie · Passkey WebAuthn ready)                │
│  ├── Secrets Vault (AES-256-GCM · HKDF key derivation)               │
│  ├── Runner Manager (process / Docker sandbox)                       │
│  │   ├── Job Queue (Redis + DB-persisted)                            │
│  │   ├── Heartbeat Monitor (auto-restart)                            │
│  │   └── Agent Entrypoint (asyncio loop)                             │
│  │       ├── MCP Tool Server (14 modules · 40+ tools)                │
│  │       ├── Guardrails (non-bypassable trading limits)              │
│  │       └── Multi-Agent Pipeline                                    │
│  │           ├── Reflector (Haiku)        — past trade review        │
│  │           ├── Technical Analyst (Haiku) — indicators              │
│  │           ├── Fundamental Analyst (Haiku) — sentiment             │
│  │           ├── Risk Analyst (Haiku)     — portfolio risk           │
│  │           ├── Sentiment Analyzer (Haiku) — news scoring           │
│  │           ├── Strategy Optimizer (Haiku) — param tuning           │
│  │           └── Orchestrator (Sonnet)    — final decision           │
│  ├── Strategy Engine (5 strategies + ensemble + MTF + regime)        │
│  ├── ML Models (LightGBM per-symbol · drift detection)               │
│  ├── AI Usage Logger (token + cost per call · 90d retention)         │
│  ├── PostgreSQL 15 + Redis 7 (AOF persistence)                       │
│  └─── HTTP ────► Windows VPS                                         │
│                  └── MT5 Bridge + MetaTrader 5 (XM Global)           │
└──────────────────────────────────────────────────────────────────────┘

🛠 Tech Stack

📄 Pages Overview

⚡ Quick Start

Prerequisites

• Python 3.12+
• Node.js 22+
• Docker (for local PostgreSQL + Redis)
• Windows VPS with MetaTrader 5 (production trading only)

1. Start databases

docker-compose up -d

2. Backend

cd backend
python -m venv .venv
source .venv/bin/activate          # Windows: .venv\Scripts\activate
pip install -r requirements.txt
cp .env.example .env
alembic upgrade head
uvicorn app.main:app --reload --port 8000

3. MT5 Bridge (Windows VPS only)

cd mt5_bridge
pip install -r requirements.txt
cp .env.example .env                # add MT5 credentials
uvicorn main:app --host 0.0.0.0 --port 8001

4. Frontend

cd frontend
npm install
cp .env.example .env.local
npm run dev

5. Run tests

cd backend
python -m pytest tests/ -v --no-cov   # 444 tests

📁 Project Structure

gold-trading-bot/
├── backend/
│   ├── app/
│   │   ├── api/routes/         # 80+ REST endpoints
│   │   ├── ai/                 # Claude client, pricing, usage logger
│   │   ├── bot/                # Trading engine, scheduler, health monitor
│   │   ├── strategy/           # 5 strategies + ensemble + regime
│   │   ├── risk/               # Risk manager, circuit breaker, correlation
│   │   ├── ml/                 # LightGBM trainer, features, drift
│   │   ├── runner/             # Docker sandbox runner system
│   │   ├── db/                 # SQLAlchemy models + 15 migrations
│   │   └── ...
│   ├── alembic/versions/       # DB migrations
│   ├── mcp_server/
│   │   ├── server.py           # FastMCP tool server
│   │   ├── guardrails.py       # Non-bypassable trading limits
│   │   ├── agents/             # 6 specialist agents + orchestrator
│   │   └── tools/              # 14 tool modules
│   └── tests/                  # 444 tests (27 files)
├── frontend/
│   ├── app/                    # Next.js App Router (15 pages, no runners)
│   ├── components/             # UI primitives + layout
│   ├── lib/                    # API client + WebSocket
│   └── public/agent-characters/ # Chibi agent portraits
├── mt5_bridge/                 # MetaTrader 5 HTTP bridge (Windows VPS)
├── agent-character/            # Source character art (PNG)
├── docs/
│   ├── logo/                   # Logo assets
│   └── screenshots/            # README screenshots
├── scripts/backup_db.sh        # Daily pg_dump
└── docker-compose.yml

🔧 Environment Variables

See backend/.env.example and mt5_bridge/.env.example.

📜 License

Private — internal use only.

Built with Claude Code · Deployed on Railway · Trading on MT5