harry/ForexBot2
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Refocus on XAU/USD: add momentum indicators, tune TP, exhaustion block

Browse Source 
Strip EUR/USD, GBP/USD, USD/JPY pairs and strategies from entire codebase.
Add 3 new scored indicators (ROC, Keltner/TTM Squeeze, ADX slope) and
enable MACD-as-pillar + divergence detection for early trend entry.
Introduce "transitioning" regime (ADX < 25, slope > 3.0) to catch trend
births before ADX confirms. Gold-specific composite weights per regime.

Tune TP multipliers: quality-tiered scaling (A+/A get 1.5-2.0x ATR via
XAU ATR method, B/C use swing-level targeting). Backtest: +24R total,
65% WR, PF 1.12 over 365 days.

Add momentum-confirmed exhaustion block: hard-reject trades when 2+
static exhaustion signals fire AND ROC/MACD confirm fading momentum.
Prevents late trend entries without killing strong trend trades.

Telegram: simplify buttons to timeframe-only labels, add "Scan All TFs"
multi-timeframe summary, add /scan command, fix BB/KC level breach keys,
fix price formatting (.2f for gold), fix deprecated asyncio call, fix
"1 pairs" grammar and 60s/30s dashboard refresh mismatch.
This commit is contained in:
harwinder
2026-05-15 10:51:51 -04:00
parent bb3c475f22
commit 04328eaeab
15 changed files with 852 additions and 2108 deletions
Download Patch File Download Diff File Expand all files Collapse all files
DOCUMENTATION.md
+96 -69
View File
@@ -6,17 +6,14 @@
## What Is ForexBot2?
ForexBot2 is an automated forex analysis bot. It watches 4 currency pairs around the clock, analyzes them using 6 different technical indicators, checks the news, and sends you alerts on Telegram when it finds a good trading opportunity — complete with entry price, stop loss, and take profit levels.
ForexBot2 is an automated XAU/USD (gold) signal intelligence platform. It analyzes gold across multiple timeframes using 9 technical indicators with regime-adaptive weights, checks the news, and sends you alerts on Telegram when it finds a good trading opportunity — complete with entry price, stop loss, and take profit levels.
Think of it as a tireless analyst who never sleeps, never gets emotional, and checks the charts every few minutes across multiple timeframes.
## What Pairs Does It Watch?
## What Does It Watch?
| Pair | What It Is |
|------|-----------|
| EUR/USD | Euro vs US Dollar — the world's most traded pair |
| GBP/USD | British Pound vs US Dollar |
| USD/JPY | US Dollar vs Japanese Yen |
| XAU/USD | Gold vs US Dollar |
## What Timeframes Does It Scan?
@@ -36,7 +33,7 @@ The M5 scan runs silently in the background — it gathers data to keep the bot'
The bot uses a layered decision process. It is not based on a single indicator — it combines multiple tools, each looking at the market from a different angle.
### The 6 Active Indicators
### The 9 Active Indicators
#### 1. EMA Trend (Exponential Moving Averages)
@@ -141,22 +138,56 @@ The *direction* comes from two companion lines: +DI (bullish pressure) and -DI (
---
#### 7. MACD (Moving Average Convergence Divergence)
**What it is:** MACD tracks the difference between a fast (12-period) and slow (26-period) EMA, with a signal line (9-period EMA of the MACD). The histogram shows the difference between MACD and signal.
**How the bot uses it:** Histogram crossing above zero = bullish momentum building. Crossing below zero = bearish. Histogram acceleration (getting larger) confirms trend strength. MACD is gold's best leading indicator — it catches momentum shifts before price breaks key levels.
**Weight:** 2.0 in trending markets, 2.5 in transitioning markets, 1.5 in ranging markets.
---
#### 8. ROC (Rate of Change)
**What it is:** ROC measures the percentage change in price over the last N bars (default: 10). It quantifies momentum acceleration.
**How to read it:**
- ROC > 0 and rising = bullish momentum accelerating
- ROC crossing zero = directional shift
- |ROC| > 2% = strong momentum (possible exhaustion)
**What the bot does with it:** ROC catches the speed of trend moves. Combined with Keltner squeeze release, it identifies breakout moments. Zero-line crossovers provide high-confidence directional signals.
**Weight:** 1.5 in trending, 2.0 in transitioning, 0.5 in ranging.
---
#### 9. Keltner Channels (TTM Squeeze)
**What it is:** Keltner Channels are an EMA(20) midline with bands at ±1.5×ATR(10). When Bollinger Bands contract inside Keltner Channels, that is a "TTM Squeeze" — volatility compression preceding a big move.
**How to read it:**
- Squeeze ON = bands compressed, breakout imminent
- Squeeze RELEASED = explosion happening now, direction from MACD
- Price above upper channel = strong uptrend continuation
- Price below lower channel = strong downtrend continuation
**What the bot does with it:** The squeeze release is the single best range-to-trend transition signal. When the squeeze fires and MACD agrees on direction, the bot generates a high-confidence signal. This is the most important indicator in the "transitioning" regime.
**Weight:** 2.5 in transitioning (squeeze breakouts), 2.0 in ranging, 1.5 in trending.
---
### Informational Indicators (Not Scored)
These indicators do not contribute to the buy/sell score but provide context:
- **ATR (Average True Range):** Measures volatility — how much the price moves on average per candle. Used for setting stop loss distances and classifying the market as low/normal/high/extreme volatility.
- **MACD Histogram:** Used internally by the divergence detector, not scored on its own.
- **ADX Slope:** Computed as ADX_now minus ADX_5_bars_ago. When ADX < 25 but slope > 3.0, the bot classifies the market as "transitioning" — a trend is being born. This catches trends 5-10 bars before traditional ADX threshold crossings.
- **EMA Ribbon Compression:** When the spread between EMA9/21/50 (normalized by ATR) is very tight, a trend change is imminent. The bot boosts EMA signal confidence when ribbon expansion is detected after compression.
- **Swing Structure (Support/Resistance):** Identifies the 3 nearest swing highs and 3 nearest swing lows. Used for setting take profit targets and stop losses.
### Dormant Indicators (Implemented But Not Active)
These are fully coded but currently switched off:
- **Stochastic Oscillator** — Similar to RSI but with a different calculation
- **Ichimoku Cloud** — Japanese trend-following system
- **Pivot Points** — Classic support/resistance levels
- **Volume Analysis** — Trading volume patterns
---
## How Are The Indicators Combined?
@@ -165,23 +196,27 @@ The bot does not just average the indicators. It uses a **regime-adaptive weight
### Step 1: Classify the Market Regime
Using ADX and EMA alignment, the bot first determines whether the market is:
Using ADX, EMA alignment, and ADX slope, the bot determines the market regime:
- **Trending up** — ADX above 25 and EMAs are bullishly aligned
- **Trending down** — ADX above 25 and EMAs are bearishly aligned
- **Ranging** — ADX below 25 (sideways/choppy market)
- **Transitioning** — ADX below 25 but ADX slope > 3.0 (trend is being born)
- **Ranging** — ADX below 25 and ADX slope ≤ 3.0 (sideways/choppy market)
### Step 2: Adjust Indicator Weights
### Step 2: Adjust Indicator Weights (Gold-Specific)
Depending on the regime, certain indicators get louder or quieter:
| Indicator | Trending Weight | Ranging Weight | Why |
|-----------|----------------|---------------|-----|
| EMA Trend | 2.0x | 0.5x | EMAs excel in trends, fail in chop |
| RSI | 1.5x | 2.0x | RSI overbought/oversold works in ranges |
| Bollinger | 0.8x | 2.0x | Mean reversion is a ranging strategy |
| Candlestick | 1.5x | 1.5x | Patterns work in both |
| Divergence | 1.0x | 1.5x | Divergences mark range boundaries |
| ADX | 1.0x | 1.0x | Confirms the regime itself |
| Indicator | Trending | Ranging | Transitioning | Why |
|-----------|----------|---------|---------------|-----|
| EMA Trend | 2.0 | 0.3 | 1.5 | EMAs excel in trends, fail in chop |
| RSI | 1.0 | 1.5 | 1.0 | RSI OB/OS works in ranges; gold doesn't mean-revert cleanly in trends |
| Bollinger | 0.5 | 1.5 | 1.0 | Gold rides the band in trends |
| MACD | 2.0 | 1.5 | 2.5 | Gold's best leading indicator |
| Keltner | 1.5 | 2.0 | 2.5 | Squeeze breakouts catch range-to-trend transitions |
| ROC | 1.5 | 0.5 | 2.0 | Momentum acceleration matters most at trend birth |
| Candlestick | 0.8 | 1.0 | 1.0 | Patterns work everywhere |
| Divergence | 2.0 | 2.5 | 2.0 | Gold's best reversal detector |
| ADX | 0.8 | 0.5 | 1.0 | Confirms the regime itself |
### Step 3: Compute Composite Score
@@ -203,7 +238,7 @@ This produces a score from -100 (maximum bearish) to +100 (maximum bullish).
| +40 or higher | STRONG BUY |
| +15 to +39 | BUY |
| -14 to +14 | NEUTRAL |
| -15 to -39 | SELL |
| -39 to -15 | SELL |
| -40 or lower | STRONG SELL |
---
@@ -285,7 +320,7 @@ If the signal score is above 30 (strong conviction), the bot treats it as a "mat
## Real-Time Price Monitoring (WebSocket)
For EUR/USD and XAU/USD, the bot also streams live prices via WebSocket (the other two pairs are monitored via periodic scans only — a limitation of the current data plan).
The bot streams live XAU/USD prices via WebSocket for real-time level breach detection.
### Level Break Alerts
@@ -305,26 +340,25 @@ When the live price crosses any of these levels, the bot:
---
## Correlation Warnings
## Confidence Adjustments (Diminishing Penalty Cap)
The bot tracks two correlation groups:
- **USD-weakness group:** EUR/USD and GBP/USD (both move inversely to USD)
- **Risk-sentiment group:** XAU/USD and USD/JPY (both respond to risk appetite)
Beyond indicators, MTF, and news, the bot applies penalties for risk factors. However, penalties use a **diminishing cap** to prevent over-suppression:
If both pairs in a group signal the same direction, the bot warns you: "Same exposure — you may be doubling your risk on the same theme."
1. All penalties are collected and sorted by magnitude (largest first)
2. Applied with exponential decay: 1st penalty at 100%, 2nd at 50%, 3rd at 25%
3. **Hard cap: total penalty never exceeds 30%**
---
## Additional Confidence Adjustments
Beyond indicators, MTF, and news, the bot applies these final adjustments:
| Factor | Effect | Why |
|--------|--------|-----|
| Counter-trend signal | -15% confidence | Trading against the trend is riskier |
| Extreme volatility | -10% confidence | Wild markets produce unreliable signals |
| Near EMA 200 (within 0.5%) | -10% confidence | Price tends to chop around EMA 200 |
| Far from EMA 200 (beyond 1.5%) | -10% confidence | Overextended from the mean |
| Factor | Base Penalty | Why |
|--------|-------------|-----|
| MTF disagreement | 15% | Trading against other timeframes is riskier |
| Counter-trend signal | 15% | Trading against the trend is riskier |
| Event caution | 15% | Upcoming economic event |
| Extreme volatility | 10% | Wild markets produce unreliable signals |
| News conflict | 10% | News sentiment opposes signal |
| Exhaustion warning | 8% | Momentum may be exhausted |
| No pullback | 8% | Entering without pullback reduces RR |
| Near EMA 200 | 5% | Price tends to chop around EMA 200 |
| Far from EMA 200 | 5% | Overextended from the mean |
Final confidence is always clamped between 0% and 95% — the bot never claims 100% confidence.
@@ -335,14 +369,14 @@ Final confidence is always clamped between 0% and 95% — the bot never claims 1
### Commands
| Command | What It Does |
|---------|-------------|
| `/start` | Shows the scan button grid (4 pairs x 3 timeframes) |
| `/start` | Shows the scan button grid (XAU/USD × 3 timeframes) |
| `/autoscan` | Turns automatic scanning on or off |
| `/status` | Shows bot status, WebSocket connection, live prices, level cache |
| `/help` | Lists all available commands |
### Auto-Scan Behavior
- Starts automatically on boot if `TELEGRAM_CHAT_ID` is configured
- Scans all 4 pairs at each candle boundary (M5/M15/H1/H4)
- Scans XAU/USD at each candle boundary (M5/M15/H1/H4)
- Only sends messages when actionable signals (grade A+/A/B/C) are found
- If no actionable signals are found, it stays silent (logged internally only)
@@ -372,7 +406,6 @@ ForexBot2/
news_engine.py # Economic calendar and news sentiment
data_provider.py # Twelve Data API client with caching and rate limiting
main.py # CLI entry point for single-pair analysis
ws_twelvedata.py # Standalone WebSocket test utility
requirements.txt # Python dependencies
```
@@ -384,7 +417,7 @@ pandas>=2.0 # DataFrame handling for OHLCV data
requests>=2.28 # HTTP client for news/calendar APIs
twelvedata>=1.2.0 # Twelve Data SDK (REST OHLCV source)
python-telegram-bot>=20.0 # Async Telegram bot framework
websockets>=12.0 # WebSocket client for live price streaming
websockets>=12.0 # WebSocket client for live price streaming (Telegram bot level-breach monitor)
```
## Data Flow
@@ -396,7 +429,7 @@ websockets>=12.0 # WebSocket client for live price streaming
(fetch + cache + validate OHLCV)
|
engine.py
(compute 6 indicators per TF)
(compute 9 indicators per TF)
|
signal_aggregator.py
(MTF agreement + news + final signal + trade setup)
@@ -424,15 +457,11 @@ class SignalStrength(Enum):
### Pair Definitions
```python
USDJPY = "USDJPY=X" # Yahoo-style suffix for forex
EURUSD = "EURUSD=X"
GBPUSD = "GBPUSD=X"
XAUUSD = "XAU/USD"
XAUUSD = "XAU/USD" # No suffix for commodities
PAIR_INFO = {
USDJPY: {"display": "USD/JPY", "pip_value": 0.01, "is_jpy_pair": True},
EURUSD: {"display": "EUR/USD", "pip_value": 0.0001, "is_jpy_pair": False},
GBPUSD: {"display": "GBP/USD", "pip_value": 0.0001, "is_jpy_pair": False},
XAUUSD: {"display": "XAU/USD", "pip_value": 0.10, "is_jpy_pair": False},
XAUUSD: {"display": "XAU/USD", "pip_value": 0.10, "is_jpy_pair": False},
}
```
@@ -476,7 +505,7 @@ Maintains a sliding window of timestamps. If 55 calls were made in the last 60 s
### Symbol Conversion: `_to_td_symbol(symbol)`
```
"EURUSD=X" -> "EUR/USD" (strip =X, insert /)
"XAU/USD" -> "XAU/USD" (pass-through for slash-format symbols)
"XAU/USD" -> "XAU/USD" (already has /, pass through)
```
@@ -628,8 +657,8 @@ Signal mapping: >=40 STRONG_BUY, >=15 BUY, <=-40 STRONG_SELL, <=-15 SELL, else N
```python
@dataclass
class TradeSetup:
pair: str # "EURUSD=X"
display_name: str # "EUR/USD"
pair: str # "XAU/USD"
display_name: str # "XAU/USD"
direction: str # "BUY" or "SELL"
entry_price: float
stop_loss: float
@@ -814,10 +843,8 @@ CURRENCY_KEYWORDS = {
### Pair Impact Mapping
```python
"USD" -> [EURUSD, USDJPY, GBPUSD, XAUUSD] # USD events affect all pairs
"EUR" -> [EURUSD]
"JPY" -> [USDJPY]
"GBP" -> [GBPUSD]
"USD" -> [XAUUSD] # USD events affect gold
"XAU" -> [XAUUSD]
"XAU" -> [XAUUSD]
```
@@ -898,7 +925,7 @@ def _run_signal_sync(symbol, timeframe, confirmation_tfs):
```python
while _autoscan_chats:
connect to wss://ws.twelvedata.com/v1/quotes/price?apikey=...
subscribe to ["EUR/USD", "XAU/USD"]
subscribe to ["XAU/USD"]
for each incoming message:
if event != "price": continue
map ws_symbol -> pair_symbol via _WS_TO_PAIR
@@ -947,14 +974,14 @@ Footer: "Educational / research use only."
Timeframe Auto-Scan | HH:MM UTC
Per pair: emoji, signal, quality, score, confidence, MTF status
Actionable list
Correlation warnings (if any)
Actionable signals (if any)
```
### Telegram Commands
| Handler | Function | Registration |
|---------|----------|-------------|
| `/start` | `cmd_start()` | Shows scan keyboard (12 buttons: 4 pairs x 3 TFs) |
| `/start` | `cmd_start()` | Shows scan keyboard (3 buttons: XAU/USD × 3 TFs) |
| `/help` | `cmd_help()` | Lists all commands |
| `/status` | `cmd_status()` | Auto-scan state, WS state, live prices, level cache stats, cooldowns |
| `/autoscan` | `cmd_autoscan()` | Toggle: adds/removes chat from `_autoscan_chats`, starts/stops scheduler |
@@ -967,8 +994,8 @@ Correlation warnings (if any)
### Usage
```bash
python main.py # Default: USD/JPY H1
python main.py --timeframe M15 # USD/JPY M15
python main.py # Default: XAU/USD H1
python main.py --timeframe M15 # XAU/USD M15
python main.py --detail # Include full indicator breakdown
python main.py --json # Output as JSON
python main.py --verbose # Debug logging
@@ -1000,7 +1027,7 @@ Terminal output includes color-coded sections:
2. **Shared data provider:** A single `ForexDataProvider` instance is reused across all signal computations (`_get_shared_dp()`). This maximizes cache hits — when M15 and M5 scans both need H1 data, it is fetched once.
3. **WebSocket limited to 2 symbols:** The Twelve Data Grow plan (8 trial WS credits) only supports EUR/USD and XAU/USD via WebSocket. GBP/USD and USD/JPY are monitored exclusively through periodic REST scans.
3. **WebSocket for XAU/USD only:** The bot streams live prices via WebSocket for real-time level breach detection on gold.
4. **M5 is data-only:** The M5 scan runs every 5 minutes but only updates the level cache (used by WebSocket breach detection). It does not send Telegram messages — this reduces noise while keeping the internal picture current.