File size: 4,505 Bytes
9cb5a00 | 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 | # ML-3m-trader
[](https://www.python.org/)
[](LICENSE)
[](https://lightgbm.readthedocs.io/)
[](https://www.metatrader5.com/)
Machine learning trading system for **XAUUSDc** (Gold) on the **3-minute timeframe**. Uses a LightGBM multi-class classifier to predict trade signals (Buy, Sell, Hold, Do Nothing) with a vectorized backtesting engine that enforces 1:1 risk-reward, realistic slippage, and spread-based trade filtering.
---
## Overview
ML-3m-trader is an end-to-end pipeline that connects to MetaTrader 5 to fetch one year of historical 3-minute OHLCV data, engineers a comprehensive set of technical features, labels each bar by simulating potential trade outcomes, trains a gradient-boosted classifier, and evaluates performance through a walk-forward backtest with full risk management.
---
## Features
- **Data Acquisition**: Direct connection to MetaTrader 5 for live historical data
- **Technical Indicators**: SMA, Double Moving Average (crossover), VROC, Synthetic VIX (realized volatility proxy), Momentum Strength Index, ADX, cyclical time encoding
- **Labeling Engine**: Forward-looking trade simulation with ATR-based stop-loss, 1:1 risk-reward resolution, and spread filtering
- **LightGBM Classifier**: Multi-class (4-class) gradient boosting with balanced class weights, chronological train/test split, and early stopping
- **Backtesting Engine**: Walk-forward execution with position sizing by balance, random slippage (0-2 units), spread filter enforcement, and full trade logging
- **Performance Metrics**: Win rate, average win/loss percentage, Sharpe ratio, Sortino ratio, Calmar ratio, max drawdown, profit factor, expectancy, intraday PnL statistics
---
## Architecture
```
main.py CLI entry point with subcommands
|
+-- data_fetcher.py MetaTrader 5 data download and CSV persistence
+-- features.py Vectorized technical indicator computation
+-- labeler.py Supervised label generation via trade simulation
+-- model.py LightGBM training, prediction, and persistence
+-- backtester.py Walk-forward backtesting with risk management
+-- metrics.py Performance evaluation and report generation
+-- config.py Central configuration constants
```
---
## Quick Start
**1. Set up the environment**
```
python -m venv .venv
.venv\Scripts\activate
pip install -r requirements.txt
```
**2. Fetch data (MT5 must be open and logged in)**
```
python main.py fetch
```
**3. Train the model**
```
python main.py train
```
**4. Run the backtest**
```
python main.py backtest
```
**5. Or run the full pipeline in one command**
```
python main.py run
```
---
## Commands
| Command | Description |
|---------|-------------|
| `python main.py fetch` | Download 1 year of 3-minute bars from MetaTrader 5 |
| `python main.py train` | Compute features, generate labels, train LightGBM model |
| `python main.py backtest` | Walk-forward backtest on held-out test set with metrics |
| `python main.py evaluate` | Re-display the saved performance report |
| `python main.py predict` | Show latest class probabilities |
| `python main.py run` | Full pipeline: fetch, train, backtest |
---
## Configuration
All parameters are centralized in `config.py`. See [GUIDE.md](GUIDE.md) for the complete reference table.
Key defaults:
- **Symbol**: XAUUSDc
- **Timeframe**: 3 minutes
- **Risk per trade**: 2% of balance
- **Risk-reward ratio**: 1:1
- **Slippage**: Random 0-2 units
- **Spread filter**: Skip trades where stop-loss distance is less than spread multiplied by 10
- **Train/test split**: 80/20 chronological
---
## Output
| Path | Content |
|------|---------|
| `data/raw_xauusdc_m3.csv` | Raw OHLCV data |
| `data/featured_data.csv` | Feature-engineered dataset with labels |
| `models/lgbm_model.pkl` | Trained LightGBM model |
| `results/report.txt` | Backtest performance report |
| `results/trades.csv` | Individual trade log |
---
## Requirements
- Python 3.9+
- MetaTrader 5 (Windows only, installed and logged in)
- See [requirements.txt](requirements.txt) for pip dependencies
---
## License
[MIT License](LICENSE) -- Rembrant Oyangoren Albeos, 2026
|