diff --git a/USAGE.md b/USAGE.md index ff24555..04afc33 100644 --- a/USAGE.md +++ b/USAGE.md @@ -6,159 +6,189 @@ pip install -r requirements.txt ``` -Set your Twelve Data API key (or it falls back to the key in `config.py`): +Set your Twelve Data API key (optional — falls back to the key in `config.py`): ```bash -export TWELVE_DATA_API_KEY=your_key_here # Linux/Mac +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 ``` --- -## Basic Syntax +## Running — Terminal (main.py) ``` python main.py [OPTIONS] ``` ---- - -## 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 | +| `--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` (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 | +| `--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 -## Common Examples +| 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 | -### Analyze all major Forex pairs (default) +### 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. ---- - -### Analyze Gold (XAU/USD) +**One pair, full detail** ```bash -python main.py --pairs XAUUSD +python main.py --pairs EURUSD --detail ``` -Pass the symbol without the slash. The engine converts it to Twelve Data format automatically. ---- - -### Gold on the 4-hour chart with full detail +**Gold on the 4-hour chart** ```bash python main.py --pairs XAUUSD --timeframe H4 --detail ``` ---- - -### Multiple pairs at once +**Multiple pairs** ```bash -python main.py --pairs XAUUSD EURUSD GBPUSD +python main.py --pairs EURUSD GBPUSD USDJPY ``` ---- - -### Only show high-conviction signals (Grade B or above) +**High-conviction signals only (grade B+)** ```bash python main.py --min-grade B ``` ---- - -### Top 3 signals across all pairs including crosses +**Top 3 signals across all pairs including crosses** ```bash python main.py --all --top 3 ``` ---- - -### Continuous monitoring — updates every 5 minutes +**Continuous monitoring** ```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) +**JSON output** ```bash -python main.py --pairs XAUUSD --json +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, high confidence | -| A | Strong signal, minor divergence | -| B | Good setup, watch for confirmation | -| C | Weak — for reference only | +| 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 | --- -## 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 + │ EUR/USD │ STRONG BUY │ ░░░░░░░░░░░░░░│███████████████ │ A+ │ 82.3% │ ``` -- **Score** — ranges from -100 (strong sell) to +100 (strong buy) -- **Grade** — summary quality of the signal setup +- **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` -- **Trade Setup** — auto-calculated entry, SL, and TP based on ATR +- **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