spb/hfmarketdata

1---2name: hfmd-data-analysis3description: Fetch historical OHLCV bars (stocks, ETFs, futures, crypto, indices, FX; 1-minute to daily) from HF Market Data into pandas and produce summary statistics, return/volatility/drawdown analysis and charts. Use when the user asks to analyse, describe, chart or export price history for a symbol or a basket.4---56# hfmd-data-analysis78Pull price history from `https://www.hfmarketdata.io` (v1 `/v1/bars/{asset}/{ticker}`) into a DataFrame and9answer "what did this instrument do?" questions with numbers, not impressions.1011## When to use1213- "Show me AAPL daily since 2020 and summarise it", "how volatile was BTC in 2024?", "export SPY 5-minute bars for last week to CSV"14- Any request that needs bars in pandas before something else (feature engineering, correlations, seasonality)15- Not for backtests (use `hfmd-quick-backtest`), continuous futures methodology (`hfmd-continuous-futures`) or curves (`hfmd-term-structure`)1617## Inputs to confirm with the user1819| Parameter | Values | Default |20|---|---|---|21| asset | `stock` `etf` `crypto` `index` `fx` `futures` (vendor continuous) | infer from the symbol |22| timeframe | `1min` `5min` `30min` `1hour` `1day` | `1day` |23| start / end | `YYYY-MM-DD` (intraday: keep ranges short — one day of 1-min bars ≈ 390 rows RTH, 1 440 for crypto) | last 5 years for daily |24| adjustment | stock/etf: `UNADJUSTED` `adj_split` `adj_splitdiv` · futures: `contin_UNadj` `contin_adj_ratio` `contin_adj_absolute` | API default (`adj_splitdiv` for stocks) |2526## Steps27281. Resolve the symbol if unsure: `GET /v1/{asset}/tickers?search=AAP` (or ask).292. Fetch: `python3 scripts/fetch_bars.py --asset stock --ticker AAPL --timeframe 1day --start 2020-01-01 --out aapl.csv`30   - paginates automatically (keyless max 5 000 rows/request) and prints the exact range received — never assume the range you asked for is the range you got.313. Analyse: `python3 scripts/analyze.py aapl.csv --plot aapl.png`32   - prints: rows, first/last bar, CAGR, annualised volatility, Sharpe (rf = 0), max drawdown (with dates), best/worst bar, skew/kurtosis, gap count, monthly return table; writes a price + drawdown chart if `--plot`.334. Report the numbers with their window and adjustment; flag missing sessions instead of filling them.3435## Examples3637```bash38# 1. Five years of daily SPY, summary + chart39python3 scripts/fetch_bars.py --asset etf --ticker SPY --start 2021-01-01 --out spy.csv && python3 scripts/analyze.py spy.csv --plot spy.png4041# 2. One week of 5-minute bars for TSLA (intraday: naive US/Eastern timestamps)42python3 scripts/fetch_bars.py --asset stock --ticker TSLA --timeframe 5min --start 2025-08-25 --end 2025-08-29 --out tsla_5m.csv4344# 3. Vendor continuous crude oil, ratio-adjusted, to parquet45python3 scripts/fetch_bars.py --asset futures --ticker CL --adjustment contin_adj_ratio --start 2015-01-01 --out cl.parquet4647# 4. Several tickers → one long DataFrame48python3 scripts/fetch_bars.py --asset stock --ticker AAPL MSFT NVDA --start 2024-01-01 --out mega.csv49```5051## Gotchas5253- Intraday `datetime` is naive **US/Eastern** (exchange time); daily bars are plain dates. Localise before joining with UTC data.54- Stocks default to split+dividend adjusted prices; say so when quoting historical levels.55- Keyless mode has low hourly limits: 30 requests/hour, 5 000 rows/request. Set `HFMD_API_KEY` (free API key, 120 req/min, 50 000 rows/request) before pulling intraday history; higher limits are granted on request by e-mail to contact@spboucher.ai (also free).56- `volume` for FX/indices may be 0/absent — do not compute volume statistics on them.57- Error `TICKER_NOT_FOUND` usually means the symbol exists in another asset class (e.g. `SPY` is `etf`, not `stock`).58