XauBot/README.md

XAUBot AI

AI-powered XAUUSD (Gold) trading bot with XGBoost ML, Smart Money Concepts (SMC), and HMM regime detection for MetaTrader 5.

---

Features

Feature	Description
XGBoost ML Model	37-feature model predicting BUY/SELL/HOLD with calibrated confidence
Smart Money Concepts	Order Blocks, Fair Value Gaps, Break of Structure, Change of Character
HMM Regime Detection	3-state Hidden Markov Model classifying trending/ranging/volatile markets
Dynamic Risk Management	ATR-based stop loss, Kelly criterion sizing, daily loss limits
Session-Aware Trading	Optimized for Sydney, London, and New York sessions
Auto-Retraining	Models automatically retrain when market conditions shift
Telegram Alerts	Real-time trade notifications and daily summaries
Web Dashboard	Next.js monitoring interface for live tracking

Architecture

                          ┌─────────────────┐
                          │   MetaTrader 5   │
                          │   (XAUUSD M15)   │
                          └────────┬─────────┘
                                   │ OHLCV
                          ┌────────▼─────────┐
                          │   Data Pipeline   │
                          │  (Polars Engine)  │
                          └────────┬─────────┘
                                   │
                 ┌─────────────────┼─────────────────┐
                 │                 │                  │
        ┌────────▼───────┐ ┌──────▼───────┐ ┌───────▼──────┐
        │  SMC Analyzer   │ │  Feature Eng  │ │ HMM Regime   │
        │  (OB/FVG/BOS)  │ │ (37 features) │ │  Detector    │
        └────────┬───────┘ └──────┬───────┘ └───────┬──────┘
                 │                │                  │
                 └─────────────────┼─────────────────┘
                                   │
                          ┌────────▼─────────┐
                          │  XGBoost Model    │
                          │  (Signal + Conf)  │
                          └────────┬─────────┘
                                   │
                 ┌─────────────────┼─────────────────┐
                 │                 │                  │
        ┌────────▼───────┐ ┌──────▼───────┐ ┌───────▼──────┐
        │  11 Entry       │ │  Risk Engine  │ │  Position    │
        │  Filters        │ │  (ATR + Kelly)│ │  Manager     │
        └────────┬───────┘ └──────┬───────┘ └───────┬──────┘
                 │                │                  │
                 └────────────────┼──────────────────┘
                                  │
                         ┌────────▼─────────┐
                         │  Trade Execution   │
                         │  (MT5 + Logging)   │
                         └───────────────────┘

Project Structure

xaubot-ai/
├── main_live.py              # Main async trading orchestrator
├── train_models.py           # Model training script
├── src/                      # Core modules
│   ├── config.py             #   Trading configuration & capital modes
│   ├── mt5_connector.py      #   MetaTrader 5 connection layer
│   ├── smc_polars.py         #   Smart Money Concepts analyzer
│   ├── ml_model.py           #   XGBoost trading model
│   ├── feature_eng.py        #   Feature engineering (37 features)
│   ├── regime_detector.py    #   HMM market regime detection
│   ├── risk_engine.py        #   Risk calculations & validation
│   ├── smart_risk_manager.py #   Dynamic risk management
│   ├── session_filter.py     #   Session filter (Sydney/London/NY)
│   ├── position_manager.py   #   Open position management
│   ├── dynamic_confidence.py #   Adaptive confidence thresholds
│   ├── auto_trainer.py       #   Auto-retraining pipeline
│   ├── news_agent.py         #   Economic news filtering
│   ├── telegram_notifier.py  #   Telegram alerts
│   ├── trade_logger.py       #   Trade logging to DB
│   └── utils.py              #   Utility functions
├── backtests/                # Backtesting
│   ├── backtest_live_sync.py #   Main backtest (synced with live)
│   └── archive/              #   Historical versions
├── scripts/                  # Utility scripts
│   ├── check_market.py       #   Quick SMC market analysis
│   ├── check_positions.py    #   View open positions
│   ├── check_status.py       #   Account status check
│   ├── close_positions.py    #   Emergency close all
│   ├── modify_tp.py          #   Modify take-profit levels
│   └── get_trade_history.py  #   Pull trade history
├── tests/                    # Tests
├── models/                   # Trained models (.pkl)
├── data/                     # Market data & trade logs
├── docs/                     # Documentation
│   ├── arsitektur-ai/        #   Architecture docs (23 components)
│   └── research/             #   Research & analysis
├── web-dashboard/            # Next.js monitoring dashboard
└── docker/                   # Docker configuration

Backtest Results (Jan 2025 - Feb 2026)

Metric	Value
Total Trades	654
Win Rate	63.9%
Net P/L	$4,189.52
Profit Factor	2.64
Max Drawdown	2.2%
Sharpe Ratio	4.83

Installation

🐳 Docker Deployment (Recommended)

Quick Start:

# 1. Clone the repository
git clone https://github.com/GifariKemal/xaubot-ai.git
cd xaubot-ai

# 2. Configure environment
cp .env.docker.example .env
# Edit .env with your MT5 credentials

# 3. Start all services (Windows)
docker-start.bat

# 3. Start all services (Linux/Mac)
./docker-start.sh

Services will be available at:

• 📊 Dashboard: http://localhost:3000
• 🔌 API: http://localhost:8000
• 📚 API Docs: http://localhost:8000/docs
• 🗄️ Database: localhost:5432

Full Docker documentation: See DOCKER.md

---

🐍 Manual Installation

Prerequisites:

• Python 3.11+
• MetaTrader 5 terminal (Windows)
• PostgreSQL (optional, for trade logging)

Setup:

# Clone the repository
git clone https://github.com/GifariKemal/xaubot-ai.git
cd xaubot-ai

# Install dependencies
pip install -r requirements.txt

# Configure environment
cp .env.example .env
# Edit .env with your MT5 credentials and Telegram token

Configuration

Key settings in .env:

# MetaTrader 5
MT5_LOGIN=your_login
MT5_PASSWORD=your_password
MT5_SERVER=your_server
MT5_PATH=C:/Program Files/MetaTrader 5/terminal64.exe

# Telegram Notifications
TELEGRAM_BOT_TOKEN=your_bot_token
TELEGRAM_CHAT_ID=your_chat_id

# Trading
CAPITAL=5000
SYMBOL=XAUUSD

Run

# Train models first
python train_models.py

# Start the bot
python main_live.py

# Run backtest
python backtests/backtest_live_sync.py --tune

Risk Management

Protection	Details
ATR-Based Stop Loss	Minimum 1.5x ATR distance
Broker-Level SL	Emergency SL set at broker level
Position Sizing	Kelly criterion with capital mode scaling
Daily Loss Limit	5% of capital per day
Total Loss Limit	10% of capital
Position Limit	Max 2 concurrent positions
Time-Based Exit	Max 6 hours per trade
Session Filter	Only trades during active sessions
Spread Filter	Rejects trades during high spread
Cooldown	Minimum time between trades

Tech Stack

• Polars — High-performance data engine (not Pandas)
• XGBoost — Gradient boosted ML model
• hmmlearn — Hidden Markov Model for regime detection
• MetaTrader5 — Broker connection API
• asyncio — Async event loop for low-latency execution
• loguru — Structured logging
• PostgreSQL — Trade database
• Next.js — Web dashboard

Disclaimer

This software is for educational and research purposes only. Trading foreign exchange (Forex) and commodities on margin carries a high level of risk and may not be suitable for all investors. Past performance is not indicative of future results. You could lose some or all of your investment. Use at your own risk.

License

MIT License - Copyright (c) 2025-2026 Gifari Kemal