harry/ForexBot2
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Update USAGE.md to reflect rebuilt Telegram bot and current features

Browse Source 
- 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 <noreply@anthropic.com>
This commit is contained in:
Harwinder
2026-05-04 17:18:37 -04:00
parent 4aba243472
commit 7bde28c524
1 changed files with 132 additions and 89 deletions
Download Patch File Download Diff File Expand all files Collapse all files
USAGE.md
+132 -89
View File
@@ -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.