ForexBot2/LOGIC.md

ForexBot2 — Engine Logic Reference

1. Data Provider (Twelve Data API)

What the API provides

Each API call returns an OHLCV time series for a currency pair:

Field	Description
Datetime	UTC timestamp of the candle open
Open	Opening price
High	Highest price during the candle
Low	Lowest price during the candle
Close	Closing price
Volume	Tick volume (limited on Forex)

Supported intervals: 1min, 5min, 15min, 30min, 1h, 4h, 1day, 1week.

Supported pairs (free tier — live data)

EURUSD, GBPUSD, USDJPY, USDCHF, AUDUSD, USDCAD, NZDUSD, EURGBP, EURJPY, GBPJPY, AUDJPY, EURCHF, CADJPY. All other symbols (XAU, XAG, indices) return no data on the free plan.

API credit limits (free tier)

• 8 credits per minute
• 800 credits per day
• 1 credit per symbol in a batch request (7 pairs in one request = 7 credits, not 7 requests)

Data validation and cleaning

After every fetch the data goes through _validate_and_clean:

1. Drop rows where all of Open/High/Low/Close are NaN
2. Forward-fill small gaps (max 3 consecutive bars)
3. Drop rows still missing Close
4. Remove bars with future timestamps (> 5 min ahead of now)
5. Fix OHLC inconsistencies (e.g. High < Low) by clamping
6. Remove extreme outlier bars (> 10 standard deviations return)
7. Sort index and deduplicate (keep last on duplicates)

---

2. How Many API Calls Are Made

Per scan or /signal command

The bot does one shared prefetch before spawning the 4 TF analyses. It collects all unique timeframes needed across all scans, then makes one batch API call per timeframe (all pairs in a single request).

Current SCAN_TIMEFRAMES: M15, H1, D1, W1 Confirmations:

• M15 uses: H1, D1
• H1 uses: M15, D1
• D1 uses: H1, W1
• W1 uses: D1

Unique timeframes: M15, H1, D1, W1 = 4 batch calls

Each call: 7 pairs × 1 credit = 7 credits per call

Total per scan: 4 calls × 7 credits = 28 credits

With the 8 credits/minute limit:

• Call 1 (7 credits): fires immediately — 1 credit remaining
• Call 2 (7 credits): must wait ~60s for window to clear
• Call 3 (7 credits): waits another ~60s
• Call 4 (7 credits): waits another ~60s

Minimum scan time: ~3 minutes.

After the shared prefetch, the 4 concurrent TF analyses read from the in-memory cache and make zero additional API calls.

Cache behaviour

Results are cached per symbol+timeframe for refresh_interval seconds (default in PlatformConfig). A second scan within that window skips all API calls entirely and returns cached data instantly.

---

3. Technical Engine — How Signals Are Decided

Step 1 — Fetch OHLCV data

Primary timeframe data is fetched first. If it fails, the report is immediately graded F and returned — no further analysis is attempted. Confirmation timeframe data is fetched next; failures are logged as warnings but do not abort the analysis.

Step 2 — Compute 11 indicators

Each indicator returns: value, signal (STRONG_BUY / BUY / NEUTRAL / SELL / STRONG_SELL), confidence (0–100), and a weight.

Indicator	Weight	What it measures
EMA Trend	1.2	Alignment of fast/medium/slow/trend EMAs
MACD	1.1	Momentum crossover and histogram direction
Ichimoku	1.1	Cloud position, TK cross, cloud colour
RSI	1.0	Overbought/oversold momentum
ADX	1.0	Trend strength and directional index
Bollinger Bands	0.9	Price position within volatility envelope
Stochastic	0.8	Oscillator crossover in OB/OS zones
Candlestick	0.7	Pattern detection (hammer, engulfing, doji…)
Divergence	1.5	RSI/MACD divergence from price (reversal)
Pivot Points	0.6	Classical pivot S/R relative to current price
ATR / Volume	0.0	Context only — not included in score

Divergence has the highest weight (1.5) because divergences are strong reversal predictors. ATR and Volume have weight 0 — they inform the trade setup and volatility regime but do not vote on direction.

Step 3 — Classify market regime

Using ADX value and EMA direction:

• trending_up / trending_down: ADX ≥ strong threshold + EMA aligned
• ranging: ADX below threshold

The regime changes indicator weights for the composite score:

• Trending: EMA (×1.5), ADX (×1.3), MACD (×1.2) weighted up; RSI (×0.7) and Bollinger (×0.6) weighted down
• Ranging: RSI (×1.4), Bollinger (×1.4), Stochastic (×1.3) weighted up; EMA (×0.6) and ADX (×0.5) weighted down

Step 4 — Compute composite score (−100 to +100)

For each indicator:

weighted_score = signal_value × weight × regime_multiplier × (confidence / 100)

Signal values: STRONG_BUY = +2, BUY = +1, NEUTRAL = 0, SELL = −1, STRONG_SELL = −2

Final composite score = (sum of weighted scores / total weight) × 50

Composite signal thresholds:

• score ≥ +40 → STRONG BUY
• score ≥ +15 → BUY
• score ≤ −40 → STRONG SELL
• score ≤ −15 → SELL
• otherwise → NEUTRAL

Step 5 — Multi-timeframe (MTF) agreement check

All timeframe signals (primary + confirmations) are collected. MTF agreement = True if at least mtf_agreement_threshold timeframes all point bullish or all point bearish.

Effect on confidence:

• Agreement: confidence +15 (capped at 95); score blended with average of all TF scores (60% primary, 40% MTF average)
• Disagreement: confidence ×0.7
• Conflict (some bullish, some bearish): confidence ×0.7 × 0.6 = ×0.42
  • warning added to report

Step 6 — Fundamental adjustments

Applied in order, each multiplying confidence:

Condition	Confidence adjustment
News aligns with technical	+5 (capped 95)
News conflicts with technical	×0.85
Event risk: caution	×0.70
Event risk: danger	×0.30 + block signal
Volatility: extreme	×0.80

Step 7 — Final signal determination

Uses the adjusted score and confidence:

Condition	Signal
score ≥ +40 and confidence ≥ 65	STRONG BUY
score ≥ +15 and confidence ≥ 50	BUY
score ≤ −40 and confidence ≥ 65	STRONG SELL
score ≤ −15 and confidence ≥ 50	SELL
otherwise	NEUTRAL

Step 8 — Quality grade

Combines score, confidence, and MTF agreement into a letter grade:

Grade	abs(score)	confidence	MTF agreement
A+	≥ 50	≥ 75	required
A	≥ 35	≥ 65	required
B	≥ 25	≥ 55	not required
C	≥ 15	≥ 45	not required
D	≥ 10	any	not required
F	< 10	any	—

A+ and A require MTF agreement as a hard condition — no matter how strong the primary score, without timeframe alignment the grade caps at B.

Step 9 — Trade setup (grades A+, A, B only)

Entry = current close price Stop Loss = entry ± (ATR × 1.5) Take Profit 1 = entry ± (SL distance × R:R ratio) Take Profit 2 = entry ± (SL distance × R:R ratio × 1.5)

ATR is used as the volatility measure so SL/TP adapt to current market conditions rather than using fixed pip distances.

---

4. Signal Flow Summary

Telegram /scan or /signal
        │
        ▼
_analyze_all_tfs(pairs)
        │
        ├── prefetch_batch(pairs, [M15, H1, D1, W1])
        │       ├── Batch call 1: all pairs @ M15  (7 credits, wait if needed)
        │       ├── Batch call 2: all pairs @ H1   (7 credits, wait if needed)
        │       ├── Batch call 3: all pairs @ D1   (7 credits, wait if needed)
        │       └── Batch call 4: all pairs @ W1   (7 credits, wait if needed)
        │
        └── 4 threads (one per TF), all reading from warm cache
                │
                └── per thread: SignalAggregator.analyze_all_pairs()
                        │
                        └── per pair: analyze_pair()
                                ├── fetch_ohlcv (cache hit)
                                ├── TechnicalEngine.analyze()
                                │       ├── 11 indicators
                                │       ├── Regime classification
                                │       └── Composite score
                                ├── MTF agreement check
                                ├── News / event risk adjustments
                                ├── Final signal + grade
                                └── Trade setup (A+/A/B only)