AI-XAUUSD-Trading

AI-XAUUSD-Trading

Trades gold against the US dollar with three reinforcement learning models, market regime detection and risk rules. A research project for people who study trading algorithms, not financial advice.

Made by JonusNattapong on Hugging Face. These notes are Mindket's, written from its model page and model card; the model's own files and license are on Hugging Face.

About

What it is: This project is a trading system for XAUUSD, gold priced in US dollars. It combines three reinforcement learning models, PPO, TD3 and SAC, in an ensemble. It adds market regime detection, position sizing by model confidence, and risk rules such as scaled profit-taking and trailing stops.

Who it suits: It suits students, researchers and developers who want to study reinforcement learning in trading, build on a working example or benchmark their own methods.

Industry | Who uses it | How they use it | Example
Finance research | Quant researchers | Study ensembles of reinforcement learning agents on price data | Compare the ensemble with a single model
Education | Students | Learn how regime detection and risk rules fit together | Read the code that sizes a position by confidence
Software | Algorithm developers | Use the code as a base for a trading system | Swap in your own risk manager
Risk analysis | Risk analysts | Examine adaptive stops and exits | Test trailing stops under different regimes

If you want advice on real trades, you can skip it, because the card says it is not financial advice.

Where to use it:

• Python scripts and notebooks on Windows, macOS or Linux
• Backtesting on your own historical XAUUSD price data
• Research and benchmarking against other trading algorithms

Use case | Who | What they get back
Strategy research | Researchers | A signal and a confidence value for each market state
Position sizing | Developers | A size that scales with model confidence
Benchmarking | Analysts | Metrics to compare against other algorithms

How to set it up: You need Python with pip and a file of historical XAUUSD price data.

• Python and pip
• The libraries stable-baselines3, gymnasium, pandas, numpy, scikit-learn and yfinance
• The project's code from its GitHub repository, plus the three trained model files
• A CSV of market data, which the sample reads

1. Install the Hugging Face client with pip and download the repository with the hf command.
2. Install the Python libraries.
3. Get the project's code from its repository.
4. Place your market data file next to the scripts.

pip install -U huggingface_hub
hf download JonusNattapong/AI-XAUUSD-Trading

# Install dependencies
pip install stable-baselines3 gymnasium pandas numpy scikit-learn yfinance

How to use it: In the card's basic sample you load the three models into the ensemble, detect the market regime from your data, predict a signal with a confidence value and size the position. The card also describes a live trading mode, which places real orders, so validate everything first.

from ensemble_trader import EnsembleTrader
from market_regime_detector import MarketRegimeDetector

# Initialize components
ensemble = EnsembleTrader(model_paths=['ppo_model.zip', 'td3_model.zip', 'sac_model.zip'])
regime_detector = MarketRegimeDetector()

# Load market data
market_data = pd.read_csv('xauusd_data.csv')

# Detect market regime
regime, params = regime_detector.detect_regime(market_data)

# Make trading decision
state = preprocess_market_data(market_data)
signal, confidence = ensemble.predict(state)

# Apply confidence-based sizing
position_size = calculate_position_size(confidence, risk_per_trade=0.02)

Tool | What it does
EnsembleTrader | Combines the three reinforcement learning models into one signal
MarketRegimeDetector | Classifies the market state and returns adaptive parameters
calculate_position_size | Scales the position with the model's confidence
live_trading_interface | Sends real orders in the live mode

Example: You feed in a CSV of gold prices. The script prints the detected regime, a trade signal with a confidence number, and a position size based on a 2% risk per trade. You review these before deciding anything.

For newcomers and experts: Reinforcement learning means a program learns trading rules by trial and reward in a simulated market. The first small thing to try is the basic sample on historical data, with no live trading.

The card describes an ensemble of PPO, TD3 and SAC in a Gym environment, with six market conditions that each use their own parameters. Risk management covers scaled profit-taking, breakeven stops and trailing stops. The author reports backtests over 2015 to 2025, but history does not predict future results.

Market data
Regime detector picks parameters
PPO, TD3 and SAC ensemble
Confidence sets position size
Risk manager handles exits

Good to know: Reported backtest: the author lists a 58.3% win rate, a $49.45 average win and a $106.18 average loss over 2015 to 2025. These are the author's numbers, not verified here.

Title: Reported win rate by market regime, percent
Strong bull: 65.2%
Bull trend: 61.8%
Ranging: 52.1%
High volatility: 48.9%

• Limits: the card says it is not for real trading without thorough validation, that results rest on historical data and that markets carry a risk of loss.
• Live mode: the sample shows a live trading class that takes a capital amount, a borrowing multiple and risk per trade, so it can place real orders.
• License: MIT, as the License line says.
• Cost to run: no API key or paid service is named. Live trading would need your own trading account.
• Data it reaches: market data files you supply, yfinance for price data, and any trading account you connect in live mode.
• Not for: financial advice or unvalidated real trading, as the card states.

On Hugging Face, 13 November 2026

• Task: reinforcement learning
• Downloads in the last 30 days: 0
• Likes: 58
• License: mit
• Languages: en
• Tags: reinforcement-learning, trading, finance, algorithmic-trading, forex, gold, xauusd, ensemble-learning, market-regime, risk-management, model-index

Links

• Model: https://huggingface.co/JonusNattapong/AI-XAUUSD-Trading
• Files: https://huggingface.co/JonusNattapong/AI-XAUUSD-Trading/tree/main

Get the model

Download its files with Hugging Face's command line:

pip install -U huggingface_hub
hf download JonusNattapong/AI-XAUUSD-Trading

Then follow the usage in its model card. Nothing in this kit runs by itself.