From 7bde28c5244f652dfc1b9ac7b1418ab7088c7b91 Mon Sep 17 00:00:00 2001 From: Harwinder Date: Mon, 4 May 2026 17:18:37 -0400 Subject: [PATCH] Update USAGE.md to reflect rebuilt Telegram bot and current features MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Replace /pair + old /scan docs with new /signal and /scan commands - Add trade alert card format with dot-grade legend (🟢/🟡/🔴) - Document /scan grade-B+ filter behaviour and summary header - Expand signal grades table with score/confidence/MTF thresholds - Add note that trade setup only generated for Grade B and above - Add --watch API credit warning; fix Windows token setup syntax Co-Authored-By: Claude Sonnet 4.6 --- USAGE.md | 221 +++++++++++++++++++++++++++++++++---------------------- 1 file changed, 132 insertions(+), 89 deletions(-) diff --git a/USAGE.md b/USAGE.md index 04afc33..99ac56e 100644 --- a/USAGE.md +++ b/USAGE.md @@ -16,7 +16,7 @@ $env:TWELVE_DATA_API_KEY="your_key_here" # PowerShell --- -## Running — Terminal (main.py) +## Terminal — main.py ``` python main.py [OPTIONS] @@ -49,80 +49,167 @@ python main.py [OPTIONS] ### Examples -**Scan all major pairs (default)** ```bash +# Scan all major pairs on H1 (default) python main.py -``` -Analyzes EUR/USD, GBP/USD, USD/JPY, USD/CHF, AUD/USD, USD/CAD, NZD/USD on H1. -**One pair, full detail** -```bash +# One pair, full indicator detail python main.py --pairs EURUSD --detail -``` -**Gold on the 4-hour chart** -```bash +# Gold on the 4-hour chart python main.py --pairs XAUUSD --timeframe H4 --detail -``` -**Multiple pairs** -```bash +# Multiple pairs python main.py --pairs EURUSD GBPUSD USDJPY -``` -**High-conviction signals only (grade B+)** -```bash +# High-conviction signals only (grade B or above) python main.py --min-grade B -``` -**Top 3 signals across all pairs including crosses** -```bash +# Top 3 signals across all pairs including crosses python main.py --all --top 3 -``` -**Continuous monitoring** -```bash +# Continuous monitoring — refreshes every 5 minutes python main.py --watch python main.py --pairs XAUUSD --watch --detail -``` -**JSON output** -```bash +# JSON output python main.py --json python main.py --all --json > signals.json ``` +### Terminal Output + +``` + │ 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 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 +``` + --- -## Running — Telegram Bot (telegram_bot.py) +## Telegram Bot — telegram_bot.py ```bash -export TELEGRAM_BOT_TOKEN="your_token_here" +# 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 + python telegram_bot.py ``` -Get a token from [@BotFather](https://t.me/BotFather) on Telegram (`/newbot`). +Get a token from [@BotFather](https://t.me/BotFather) → `/newbot`. ### Bot Commands | Command | Description | |---|---| -| `/scan` | Scan all major pairs at your default timeframe | -| `/scan H4` | Scan with a specific timeframe | -| `/pair EURUSD` | Detailed analysis of one pair | -| `/pair EURUSD H4` | With timeframe override | -| `/tf H4` | Set your default timeframe | -| `/help` | Command reference and timeframe guide | +| `/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 | -The bot output mirrors the terminal format exactly — same header, score bars, table, and detail report. +### Trade Alert Format + +Each signal is delivered as a formatted card: + +``` +🟢 TRADE ALERT: BUY EUR/USD +Grade: A+ | Confidence: 82% | H1 + +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 + +Technical Indicators: +• EMA Trend: 1.0842 (4/4 EMAs bullish) +• 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. +``` + +**Dot colour matches grade:** + +| Dot | Grade | Meaning | +|---|---|---| +| 🟢 | A / A+ | High confidence — entry candidate | +| 🟡 | B | Decent setup — wait for confirmation | +| 🔴 | C / D / F | Low confidence — watch only | + +**`/signal`** — always returns the full card regardless of grade (useful for monitoring any pair). + +**`/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. + +--- + +## 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 | + +Trade setup (entry / TP / SL) is only generated for Grade B and above. --- ## Supported Symbols -Pass any symbol without slashes or spaces: +Pass any symbol without slashes or the `=X` suffix: -| You type | Pair | +| Input | Pair | |---|---| | `EURUSD` | Euro / US Dollar | | `GBPUSD` | British Pound / US Dollar | @@ -134,61 +221,17 @@ Pass any symbol without slashes or spaces: | `XAUUSD` | Gold / US Dollar | | `GBPJPY` | British Pound / Japanese Yen | -Any symbol supported by Twelve Data works. Note: commodities like XAU/USD require a paid Twelve Data plan — the free tier falls back to synthetic data for those. - ---- - -## Signal Grades - -| Grade | Meaning | -|---|---| -| A+ | Strongest — all timeframes aligned, very high confidence | -| A | Strong signal, minor timeframe divergence | -| B | Good setup — wait for confirmation before entering | -| C | Weak signal — for monitoring only | -| D/F | Noise — best ignored | - ---- - -## Output Explained - -``` - │ EUR/USD │ STRONG BUY │ ░░░░░░░░░░░░░░│███████████████ │ A+ │ 82.3% │ -``` - -- **Score bar** — left of │ = bearish, right of │ = bullish, filled blocks show strength -- **Grade** — overall quality of the signal setup - -``` - EUR/USD │ Price: 1.08423 │ Regime: trending_up │ Vol: normal - - SIGNAL: STRONG BUY │ Score: +62.4 │ Grade: A │ Confidence: 74% - Action: STRONG BUY — High-quality setup, consider entry - - Multi-Timeframe: ✓ ALIGNED - M15: BUY (+28.1) - H1: STRONG BUY (+62.4) - H4: BUY (+41.0) - - 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 -``` - -- **Score** — −100 (strong sell) to +100 (strong buy) -- **Regime** — `trending_up`, `trending_down`, or `ranging` -- **Confidence** — 0–100% based on indicator agreement -- **Trade Setup** — entry, stop loss, and take profit auto-calculated from ATR +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. --- ## API Limits (Twelve Data Free Tier) -- 8 credits per minute -- 800 credits per day -- Each full scan uses ~21 credits (7 pairs × 3 timeframes) -- ~38 full scans available per day on the free plan +| 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 | + +`--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.