ForexBot2/USAGE.md

ForexBot2 — Usage Guide

Setup

pip install -r requirements.txt

Set your Twelve Data API key (optional — falls back to the key in config.py):

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

---

Terminal — main.py

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

Timeframes

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

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

# High-conviction signals only (grade B or above)
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
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

---

Telegram Bot — telegram_bot.py

# 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 → /newbot.

Bot 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

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

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)

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.