README.md

---
license: mit
library_name: ml-trader
tags:
- trading
- machine-learning
- xauusd
- gold
- mt5
- metatrader5
- python
- rust
---

# ML-3m-trader: XAUUSDc 3-Minute Timeframe ML Trading System

An end-to-end proprietary machine learning pipeline for trading XAUUSDc (Gold) on the 3-minute timeframe. This system utilizes a high-performance architecture bridging Python for data processing and model orchestration with Rust for high-frequency execution components.

[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
[![Python Count](https://img.shields.io/badge/Python-9_files-blue.svg)](https://www.python.org/)
[![Rust Count](https://img.shields.io/badge/Rust-10_files-orange.svg)](https://www.rust-lang.org/)
[![Total Size](https://img.shields.io/badge/Repo_Size-9462_KB-green.svg)](#techstack)
[![Author](https://img.shields.io/badge/Author-Rembrant_Oyangoren_Albeos-blueviolet.svg)](https://huggingface.co/algorembrant)

## Project Overview

The ML-3m-trader repository provides a robust framework for automated trading, featuring a hybrid implementation designed for speed and reliability. The core logic involves sophisticated feature engineering and a classification-based approach to market decision-making. Read paper at [SSRN](https://ssrn.com/abstract=6143486) for brigde system framework.

> [!NOTE]
> **Confidentiality Notice**: The specific machine learning algorithms and proprietary trading strategies utilized in this system are currently private. The documentation focuses on infrastructure and architectural workflows.

## Key Features

- **Multi-Language Architecture**: Seamless integration between Python processing and Rust execution.
- **Data Acquisition**: Automated 3-minute OHLCV data fetching.
- **Proprietary Labeling**: Advanced market state labeling engine with built-in risk-reward and spread filtering.
- **Vectorized Backtesting**: High-speed, realistic execution modeling accounting for slippage and spread.
- **Comprehensive Metrics**: Detailed performance analysis including Sharpe, Sortino, and Profit Factor.

## Output Preview

The following visualizations illustrate the system's internal processing and performance evaluation.

### Feature Processing Workflow
![Feature Processing Workflow](feature_process.png)
The diagram above details the data transformation pipeline from raw market indicators to model-ready features.

### Performance Metrics
![Performance Metrics](metrics.png)
The image above showcases the standardized backtesting report generated after a full simulation run.

## System Architecture

```mermaid
graph TD
    A[MetaTrader 5] -->|OHLCV Data| B(Data Fetcher)
    B --> C(Feature Engineering)
    C --> D(Labeling Engine)
    D --> E(ML Pipeline)
    E --> F{Backtesting}
    F -->|Performance| G(Metrics Report)
    F -->|Execution| H[Live Trading Interface]
    
    subgraph "Hybrid Processing"
    C
    D
    E
    end
```

## Project Structure
Detailed overview of all project components:

```text
ML-3m-trader/
├── python_version/          
│   ├── main.py
│   ├── config.py
│   ├── data_fetcher.py
│   ├── diag_mt5.py
│   ├── features.py
│   ├── labeler.py
│   ├── model.py
│   ├── backtester.py
│   ├── metrics.py
│   └── README.md
├── rust_ml_trader/         
│   ├── src/
│   │   ├── main.rs
│   │   ├── backtester.rs
│   │   ├── config.rs
│   │   ├── data_fetcher.rs
│   │   ├── features.rs
│   │   ├── labeler.rs
│   │   ├── metrics.rs
│   │   ├── model.rs
│   │   └── types.rs
│   ├── .gitignore
│   ├── Cargo.toml
│   ├── GUIDE.md
│   ├── LICENSE
│   └── README.md
├── SUM3API (local)/        
│   ├── MQL5/
│   │   ├── Experts/
│   │   │   └── ZmqPublisher.mq5
│   │   ├── Include/
│   │   └── Libraries/
│   └── Rustmt5-chart/
├── feature_process.png
├── LICENSE
├── metrics.png
├── requirements.txt
├── STACKS.md               
└── sractch.md
```

## Usage

For detailed technical documentation, please refer to [STACKS.md](STACKS.md).

### Quick Start (Python)

1. Install dependencies:
   ```bash
   pip install -r requirements.txt
   ```
2. Run the full pipeline:
   ```bash
   python python_version/main.py run
   ```

### Quick Start (Rust)

1. Build the project:
   ```bash
   cd rust_ml_trader
   cargo build --release
   ```
2. Execute backtest:
   ```bash
   cargo run --release
   ```

## Citation

If you use this repository in your research or project, please cite it as follows:

```bibtex
@misc{albeos2026ml3mtrader,
  author = {Rembrant Oyangoren Albeos},
  title = {ML-3m-trader: XAUUSDc 3-Minute Timeframe ML Trading System},
  year = {2026},
  publisher = {Hugging Face},
  journal = {Hugging Face Repository},
  howpublished = {\url{https://huggingface.co/algorembrant/ML-3m-trader}}
}
```