# ForexBot2 — Usage Guide ## Setup ```bash pip install -r requirements.txt ``` Set your Twelve Data API key (the bot will not work without one): ```powershell $env:TWELVE_DATA_API_KEY="your_key_here" # PowerShell ``` ```bash export TWELVE_DATA_API_KEY=your_key_here # macOS / Linux set TWELVE_DATA_API_KEY=your_key_here # Windows CMD ``` Get a free key at . Free tier covers most major Forex pairs; gold/silver fall through to Yahoo Finance automatically (see [Symbols](#supported-symbols)). --- ## Terminal — `main.py` ``` python main.py [OPTIONS] ``` ### Options | Option | Default | Description | |------------------------------|--------------------------|----------------------------------------------------------| | `--pairs PAIR [PAIR ...]` | all major pairs | Specific pairs to analyze | | `--timeframe TF` / `-tf TF` | `H1` | Primary timeframe — see table below | | `--all` | off | Include cross pairs (EUR/GBP, EUR/JPY, GBP/JPY, etc.) | | `--detail` | off | Full indicator breakdown for every pair | | `--top N` | all | Show only the top N signals by strength | | `--min-grade GRADE` | `F` | Minimum grade to display: `A+ A B C D F` | | `--json` | off | Output results as JSON | | `--watch` | off | Continuous mode — re-scans every 5 minutes | | `--verbose` / `-v` | off | Enable debug logging | ### Timeframes accepted by `--timeframe` | Flag | Interval | Best for | |-------|-------------|---------------------------| | `M5` | 5 minutes | Scalping | | `M15` | 15 minutes | Short-term intraday | | `M30` | 30 minutes | Intraday | | `H1` | 1 hour | Intraday / swing (default)| | `H4` | 4 hours | Swing trading | | `D1` | Daily | Position trading | `main.py` automatically picks confirmation timeframes around the primary (e.g. `H1` confirms with `M15` and `H4`). ### Examples ```bash # Scan all major pairs on H1 (default) python main.py # One pair, full indicator detail python main.py --pairs EURUSD --detail # Gold on the 4-hour chart python main.py --pairs XAUUSD --timeframe H4 --detail # Multiple pairs python main.py --pairs EURUSD GBPUSD USDJPY # Only Grade B+ signals python main.py --min-grade B # Top 3 signals across all pairs including crosses python main.py --all --top 3 # Continuous monitoring — refreshes every 5 minutes python main.py --watch python main.py --pairs XAUUSD --watch --detail # JSON output to a file python main.py --json python main.py --all --json > signals.json ``` ### Terminal output Summary table: ``` │ EUR/USD │ STRONG BUY │ ░░░░░░░░░░░░░│███████████████ │ A+ │ 82.3% │ ``` - **Score bar** — left of `│` = bearish, right = bullish; filled blocks show strength - **Grade** — overall quality of the signal setup - **⚠** — high-impact event imminent; **△** — event approaching (caution) Detail block (shown automatically for Grade B+ signals, or for every pair with `--detail`) includes price, regime, multi-timeframe breakdown, every indicator value, bullish/bearish reasons, warnings, news, and the trade setup (entry / SL / TP1 / TP2). --- ## Telegram Bot — `telegram_bot.py` ```powershell $env:TELEGRAM_BOT_TOKEN="your_token_here" python telegram_bot.py ``` Get a token from [@BotFather](https://t.me/BotFather) → `/newbot`. ### Commands | Command | Description | |--------------------|---------------------------------------------------------------------| | `/signal EURUSD` | Full signal analysis for one pair across M15 and H1 | | `/signal XAUUSD` | Same — gold uses the yfinance fallback automatically | | `/scan` | Analyze all major pairs, return one card per Grade B+ pair | | `/help` | Command reference + grade legend | | `/start` | Same as `/help` | The bot **does not** accept a timeframe argument. It always scans M15 and H1 (using D1 as a confirmation timeframe internally for higher-timeframe trend context). To change timeframes, edit `SCAN_TIMEFRAMES` in [telegram_bot.py](telegram_bot.py). ### Live progress Every command shows coarse progress through message edits while it runs: ``` 🔄 Analyzing XAU/USD across M15 · H1… 📡 Fetching market data (3 timeframes × 1 pair)… 🧠 Analyzing pairs across timeframes… ``` The placeholder is then replaced by the result message (`/signal`) or new messages are sent (`/scan`). ### Signal card format ``` 🌐 🧠 EUR/USD — Signal Analysis 🕐 03:45 PM EST · Mon 04 May 2026 Grade scale: 🔥 A+ · ✅ A · 👍 B · ⚠️ C · 📉 D · ❌ F ──────────────────────── ✅ M15 · BUY · Grade A Entry: 1.08423 Take Profit: 1.08970 (+54.7 pips) Take Profit 2: 1.09517 Stop Loss: 1.08150 (-27.3 pips) Risk:Reward: 1:2.0 • EMA Trend: 1.00 (Golden cross) • MACD: 0.000082 (Bullish crossover) • RSI: 58.3 (Neutral) ... MTF: ✅ Aligned | Score: +62.4 | trending_up | Vol: normal ``` ### Scan format `/scan` produces one compact line per Grade B+ pair: ``` 👍 EUR/USD · BUY · B · M15 Entry: 1.08423 | TP: 1.08970 (+55p) | SL: 1.08150 (-27p) | R:R 1:2.0 ``` Pairs without an actionable Grade B+ signal are omitted from the scan output. --- ## Signal Grades | Grade | Symbol | abs(score) | confidence | MTF agreement | Meaning | |-------|--------|-----------:|-----------:|---------------|--------------------------------------| | A+ | 🔥 | ≥ 50 | ≥ 75 | required | Strongest — entry candidate | | A | ✅ | ≥ 35 | ≥ 65 | required | Strong signal | | B | 👍 | ≥ 25 | ≥ 55 | not required | Decent setup — confirm before entry | | C | ⚠️ | ≥ 15 | ≥ 45 | not required | Weak — monitor only | | D | 📉 | ≥ 10 | any | not required | Noise | | F | ❌ | < 10 | any | — | No trade | Trade setup (entry / TP / SL) is generated only for Grade A+ / A / B. --- ## Supported Symbols Pass any symbol without slashes or the `=X` suffix. ### Forex (live data on Twelve Data free tier) | Input | Pair | |----------|---------------------------------------| | `EURUSD` | Euro / US Dollar | | `GBPUSD` | British Pound / US Dollar | | `USDJPY` | US Dollar / Japanese Yen | | `USDCHF` | US Dollar / Swiss Franc | | `AUDUSD` | Australian Dollar / US Dollar | | `USDCAD` | US Dollar / Canadian Dollar | | `NZDUSD` | New Zealand Dollar / US Dollar | | `EURGBP`, `EURJPY`, `GBPJPY`, `AUDJPY`, `EURCHF`, `CADJPY` | Major crosses | ### Metals (Yahoo Finance fallback — automatic) | Input | Maps to | Source | |----------|---------|--------------------| | `XAUUSD` | `GC=F` | Yahoo gold futures | | `XAGUSD` | `SI=F` | Yahoo silver futures | When Twelve Data returns no data for a symbol (e.g. gold on the free tier), the data provider transparently falls back to Yahoo Finance via `yfinance`. Logs are tagged `[live]` for Twelve Data and `[yf]` for Yahoo so you can verify the source. Note: `GC=F` is the futures contract, not spot XAU/USD. Direction is identical, but absolute price differs from your broker's spot quote by a small basis (typically $5–15). Use signal direction; execute at your broker's price. ### Symbols not on free tier and not mapped to yfinance Any symbol Twelve Data doesn't return data for and isn't in the yfinance fallback map will fail with `❌ Data unavailable`. The bot does not generate synthetic data. --- ## API Limits ### Twelve Data — Free Tier | Limit | Value | |---------------------|---------------| | Credits per minute | 8 | | Credits per day | 800 | | Credits per scan | 21 (3 TFs × 7 pairs) | | Theoretical scans/day | ~38 | Each scan makes 3 batch API calls (one per unique timeframe: M15, H1, D1). The 8-credits/minute limit means subsequent calls wait ~60 s for the window to clear, so a full scan takes about **2 minutes**. Subsequent scans within `refresh_interval` are served from cache and make zero API calls. ### Yahoo Finance — Unofficial No published rate limits. Used only for symbols mapped in `_YF_FALLBACK_MAP` (currently gold and silver futures). Daily/weekly intervals have unlimited history; intraday is capped (1m: last 7 days, 15m–1h: last 60 days), which is more than enough for the engine's ~210 bar requirement. ### `--watch` mode `main.py --watch` re-scans every 5 minutes. With 7 pairs that's 21 credits × 12 = 252 credits/hour — still within the daily limit if you run it for under ~3 hours. For longer runs, scope down with `--pairs` or stop and restart on demand. --- ## Configuration Most user-tunable values live in [config.py](config.py): - `MAJOR_PAIRS`, `CROSS_PAIRS` — which symbols `/scan` and `--all` cover - `SYMBOL_DISPLAY` — pretty names for messages - `PIP_VALUES` — per-symbol pip value override (gold = 0.01, JPY = 0.01) - `PlatformConfig` defaults — lookback days, refresh interval, indicator periods, MTF threshold, R:R ratio Bot-specific knobs in [telegram_bot.py](telegram_bot.py): - `SCAN_TIMEFRAMES` — which primary timeframes the bot reports on (default: `["M15", "H1"]`) - `_TF_CONFIRMATIONS` — confirmation TFs per primary - `_YF_FALLBACK_MAP` (in [data_provider.py](data_provider.py)) — Yahoo symbol mapping