QuantumBotX

QuantumBotX is a Windows-first trading bot and backtesting platform for MetaTrader 5. The main branch is intentionally kept focused on MT5 so users can install, test, and run the current app without confusion from experimental cross-platform work.

🚧 Development Status: Actively maintained but built in spare time.

New features and fixes land when the developer's schedule allows.

Contributions, ideas, and bug reports are always welcome.

Use this project for education, research, demo trading, and strategy validation. Always test on a demo account before considering any live trading.

Current Scope

• Primary runtime: MetaTrader 5 terminal on Windows.
• Backend: Python and Flask.
• Database: SQLite.
• Frontend: Flask templates, TailwindCSS, and Chart.js.
• Strategy tools: local technical indicator compatibility layer plus pandas.
• Development baseline: Python 3.12 is supported.

Experimental cross-platform work belongs on dedicated development branches, not on main.

Recent Changes

For operational updates, setup-impacting fixes, and repository maintenance notes, see CHANGELOG.md.

Features

• MT5 account connection and symbol validation.
• Live bot management for MT5 instruments.
• Strategy parameter forms and beginner-friendly defaults.
• Historical data download from MT5.
• Realistic backtesting with ATR-based risk management, spread/slippage

modeling, equity curves, drawdown, win rate, and trade history.

• Multiple built-in strategies for forex, gold, indices, and MT5-supported

crypto CFD symbols.

• Dashboard and portfolio views for monitoring bot status and results.
• Indonesian AI mentor features for trade journaling and learning support.
• Holiday and session-aware helpers for safer trading routines.

Platform Support

Supported

• Windows 10/11, 64-bit recommended.
• MetaTrader 5 terminal installed locally.
• Python 3.12 recommended.

Python Version Status

• Recommended and verified: Python 3.12.x (tested with 3.12.10).
• Newer versions such as 3.13 and 3.14 may work, but are currently treated

as compatibility tests, not primary baseline.

Experimental

• Linux with Wine may work for MT5, but it is not the primary support target.
• macOS requires a Windows VM, CrossOver, Wine, or a separate Windows machine.

Not Supported On main

• Cloud/VPS without a local MT5 terminal session.
• Native non-MT5 broker execution.
• Cross-platform broker runtimes.

Quick Start

• Clone the repository:

git clone https://github.com/chrisnov-it/quantumbotx.git
   cd quantumbotx

• Create and activate a virtual environment:

py -3.12 -m venv venv
   .\venv\Scripts\activate

• Install dependencies:

pip install -r requirements.txt

• Install and open MetaTrader 5.

Log in to a demo account first and keep the terminal running while using QuantumBotX.

• Configure .env:

copy .env.example .env

Then fill in:

MT5LOGIN=yourmt5_login
   MT5PASSWORD=yourmt5_password
   MT5SERVER=yourbroker_server
   SECRETKEY=changeme
   DB_NAME=bots.db

• Initialize local database schema (first run):

python init_db.py

• Start the app:

python run.py

Optional MT5 Helper

The project includes an MT5 setup helper:

python installmt5integration.py

Use it to check Python compatibility, MetaTrader5 package availability, MT5 terminal installation, and basic environment setup.

For more detail, see MT5SETUPGUIDE.md.

Data And Backtesting

QuantumBotX can download historical OHLCV data through MT5 and use it for strategy testing. Typical workflows:

• Use the web interface on the backtesting page.
• Run python lab/download_data.py.
• Upload CSV files through the backtesting UI.

Broker Preset Backtests (XM/FBS)

You can run a preset batch backtest tuned for broker environments:

py -3.12 lab/runpresetbacktests.py

Optional:

py -3.12 lab/runpresetbacktests.py --preset xm_demo.json --tail 5000

Preset files are stored in:

• config/presets/xm_demo.json
• config/presets/fbs_demo.json

Results are saved to logs/presetbacktestresults.json.

Supported markets depend on the connected MT5 broker. Common examples include:

• Forex pairs such as EURUSD, GBPUSD, USDJPY.
• Gold symbols such as XAUUSD and broker-specific variants.
• Indices such as US30, US100, US500, DE30, UK100, when available.
• Crypto CFD symbols such as BTCUSD or ETHUSD, when available through MT5.

Strategy Collection (14 Active)

| Difficulty | Strategies | |------------|------------| | 🟢 Beginner | MA Crossover, RSI Crossover, Turtle Breakout | | 🟡 Intermediate | Bollinger Reversion, Bollinger Squeeze, Ichimoku Cloud, Pulse Sync, Index Momentum, QuantumBotX Hybrid, QuantumBotX Crypto | | 🔴 Advanced | Quantum Velocity, Mercy Edge, Dynamic Breakout, Index Breakout Pro |

Strategy availability and behavior are validated by:

python testing/validateallstrategies.py

Testing Policy

Public-safe tests and diagnostics belong in testing/.

Local account-specific scripts, broker diagnostics, recovery scripts, logs, and anything with private account context belong in testing_private/, which is ignored by Git.

Repository Notes

• README.md is the canonical public README.
• ROADMAP.md describes the current MT5-focused direction for main.
• Internal notes such as MEMORY.md, TASKS.md, RETROSPECT.md, and

WALKTHROUGH.md are ignored and should not be committed publicly.

• The app intentionally keeps local .env, database files, logs, and broker

state files out of Git.

Troubleshooting

If MT5 connection fails:

• Make sure MetaTrader 5 is open and logged in.
• Confirm the account, password, and server in .env.
• Check that the symbol exists in Market Watch.
• Try a demo account first.
• Restart MT5 before restarting QuantumBotX.

If dependency installation fails:

• Use Python 3.12.
• Upgrade pip: python -m pip install --upgrade pip.
• Re-run pip install -r requirements.txt.

If you see database errors like no such table: bots:

• Run python init_db.py once in the project root.
• Make sure you run python run.py from the same project folder.

If git pull shows many conflicts after a forced remote update:

• Abort merge: git merge --abort
• Realign to remote main:

git fetch origin && git reset --hard origin/main && git clean -fd

Disclaimer

Trading foreign exchange, CFDs, crypto CFDs, and other leveraged products involves significant risk. This software is provided for educational and research purposes only. The author is not responsible for financial losses, missed trades, broker issues, execution errors, or misuse of the software.

Always validate on a demo account and use conservative risk settings.

License

This project is licensed under the MIT License. See LICENSE.md.

Author

Developed by Chrisnov IT Solutions.