Harwinder
8a1e57f682
- main.py: same options, but examples and output reflect today's format - Telegram: drop nonexistent /tf and /signal-with-TF docs; document current commands (/signal, /scan, /help, /start) and the M15+H1 scan policy with D1 as silent confirmation - Telegram card format: dotless layout with grade symbols and legend - Symbols: split forex (Twelve Data live) from metals (yfinance fallback); call out GC=F vs spot basis; remove stale synthetic-data language since the fallback no longer exists - API limits: 3 batch calls × 7 pairs = 21 credits per scan, ~2 min - New Configuration section pointing to the right files for tuning Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
286 lines
10 KiB
Markdown
286 lines
10 KiB
Markdown
# 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 <https://twelvedata.com/pricing>. 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
|