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

Update USAGE.md to match current behaviour

Browse Source 
- 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>
This commit is contained in:
Harwinder
2026-05-05 14:45:09 -04:00
parent 6a75ed1ffb
commit 8a1e57f682
1 changed files with 176 additions and 128 deletions
Download Patch File Download Diff File Expand all files Collapse all files
USAGE.md
+176 -128
View File
@@ -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 <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
## 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