fetch-quotes

# Fetch Quotes — Free-First Data Source Primary data source: **yfinance** (free, no account, no API key). Automatic upgrade to **local MT5 terminal** when it is running and logged in. Pick this when you need OHLCV bars or a current quote for any symbol and don't want to maintain credentials. ## Invocation ```text /tradecraft:fetch-quotes <SYMBOL> [TIMEFRAME] [BARS] [SOURCE] [CHART] # Examples /tradecraft:fetch-quotes XAUUSD # defaults: H1, 200 bars, auto /tradecraft:fetch-quotes US30 H4 /tradecraft:fetch-quotes EURUSD M15 100 free /tradecraft:fetch-quotes BTCUSD D1 300 auto chart ``` - `<SYMBOL>` — e.g. `XAUUSD`, `US30`, `EURUSD`, `BTCUSD`. Broker suffixes (`XAUUSDm`, `US30.cash`) are normalized automatically. - `[TIMEFRAME]` — `M1 M5 M15 M30 H1 H4 D1 W1`. Default `H1`. (`H4` via `--source free` is resampled from yfinance 1-hour bars.) - `[BARS]` — number of bars to return. Default `200`. - `[SOURCE]` — `auto` (default), `free` (yfinance only), `mt5` (MT5 only, fails if unavailable). - `[CHART]` — pass `chart` or a PNG path to render a line chart. ## What Claude Should Execute First-time setup (free path only): ```shell pip install -r "${CLAUDE_PLUGIN_ROOT}/scripts/requirements.txt" ``` Optional, Windows only, for broker-exact pricing: ```shell pip install MetaTrader5 ``` Then, per invocation, shell out to the fetcher: ```shell python "${CLAUDE_PLUGIN_ROOT}/scripts/fetch_quotes.py" \ --symbol <SYMBOL> \ --timeframe <TIMEFRAME> \ --bars <BARS> \ --source <SOURCE> \ [--chart <path.png>] ``` The script writes JSON to stdout. Parse it; if `source == "yfinance"`, remind the user that prices may be ~15 min delayed for indices and futures. ## Output Contract ```json { "source": "yfinance | mt5", "symbol": "XAUUSD", "broker_symbol": "XAUUSDm | GC=F", "timeframe": "H1", "bars": [ {"time": "2026-04-23T10:00:00+00:00", "open": 2340.1, "high": 2343.5, "low": 2339.8, "close": 2342.7, "volume": 1234} ], "latest": { "bid": 2342.70, "ask": 2342.85, "spread": 0.15, "time": "2026-04-23T10:58:12+00:00" }, "point_value": 0.01, "note": "Only present on yfinance path - explains delay and missing L1 depth.", "chart_path": "out.png" } ``` - `source` tells you which feed answered. Always check it before reporting a price. - `broker_symbol` is the actual ticker the feed used after symbol normalization — helpful when a user's broker uses a suffix. - `spread = 0` on yfinance because Yahoo gives no L1 depth. Don't treat that as real spread. - Times are ISO-8601 UTC (`+00:00`). ## Source Cascade | `--source` | Behavior | When to use | |---|---|---| | `auto` (default) | MT5 if `MetaTrader5` imports AND `initialize()` succeeds; otherwise yfinance | Any machine — best data available | | `free` | yfinance only — never touches MT5 | Zero credentials, portable, demo/CI | | `mt5` | MT5 only — fails fast if terminal isn't up | You know MT5 is running and want broker-exact prices; CI gate against silent fallback | ## Symbol Mapping (canonical → yfinance ticker, MT5 variants tried) | Canonical | yfinance | MT5 variants attempted | |---|---|---| | XAUUSD | `GC=F` | XAUUSD, XAUUSDm, XAUUSD.r, GOLD | | US30 | `^DJI` | US30, US30.cash, US30m, DJ30, DOWJ30 | | US500 | `^GSPC` | US500, SPX500, US500m, US500.cash | | US100 | `^NDX` | NAS100, US100, USTECm, NAS100.r | | EURUSD | `EURUSD=X` | EURUSD, EURUSDm, EURUSD.r | | GBPUSD | `GBPUSD=X` | GBPUSD, GBPUSDm | | USDJPY | `USDJPY=X` | USDJPY, USDJPYm | | BTCUSD | `BTC-USD` | BTCUSD, BTCUSDm, BTCUSD.cash | | ETHUSD | `ETH-USD` | ETHUSD, ETHUSDm | | Unmapped | (pass-through) | (pass-through) | Unmapped symbols are forwarded verbatim to both feeds — handy for less common instruments, but verify the ticker on the vendor side. ## Known Limits of the Free Path - **Delay** — Yahoo indices and futures are typically ~15 min delayed. FX and crypto quotes are close to real-time. - **No L1 depth** — `bid == ask == close`. Don't trust `spread` from this source. - **Gold quoted as `GC=F`** (COMEX continuous front-month futures). For FX-spot XAUUSD use `--source mt5` or override the mapping. - **H4 is resampled** from 1-hour bars when on yfinance — calendar-aligned 4h buckets, not the broker's session-aligned H4 candles. - **Rate limits** — Yahoo throttles heavy polling. For monitoring loops, cache at the bar-close boundary. ## Skip Conditions - `--source mt5` but no terminal running → returns error JSON with exit code 2. Do not fall through silently; surface the error so the user can decide. - Symbol not resolvable on either side → exit code 4. Check the spelling and whether the broker quote differs. ## Worked Examples ### Gold, auto source, default bars ```shell python "${CLAUDE_PLUGIN_ROOT}/scripts/fetch_quotes.py" --symbol XAUUSD --timeframe H1 --bars 50 # -> source: "mt5" if terminal is up, otherwise "yfinance" (GC=F) ``` ### US30, free only ```shell python "${CLAUDE_PLUGIN_ROOT}/scripts/fetch_quotes.py" --symbol US30 --timeframe H4 --bars 120 --source free # -> source: "yfinance", broker_symbol: "^DJI" ``` ### Gold with chart ```shell python "${CLAUDE_PLUGIN_ROOT}/scripts/fetch_quotes.py" --symbol XAUUSD --timeframe H1 --bars 200 --chart /tmp/gold-h1.png # -> writes /tmp/gold-h1.png; response JSON carries "chart_path" ``` Claude can then read the PNG with its vision capability for visual pattern analysis (same pattern used by `mt5-chart-browser`). ## See Also - `pair-analyze` — the generic combination that calls `fetch-quotes` as Step 0 - `analyze-gold` / `analyze-us30` — pre-configured wrappers that go through this skill for data - `mt5-integration` — deeper MT5 integration guide (broker-exact only) - `mt5-chart-browser` — read PNG charts once they are generated - `xtrading-analyze` — full multi-agent scan (assumes a more elaborate local pipeline)