# ForexBot2 — Usage Guide

## Setup

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

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

```bash
export TWELVE_DATA_API_KEY=your_key_here   # Linux/Mac
set TWELVE_DATA_API_KEY=your_key_here      # Windows CMD
$env:TWELVE_DATA_API_KEY="your_key_here"   # PowerShell
```

---

## Basic Syntax

```
python main.py [OPTIONS]
```

---

## Options

| Option | Default | Description |
|---|---|---|
| `--pairs PAIR [PAIR ...]` | all major pairs | Specific pairs to analyze |
| `--timeframe TF` | `H1` | Primary timeframe: `M5 M15 M30 H1 H4 D1` |
| `--all` | off | Add EUR/GBP, EUR/JPY, GBP/JPY and other cross pairs |
| `--detail` | off | Full indicator breakdown per pair |
| `--top N` | all | Show only the top N signals by strength |
| `--min-grade GRADE` | `F` (show all) | Filter by minimum quality grade: `A+ A B C D F` |
| `--json` | off | Output results as JSON instead of the terminal UI |
| `--watch` | off | Continuous monitoring — refreshes every 5 minutes |
| `--verbose` / `-v` | off | Enable debug logging |

---

## Common Examples

### Analyze all major Forex pairs (default)
```bash
python main.py
```
Analyzes EUR/USD, GBP/USD, USD/JPY, USD/CHF, AUD/USD, USD/CAD, NZD/USD on H1.

---

### Analyze Gold (XAU/USD)
```bash
python main.py --pairs XAUUSD
```
Pass the symbol without the slash. The engine converts it to Twelve Data format automatically.

---

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

---

### Multiple pairs at once
```bash
python main.py --pairs XAUUSD EURUSD GBPUSD
```

---

### Only show high-conviction signals (Grade B or above)
```bash
python main.py --min-grade B
```

---

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

---

### Continuous monitoring — updates every 5 minutes
```bash
python main.py --watch
```
Add `--pairs XAUUSD` to watch a single instrument, or `--all` for everything.

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

---

### JSON output (for piping or logging)
```bash
python main.py --pairs XAUUSD --json
python main.py --all --json > signals.json
```

---

## Signal Grades

| Grade | Meaning |
|---|---|
| A+ | Strongest — all timeframes aligned, high confidence |
| A  | Strong signal, minor divergence |
| B  | Good setup, watch for confirmation |
| C  | Weak — for reference only |
| D/F | Noise — best ignored |

---

## Supported Symbols

Pass any symbol without slashes. Examples:

| You type | Pair |
|---|---|
| `XAUUSD` | Gold vs USD |
| `EURUSD` | Euro vs USD |
| `GBPUSD` | British Pound vs USD |
| `USDJPY` | USD vs Japanese Yen |
| `GBPJPY` | GBP vs Japanese Yen |
| `USDCAD` | USD vs Canadian Dollar |
| `AUDUSD` | Australian Dollar vs USD |

Any pair supported by Twelve Data can be used.

---

## Output Explained

```
EUR/USD  │  Price: 1.08423  │  Regime: trending_up  │  Vol: normal

SIGNAL: STRONG BUY  │  Score: +62.4  │  Grade: A  │  Confidence: 74%
Action: Strong buy signal with multi-timeframe alignment...

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** — ranges from -100 (strong sell) to +100 (strong buy)
- **Grade** — summary quality of the signal setup
- **Regime** — `trending_up`, `trending_down`, or `ranging`
- **Trade Setup** — auto-calculated entry, SL, and TP based on ATR