🤖 MT5 AI/ML Trading Bot - Enterprise Edition

Institutional-Grade Algorithmic Trading System for MetaTrader 5

---

🏛️ Executive Summary

The MT5 AI/ML Trading Bot is a production-ready, enterprise-grade automated trading engine specifically optimized for the XAUUSD (Gold) market. It leverages cutting-edge Deep Reinforcement Learning (DRL) and Ensemble Machine Learning to deliver consistent, risk-adjusted returns within the MetaTrader 5 ecosystem.

Built on an architectural foundation that integrates 25+ top-tier quantitative finance repositories, this system provides a unified interface for model training, backtesting, and live execution.

---

🏛️ Technical Credibility & Trust

The MT5 AI/ML Trading Bot is built for institutional-grade reliability. We prioritize transparency, evidence-based development, and clear system boundaries.

• Architecture Quick-Start: 5-minute overview of system components, data flow, and maturity levels.
• System Maturity Map: Transparent status of production vs. experimental subsystems with direct evidence routing.
• Scientific Rigor: Institutional benchmarking framework using Sharpe, Sortino, Wilcoxon P-Values, and statistical outperformance metrics.
• Technical Health Dashboard: Real-time visibility into technical debt, CI status, and process integrity.
• Audit Evidence: Direct routing to verified walk-forward reports, ADRs, and security scorecards.

---

🚀 Core Features

🧠 Advanced Intelligence

• DRL Architectures: PPO (Proximal Policy Optimization), Dreamer V3, and LSTM-based actors.
• Dynamic Ensemble Engine: Adaptive model weighting system that adjusts model influence based on real-time performance (Sharpe/Accuracy), confidence calibration, and market regime context.
• Explainability System: Structured attribution breakdowns for every trade signal, providing institutional-grade transparency into model and risk decisions.
• Dynamic Feature Engineering: 140+ market indicators including multi-timeframe TA-Lib features and macro-sentiment integration.
• Standardized Model Interface: All AI models implement a unified BaseModel interface for seamless integration and ensemble voting.

🛡️ Institutional Risk Management

• Ray Dalio All-Weather Allocation: Scenario-based risk parity across multi-currency pairs.
• 11-Layer Execution Filter: Specialized cascade for entry vetting (ATR, Trend, EMA, Momentum, Session, Drawdown, Model Stability, Performance, Confidence, Signal consistency, and Macro Risk).
• 8-Layer Risk Manager: Centralized authority for account-level safety (Circuit Breakers, Daily Loss, Max Positions, Symbol Allocation, Confidence, R:R, Streak protection, and Model Health).

⚡ Production Infrastructure

• CI/CD Pipeline: Fully automated GitHub Actions for linting, security audits (pip-audit), and unit testing.
• Startup Configuration Validation: Mandatory safety gate that blocks execution if production configuration is invalid, incomplete, or contains insecure placeholders.
• Dockerized Deployment: Multi-stage builds for lightweight, cross-platform cloud deployment.
• Hybrid Connector: Native MT5 SDK support with MetaAPI cloud failover.
• Enterprise Health Monitoring: Integrated Liveness and Readiness probes via FastAPI, with automated checks for MT5 connectivity, database health, model integrity, and disk space.

---

📊 Performance Benchmark

Metric	Target Value	Verification Method
Annualized Return	60% - 90%	Walk-forward Backtest (10Y)
Sharpe Ratio	2.8 - 3.5	Risk-Adjusted Return Analysis
Max Drawdown	< 12%	Dynamic Equity Protection
Profit Factor	2.5+	Gross Profit / Gross Loss

---

🛠️ Technology Stack

• Frameworks: PyTorch, Stable-Baselines3, Gymnasium
• Data: Pandas, NumPy, TA-Lib
• DevOps: Docker, GitHub Actions, Ruff
• Settings: Pydantic Settings V2

Supported Runtime

• Python 3.11 is required for the pinned PyTorch, scientific, and trading dependencies.
• Python 3.14 is not supported by the current dependency set.
• The repository includes a .python-version file for version managers that support it.

---

📦 Project Structure

mt5-ai-xauusd-trader/
├── .github/workflows/    # Automated CI/CD (Quality, Security, Tests)
├── src/                  # Core Package Content
│   ├── core/             # Environment-driven Configuration (Pydantic)
│   ├── models/           # AI/ML Architectures (Ensemble, LSTM, DRL)
│   └── trading/          # MT5 Connectors, Risk Engines & Env
├── tests/                # Comprehensive Unit & Integration Suite
├── main.py               # Unified CLI Entrypoint
├── Dockerfile            # Multi-stage Production Build
└── requirements-ci.txt   # Pinned, CVE-free Dependencies

---

🏁 Quick Start

1. Installation & Verification

git clone https://github.com/triqbit/mt5-ai-xauusd-trader.git
cd mt5-ai-xauusd-trader

# Install dependencies (Python 3.11 is required)
python3.11 -m venv venv
source venv/bin/activate
python -m pip install --upgrade pip setuptools wheel
python -m pip install -r requirements.txt

# [CRITICAL] Verify environment and dependencies
python main.py --doctor

# Run interactive setup wizard (Recommended)
python main.py --setup

# Perform a pre-flight health check (verifies .env and connectivity)
python main.py --check

For Linux or macOS, the bootstrap script performs the same setup and creates a local .env from the template:

python3.11 -m venv venv
source venv/bin/activate
bash scripts/bootstrap.sh

If python3 points to another version, invoke the script from an activated Python 3.11 environment. The bootstrapper stops rather than creating a partially installed environment.

2. Quick Evaluation (No-Config Demo)

You can evaluate the system's analytical and RL capabilities immediately using synthetic data, without requiring MT5 credentials or pre-trained models:

# Run strategy benchmark demo (Synthetic OHLCV)
make demo-synthetic

# Run RL agent evaluation demo (Synthetic environment)
make demo-rl

3. Configuration

The system features an Interactive Setup Wizard. Simply run the bot, and it will offer to guide you through the configuration:

python main.py

Alternatively, create a .env file manually:

MT5_LOGIN=your_account
MT5_PASSWORD=your_password
MT5_SERVER=your_broker_server
MODE=demo

For Docker Compose, create the environment file before starting the service:

cp .env.example .env
docker compose up --build

4. Execution

The CLI is designed to be resilient. Diagnostic commands work even if dependencies are not yet installed:

# Get help and usage examples (always available)
python main.py --help

# Verify environment and dependencies
python main.py --doctor

# Show current sanitized configuration
python main.py --show-config

# Perform a pre-flight health check (connectivity, database, models)
python main.py --check

# Start trading in demo mode (CLI flags override .env)
python main.py --mode demo --symbol XAUUSD --algo ensemble

# Start live trading (requires explicit confirmation)
python main.py --mode live --algo ensemble --confirm-live

---

📜 Documentation Index

Guide	Description
Architecture Quick-Start	Primary technical overview and system maturity map.
Pre-Production Checklist	Mandatory deployment gate checklist for production releases.
DEVELOPMENT_PLAN.md	Technical roadmap and implementation milestones.
ENTERPRISE_STANDARDS.md	Coding standards, CI/CD requirements, and security policies.
DEPLOYMENT_GUIDE.md	Step-by-step instructions for Docker and Cloud deployment.
DATABASE_STANDARDS.md	Schemas for trade logging and performance tracking.
SLO & Reliability Targets	Measurable reliability standards and error budget framework.
Contributing Guide	How to contribute safely and effectively.
Contribution Map	Safe vs. Sensitive zone navigation.
First Contribution	Step-by-step guide for your first PR.
Data Retention Policy	Policies for operational data retention and automated purging.
Disaster Recovery Plan	Procedures for database, log, and operational data recovery.

---

🤝 Contributing

We welcome contributions! To ensure safety in this high-turbulence repository:

1. Start in a Safe Zone: Focus on docs/, tests/, or scripts/.
2. Explore with Synthetic Demos: Run make demo-synthetic to understand system telemetry.
3. Follow the First Real Contribution guide: A step-by-step path to your first PR.
4. Mandatory Rebase: Always run make resync to align your branch with the latest main commit before submitting.

See CONTRIBUTING.md for the full workflow and governance rules.

---

⚖️ License

Distributed under the MIT License. See LICENSE for more information.

---

Disclaimer: Trading involves significant risk. This software is for educational purposes only. The developers assume no liability for financial losses.