ML-3m-trader

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 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 for pip dependencies

License

MIT License -- Rembrant Oyangoren Albeos, 2026