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

---

Running — 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 (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

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

python main.py --min-grade B

Top 3 signals across all pairs including crosses

python main.py --all --top 3

Continuous monitoring

python main.py --watch
python main.py --pairs XAUUSD --watch --detail

JSON output

python main.py --json
python main.py --all --json > signals.json

---

Running — Telegram Bot (telegram_bot.py)

export TELEGRAM_BOT_TOKEN="your_token_here"
python telegram_bot.py

Get a token from @BotFather on Telegram (/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

The bot output mirrors the terminal format exactly — same header, score bars, table, and detail report.

---

Supported Symbols

Pass any symbol without slashes or spaces:

You type	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. 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

---

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