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

---

## 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)**
```bash
python main.py
```
Analyzes EUR/USD, GBP/USD, USD/JPY, USD/CHF, AUD/USD, USD/CAD, NZD/USD on H1.

**One pair, full detail**
```bash
python main.py --pairs EURUSD --detail
```

**Gold on the 4-hour chart**
```bash
python main.py --pairs XAUUSD --timeframe H4 --detail
```

**Multiple pairs**
```bash
python main.py --pairs EURUSD GBPUSD USDJPY
```

**High-conviction signals only (grade B+)**
```bash
python main.py --min-grade B
```

**Top 3 signals across all pairs including crosses**
```bash
python main.py --all --top 3
```

**Continuous monitoring**
```bash
python main.py --watch
python main.py --pairs XAUUSD --watch --detail
```

**JSON output**
```bash
python main.py --json
python main.py --all --json > signals.json
```

---

## Running — Telegram Bot (telegram_bot.py)

```bash
export TELEGRAM_BOT_TOKEN="your_token_here"
python telegram_bot.py
```

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