📈 XAU/USD Direction Classifier

End-to-end Machine Learning project for predicting the next-hour direction of XAU/USD (Gold vs US Dollar). The API accepts raw OHLC market candles, performs feature engineering internally, and serves predictions through a FastAPI inference service.

---

Project Overview

Financial markets are highly dynamic and difficult to predict. This project develops an end-to-end machine learning pipeline that predicts the next-hour movement of XAU/USD using historical price action and engineered technical features.

The project covers the complete machine learning workflow:

• Data preprocessing
• Exploratory Data Analysis (EDA)
• Feature Engineering
• Model Training
• Model Evaluation
• Model Analysis
• FastAPI Deployment
• Automated API Testing

Rather than focusing only on model accuracy, the project emphasizes building a production-style machine learning workflow that is modular, reproducible, and deployable.

---

Production-Oriented Design

Unlike many ML demonstrations that require clients to compute engineered features before inference, this project exposes a production-oriented API.

Clients provide historical OHLC market candles, while the API performs feature engineering internally before generating predictions. This keeps the client interface simple, reduces implementation errors, and mirrors real-world machine learning deployment practices.

---

Project Workflow

Historical XAU/USD Data
          │
          ▼
Data Cleaning & Processing
          │
          ▼
Feature Engineering
(26 Technical Features)
          │
          ▼
Chronological Train/Test Split
          │
          ▼
Model Training
(Logistic Regression & Gradient Boosting)
          │
          ▼
Model Evaluation
          │
          ▼
FastAPI Deployment
          │
          ▼
Raw OHLC Candles
          │
          ▼
API Feature Engineering
          │
          ▼
Prediction

---

Dataset

• Asset: XAU/USD (Gold vs US Dollar)
• Frequency: 1 Hour
• Historical Market Data
• Time-series forecasting setup
• Chronological train-test split to prevent data leakage

---

Feature Engineering

The final model uses 26 engineered features, including:

The FastAPI service computes these features internally from raw OHLC market candles, allowing API clients to send only historical market data rather than pre-engineered features.

Price Returns

• return_1h
• return_3h
• return_6h
• return_12h
• return_24h

Momentum

• momentum_3h
• momentum_6h
• momentum_12h
• momentum_24h

Candle Features

• body_size
• range_size
• upper_wick_ratio
• lower_wick_ratio
• up_candle_ratio_12h

Technical Indicators

• RSI (14)
• ATR Ratio
• SMA 6 Ratio
• SMA 12 Ratio
• SMA 24 Ratio

Volatility Features

• volatility_6h
• volatility_12h
• volatility_24h

Trend Features

• trend_strength_24h

Time Features

• hour
• day_of_week

Price Position

• close_position

---

Machine Learning Models

The following models were evaluated:

• Logistic Regression
• Gradient Boosting Classifier

The final deployed model is:

Logistic Regression

Selected due to stable performance, simplicity, interpretability, and consistent generalization on the chronological test set.

---

Model Performance

Metric	Score
Accuracy	0.5079
Precision	0.5251
Recall	0.4392
F1 Score	0.4784

---

Key Findings

• Performance is slightly above random classification.
• Financial market direction remains inherently difficult to predict.
• Prediction confidence is generally concentrated near the decision threshold.
• The model demonstrates stable behaviour across the chronological test period.

---

FastAPI Deployment

The trained model is deployed as a REST API using FastAPI.

Available Endpoints

Root

GET /

Returns API status.

---

Health Check

GET /health

Returns:

• API status
• Model loading status
• Number of engineered features

---

Prediction

POST /predict

Accepts approximately 30 historical OHLC candles.

The API performs feature engineering internally and predicts the direction of the next hourly candle.

Example response:

{
  "predicted_class": 1,
  "predicted_direction": "UP",
  "confidence": 0.5626
}

---

API Documentation

Interactive Swagger documentation is automatically available at:

http://127.0.0.1:8000/docs

---

Automated Testing

Automated tests verify:

• Root endpoint
• Health endpoint
• Prediction endpoint using raw OHLC candles
• Feature engineering output
• Feature completeness

All API tests pass successfully.

---

Project Structure

📦 xauusd-direction-classifier
│
├── 📂 api
│   ├── __init__.py
│   └── main.py
│
├── 📂 data
│   ├── raw
│   └── processed
├── 📂 images
├── 📂 models
│
├── 📂 notebooks
│
├── 📂 src
│
├── 📂 tests
│
├── README.md
├── requirements.txt
└── .gitignore

---

Installation

Clone the repository

git clone https://github.com/yourusername/xauusd-direction-classifier.git

cd xauusd-direction-classifier

Create virtual environment

python -m venv .venv

Activate environment

Windows

.venv\Scripts\activate

Install dependencies

pip install -r requirements.txt

---

Run the API

python -m uvicorn api.main:app --reload

Open

http://127.0.0.1:8000/docs

---

Run Tests

python -m pytest

---

🚀 Project Banner

---

📊 Exploratory Data Analysis

---

📈 Model Analysis

---

🌐 FastAPI Swagger Documentation

---

🔮 Prediction Example

🛠 Tech Stack

Category	Technologies
Language	Python
ML	Scikit-Learn
API	FastAPI
Model Serving	Uvicorn
Testing	Pytest
Visualization	Matplotlib
Data	Pandas, NumPy

---

Future Improvements

🚀 Future Work

• Hyperparameter Optimization
• XGBoost & LightGBM
• LSTM-based Forecasting
• Transformer Models
• Live Market Prediction
• Docker Deployment
• CI/CD Pipeline
• Cloud Deployment (AWS)
• Real-time Dashboard
• Probability Calibration
• Feature Importance Analysis

---

Limitations

• Financial markets exhibit significant randomness and non-stationarity.
• The model should not be interpreted as a trading strategy.
• Prediction performance remains only slightly above random classification.
• Additional market indicators and macroeconomic features could improve performance.

---

License

This project is provided for educational and research purposes.