From 8a1e57f68213128aca4199b07beeb536bae572b2 Mon Sep 17 00:00:00 2001 From: Harwinder Date: Tue, 5 May 2026 14:45:09 -0400 Subject: [PATCH] Update USAGE.md to match current behaviour MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 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 --- USAGE.md | 304 ++++++++++++++++++++++++++++++++----------------------- 1 file changed, 176 insertions(+), 128 deletions(-) diff --git a/USAGE.md b/USAGE.md index 99ac56e..f2b4037 100644 --- a/USAGE.md +++ b/USAGE.md @@ -6,17 +6,22 @@ pip install -r requirements.txt ``` -Set your Twelve Data API key (optional — falls back to the key in `config.py`): +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 -$env:TWELVE_DATA_API_KEY="your_key_here" # PowerShell ``` +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 +## Terminal — `main.py` ``` python main.py [OPTIONS] @@ -24,28 +29,31 @@ python main.py [OPTIONS] ### Options -| Option | Default | Description | -|---|---|---| -| `--pairs PAIR [PAIR ...]` | all major pairs | Specific pairs to analyze | -| `--timeframe 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 signal quality 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 | Show debug logging | +| 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 +### 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 | +| 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 @@ -62,7 +70,7 @@ python main.py --pairs XAUUSD --timeframe H4 --detail # Multiple pairs python main.py --pairs EURUSD GBPUSD USDJPY -# High-conviction signals only (grade B or above) +# Only Grade B+ signals python main.py --min-grade B # Top 3 signals across all pairs including crosses @@ -72,12 +80,14 @@ python main.py --all --top 3 python main.py --watch python main.py --pairs XAUUSD --watch --detail -# JSON output +# JSON output to a file python main.py --json python main.py --all --json > signals.json ``` -### Terminal Output +### Terminal output + +Summary table: ``` │ EUR/USD │ STRONG BUY │ ░░░░░░░░░░░░░│███████████████ │ A+ │ 82.3% │ @@ -87,67 +97,59 @@ python main.py --all --json > signals.json - **Grade** — overall quality of the signal setup - **⚠** — high-impact event imminent; **△** — event approaching (caution) -Detail block (shown automatically for Grade B+ signals, or all pairs with `--detail`): - -``` - EUR/USD │ Price: 1.08423 │ Regime: trending_up │ Vol: normal - - SIGNAL: STRONG BUY │ Score: +62.4 │ Grade: A+ │ Confidence: 82% - Action: STRONG BUY — High-quality setup, consider entry - - Multi-Timeframe: ✓ ALIGNED - M15: BUY (+28.1) - H1: STRONG BUY (+62.4) - H4: BUY (+41.0) - - Indicators (1h): - EMA Trend STRONG BUY (87%) │ EMA alignment: 4/4 | Golden cross - RSI NEUTRAL (40%) │ RSI 58.3 — Neutral - MACD STRONG BUY (82%) │ MACD bullish crossover | Hist: 0.000082 - ... - - Trade Setup: - Direction: BUY - Entry: 1.08423 - Stop Loss: 1.08150 (27.3 pips) - Take Profit 1: 1.08970 (54.7 pips) - Take Profit 2: 1.09517 - Risk:Reward: 1:2.0 -``` +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 - -```bash -# Set token then start the bot -set TELEGRAM_BOT_TOKEN=your_token_here # Windows CMD -export TELEGRAM_BOT_TOKEN=your_token_here # macOS / Linux -$env:TELEGRAM_BOT_TOKEN="your_token_here" # PowerShell +## 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`. -### Bot Commands +### Commands -| Command | Description | -|---|---| -| `/signal EURUSD` | Trade alert card for one pair at your default timeframe | -| `/signal EURUSD H4` | Trade alert with a specific timeframe | -| `/scan` | Scan all major pairs — sends one card per Grade B+ signal | -| `/scan H4` | Scan at a specific timeframe | -| `/tf H4` | Set your default timeframe (persists for the session) | -| `/help` | Command reference, grade guide, timeframe options | +| 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` | -### Trade Alert Format +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). -Each signal is delivered as a formatted card: +### Live progress + +Every command shows coarse progress through message edits while it runs: ``` -🟢 TRADE ALERT: BUY EUR/USD -Grade: A+ | Confidence: 82% | H1 +🔄 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) @@ -155,83 +157,129 @@ Take Profit 2: 1.09517 Stop Loss: 1.08150 (-27.3 pips) Risk:Reward: 1:2.0 -Technical Indicators: -• EMA Trend: 1.0842 (4/4 EMAs bullish) +• EMA Trend: 1.00 (Golden cross) +• MACD: 0.000082 (Bullish crossover) • RSI: 58.3 (Neutral) -• MACD: 0.0001 (Bullish crossover) -• Bollinger Bands: 1.0842 (Near lower band) -• Stochastic: 28.4 (Oversold) -• ADX: 31.2 (Strong trend) -• Ichimoku Cloud: 1.0831 (Above cloud) -• Divergences: 0.0000 (No divergence) -• Candlestick: 0.0000 (No pattern) -• Pivot Points: 1.0838 (Above pivot) +... -Multi-Timeframe (✅ Aligned): - 15min: BUY (+28) - 1h: STRONG BUY (+62) - 4h: BUY (+41) - -Regime: trending_up | Vol: normal | Score: +62.4 -⚠️ Educational use only. Not financial advice. +MTF: ✅ Aligned | Score: +62.4 | trending_up | Vol: normal ``` -**Dot colour matches grade:** +### Scan format -| Dot | Grade | Meaning | -|---|---|---| -| 🟢 | A / A+ | High confidence — entry candidate | -| 🟡 | B | Decent setup — wait for confirmation | -| 🔴 | C / D / F | Low confidence — watch only | +`/scan` produces one compact line per Grade B+ pair: -**`/signal`** — always returns the full card regardless of grade (useful for monitoring any pair). +``` +👍 EUR/USD · BUY · B · M15 + Entry: 1.08423 | TP: 1.08970 (+55p) | SL: 1.08150 (-27p) | R:R 1:2.0 +``` -**`/scan`** — only sends cards for Grade B or above; shows a summary count first, then one card per signal. Returns a "no signals" message if nothing qualifies. +Pairs without an actionable Grade B+ signal are omitted from the scan output. --- ## Signal Grades -| Grade | Score | Confidence | MTF | Meaning | -|---|---|---|---|---| -| A+ | ≥ 50 | ≥ 75% | ✓ aligned | Strongest — immediate entry candidate | -| A | ≥ 35 | ≥ 65% | ✓ aligned | Strong signal | -| B | ≥ 25 | ≥ 55% | — | Good setup — confirm before entering | -| C | ≥ 15 | ≥ 45% | — | Weak — monitor only | -| D | ≥ 10 | — | — | Noise | -| F | < 10 | — | — | No trade | +| 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 only generated for Grade B and above. +Trade setup (entry / TP / SL) is generated only for Grade A+ / A / B. --- ## Supported Symbols -Pass any symbol without slashes or the `=X` suffix: +Pass any symbol without slashes or the `=X` suffix. -| 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 | -| `XAUUSD` | Gold / US Dollar | -| `GBPJPY` | British Pound / Japanese Yen | +### Forex (live data on Twelve Data free tier) -Any symbol supported by Twelve Data works. Commodities like XAU/USD require a paid plan — the free tier falls back to synthetic GBM data for those. +| 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) +## API Limits -| Limit | Value | -|---|---| -| Credits per minute | 8 | -| Credits per day | 800 | -| Credits per full scan (7 pairs × 3 TFs) | ~21 | -| Full scans available per day | ~38 | +### Twelve Data — Free Tier -`--watch` mode re-scans every 5 minutes — this uses ~6 000 credits/day and will exceed the free tier. Use `--pairs` to limit the watchlist when running continuously. +| 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