Add requirements.txt and usage guide

2026-05-04 10:50:20 -04:00
parent 242df24ca7
commit 0a374cfea7
2 changed files with 167 additions and 0 deletions
@@ -0,0 +1,164 @@
+# 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
@@ -0,0 +1,3 @@
+numpy>=1.24
+pandas>=2.0
+requests>=2.28