Documentation

Complete guide to installing, configuring, and using FxMath Harmony Pro v1.0.

Overview

FxMath Harmony Pro is a professional harmonic pattern scanner and trade management platform for MetaTrader 5. It combines a high-performance Flask backend with a beautiful D3.js frontend to deliver real-time harmonic pattern detection, ML-powered quality scoring, and automated trade management — all accessible through your browser.

Key Capabilities

8 Harmonic Patterns: Bat, Gartley, Butterfly, Crab, Deep Crab, Cypher, Shark, 121 — all fully customizable
Multi-Depth ZigZag: O(n) monotonic stack algorithm computes all depths (5–50) in a single pass
Parallel Scanning: ThreadPoolExecutor scans multiple symbols × timeframes concurrently
ML Quality Scorer: On-the-fly Random Forest classifier with 8 feature dimensions
Adaptive ATR Levels: Volatility-adjusted SL/TP as an alternative to fixed Fibonacci levels
26 REST API Endpoints: Full programmatic control over all features
Telegram Auto-Scanner: Background daemon with chart image alerts

Installation

Windows (Standalone Executable)

Download the latest FxMath_Harmony_Pro.exe from the download section.
Place the file anywhere on your system (no installation required).
Ensure MetaTrader 5 is installed and running on your system.
Double-click the executable — the app opens in your default browser automatically.

Note: The standalone .exe includes Python 3.9, Flask, scikit-learn, pandas, numpy, matplotlib, and all other dependencies. No separate installation needed.

Windows (Python Source)

# 1. Extract the project
cd harmonics_desktop_v2

# 2. Install dependencies
pip install -r requirements.txt

# 3. Launch
python main.py

Quick Start

Launch the app (python main.py or double-click the .exe).
The app opens http://127.0.0.1:xxxxx in your browser automatically.
Click Connect MT5 in the top-right navbar.
Go to Settings → MT5 Terminal Connection and click 🔍 Detect to find your MT5 installation.
If auto-detection fails, enter the path to terminal64.exe manually.
Click Connect MT5 again — the green dot confirms connection.
Tune your symbols and timeframes in Settings.
Click Scan Market to find harmonic patterns.

Tip: The first scan may take a few seconds as the ML model trains. Subsequent scans are instantaneous due to model caching.

Scanning for Patterns

The Scanner tab is your main workspace. Configure which symbols and timeframes to scan, then click Scan Market.

Scan Controls

Control	Description
Scan Market / Predict Patterns	Run a full scan or predict incomplete/emerging patterns
🔍 Symbol Filter	Filter results by symbol name (e.g., `EUR`)
📐 Pattern Filter	Filter by pattern type (Bat, Gartley, etc.)
↕ Direction Filter	Show only BUY or SELL signals
🧠 Min Quality Filter	Only show patterns above an ML confidence threshold

Results Table

Each row shows: symbol, timeframe, pattern name, direction, entry/SL/TP1/TP2/TP3 prices, age, and ML quality score (color-coded: ✅ ≥65%, ⚠️ 40–64%, ❌ <40%). Click View to open the interactive chart.

Chart Viewer

The chart modal displays an interactive D3.js candlestick chart with pattern overlays:

Gapless Candlesticks: Index-based linear scale removes weekend/holiday gaps
Pattern Overlay: X→A→B→C→D lines with translucent harmonic wings (bullish/bearish shading)
Interactive Crosshair: Hover to snap to nearest bar with price/time tooltips
Zoom: Adjustable context window (10–300 bars before point X)
Trade Levels: Entry, SL, TP1/TP2/TP3 lines with price badges
ML Quality Badge: Confidence %, recommended TP, expected R:R, and ATR value displayed inline

ATR / Fib Level Toggle

Click 🧠 ML ATR to switch between standard Fibonacci-based SL/TP levels and volatility-adjusted ATR levels. The ATR levels are computed from ATR(14) at the pattern D-point and adapt to market volatility.

Trade Execution

Place trades directly from the chart modal:

Open a pattern chart via the results table.
Select your TP level (TP1: 0.38, TP2: 0.618, TP3: 0.786).
Enter Risk % (calculates lot size automatically) or a Fixed Lot size.
Click Place BUY or Place SELL.

The system automatically:

Resolves broker-specific symbol suffixes (e.g., EURUSD.ecn)
Retries across filling modes (FOK → IOC → Return) if rejected
Validates ATR levels against price bounds with fallback to standard levels

Trade Management

The Trades tab provides comprehensive position monitoring and automated management.

Active Trade Management

Enable the Active Trade Management toggle to activate background monitoring of all open positions:

Feature	Description
Breakeven	Automatically moves SL to entry when price reaches X% of TP distance in your favour.
Trailing Stop	SL follows price at a fixed % of TP behind current price, locking in profits.
Check Interval	Configurable interval (default 5s) for the background daemon thread.
Run Now	Manual one-shot check of all positions.

Position Management Modal

Click ✏️ SL/TP or ✕ Close on any position to open the management modal, allowing precise SL/TP modifications and partial or full position closing without browser alerts.

Telegram Bot Auto-Scanner

The Telegram tab lets you configure an automated background scanner that sends pattern alerts to your Telegram chat.

Setup

Create a bot via @BotFather on Telegram and copy the token.
Get your Chat ID via @userinfobot.
Enter both in the Telegram tab.
Click 📨 Test Message to verify.

Configuration Options

Setting	Description
Pairs	Comma-separated symbols to scan
Timeframes	Select from all 21 timeframes
Patterns	Toggle individual pattern types
Interval	Scan frequency (min: 5, default: 60 minutes)
Accuracy %	Pattern detection threshold
Min Quality %	Only alert above this ML confidence
Max Age (bars)	Ignore stale patterns older than X bars
Send Chart	Include matplotlib chart image with alert

Alert Format

Each alert includes: emoji header with direction, pair, timeframe, pattern name, standard levels, ML volatility levels (ATR-based), ML quality confidence with star rating, and Fibonacci ratios.

Custom Pattern Builder

Open Settings → scroll to Custom Pattern Builder to view, edit, or create patterns.

View: All 8 built-in patterns listed with their ratio ranges
Toggle: Enable/disable any pattern for scanning
Edit: Modify XB, AC, BD, XD min/max ratios for any pattern
Add: Create entirely new patterns with custom ratios
Persist: All changes saved to custom_patterns.json

API Reference

All endpoints are served from the Flask backend on http://127.0.0.1:PORT.

Connection

Endpoint	Method	Description
`/api/connect`	POST	Connect to MT5 (body: `{path}`)
`/api/disconnect`	POST	Disconnect from MT5
`/api/status`	GET	Connection status + account info + positions
`/api/detect-mt5`	GET	Auto-detect installed MT5 terminals
`/api/symbols`	GET	Available trading symbols

Data

Endpoint	Method	Description
`/api/rates`	GET	OHLC data (`?symbol=X&tf=Y&count=Z`)
`/api/tick`	GET	Latest tick for a symbol (`?symbol=X`)

Pattern Scanning

Endpoint	Method	Description
`/api/scan`	POST	Scan for patterns (`{pairs, timeframes, accuracy}`)
`/api/predict`	POST	Predict incomplete/emerging patterns
`/api/predict-quality`	POST	ML quality prediction with ATR levels (`{pattern, bars}`)
`/api/custom-patterns`	GET/POST	Get or save pattern definitions

Trading

Endpoint	Method	Description
`/api/trade`	POST	Place a trade order
`/api/position/modify`	POST	Modify SL/TP (`{ticket, sl, tp}`)
`/api/position/close`	POST	Close position (`{ticket}`)
`/api/positions/realtime`	GET	Live positions with total profit
`/api/trade-management`	GET/POST	Trailing stop & breakeven config
`/api/trade-management/run-now`	POST	One-shot trade management check

Settings & Utilities

Endpoint	Method	Description
`/api/settings`	GET/POST	Scanner settings
`/api/correlation`	POST	Currency strength index
`/api/sdzones`	POST	Support/demand zone detection
`/api/calendar`	GET	Economic calendar (`?days=14`)
`/api/telegram-settings`	GET/POST	Telegram bot configuration
`/api/telegram-test`	POST	Send test Telegram message
`/api/telegram-run-now`	POST	Immediate scan + Telegram alert

Harmonic Pattern Definitions

All ratios are fully editable from Settings → Custom Pattern Builder.

Pattern	XB (AB/XA)	AC (BC/AB)	BD (CD/BC)	XD (CD/XC)
Bat	0.382–0.500	0.382–0.886	1.618–2.618	0.886
Gartley	0.618–0.618	0.382–0.886	1.272–1.618	0.786
Butterfly	0.786–0.786	0.382–0.886	1.618–2.240	1.270
Crab	0.382–0.618	0.382–0.886	2.240–3.618	1.618
Deep Crab	0.886–0.886	0.382–0.886	1.618–2.618	1.618
Cypher	0.382–0.618	1.130–1.414	1.272–2.000	0.786
Shark	0.382–0.618	0.886–1.130	1.618–2.240	0.886
121	0.618–0.886	0.382–0.886	1.618–1.618	1.000

ML Quality Scorer

The ML quality scorer uses a Random Forest Classifier (100 trees, balanced weights) trained on-the-fly for each symbol/timeframe combination.

Features

Feature	Description
Ratio Tightness	How closely the pattern ratios match the ideal
CD Momentum	Momentum of the CD leg (C → D)
Volatility Ratio	Volatility at D-point vs historical average
Volume Divergence	Price-volume divergence at the completion point
Pattern Age	How many bars ago the pattern formed
Swing Alignment	Alignment with higher timeframe swings
XB Position	Position of B within the XA retracement
Prior Session Performance	Performance of the last N bars

Quality Levels

Score	Rating	Chart Color
≥ 80%	⭐⭐⭐ Excellent	Green
65–79%	⭐⭐ Good	Green
40–64%	⭐ Fair	Yellow
< 40%	— Weak	Red

Troubleshooting

Connection Issues

Problem	Solution
MT5 not detected	Manually enter the path to `terminal64.exe` in Settings → MT5 Path
Connection fails	Ensure MT5 is running and logged in to your account
Scanner finds 0 patterns	Lower the accuracy threshold, increase depth range, or add more pairs/timeframes
Trade placement fails	Check that your account allows trading (demo accounts may restrict certain symbols)

Telegram Bot

Problem	Solution
Test message fails	Verify the bot token is correct and the bot is started via @BotFather
Chat ID not found	Send a message to your bot first, then use @userinfobot to find your ID
No alerts received	Check that the bot is enabled (green status), min quality is not too high, and pairs/TFs are correct

Frequently Asked Questions

General

Q: What is harmonic pattern trading?
Harmonic patterns are specific geometric price formations that identify potential reversal zones based on Fibonacci ratios. They help traders identify high-probability entry points.

Q: Can I use this with any broker?
Yes. The app works with any broker that provides MT5 connectivity. It includes automatic symbol suffix resolution and filling mode fallback for maximum compatibility.

Technical

Q: How many symbols can I scan at once?
There is no hard limit. The parallel scanner uses configurable worker threads (default 4). Scanning 30 pairs across 3 timeframes typically completes in 3–8 seconds.

Q: Does it work with cryptocurrencies?
Yes, if your broker supports crypto symbols (e.g., BTCUSD, ETHUSD). Select them from Settings → Symbols.

Q: How is the ML model trained?
The Random Forest model trains on the fly for each symbol/timeframe pair. It uses the last 1500 bars to learn what makes a successful pattern, computing 8 feature dimensions per bar. Models are cached for subsequent scans.

Deployment

Q: Can I run this on a VPS?
Yes. The app is a standard Flask web server. Deploy it on any VPS and access the web UI remotely via the server's IP and port. Ensure MT5 is running on the VPS.

Q: Is the standalone executable safe?
Yes. The executable is built with PyInstaller and includes only the application code and its Python dependencies. You can verify the SHA-256 checksum provided on the download page.