ForexBot2/USAGE.md

ForexBot2 — Usage Guide

Setup

pip install -r requirements.txt

Set your Twelve Data API key (the bot will not work without one):

$env:TWELVE_DATA_API_KEY="your_key_here"   # PowerShell

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).

---

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

# 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

$env:TELEGRAM_BOT_TOKEN="your_token_here"
python telegram_bot.py

Get a token from @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.

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:

• 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:

• 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) — Yahoo symbol mapping