🤖 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

---

📦 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
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

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

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.