ForexBot2/USAGE.md

# ForexBot2 — Usage Guide

## Setup

```bash
pip install -r requirements.txt
```

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

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

---

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

```bash
# 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

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

python telegram_bot.py
```

Get a token from [@BotFather](https://t.me/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.