# name: hfmd-data-analysis description: 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.

# hfmd-data-analysis

Pull price history from https://www.hfmarketdata.io (v1 /v1/bars/{asset}/{ticker}) into a DataFrame and answer "what did this instrument do?" questions with numbers, not impressions.

# When to use

"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"
Any request that needs bars in pandas before something else (feature engineering, correlations, seasonality)
Not for backtests (use hfmd-quick-backtest), continuous futures methodology (hfmd-continuous-futures) or curves (hfmd-term-structure)

# Inputs to confirm with the user

Parameter	Values	Default
asset	`stock` `etf` `crypto` `index` `fx` `futures` (vendor continuous)	infer from the symbol
timeframe	`1min` `5min` `30min` `1hour` `1day`	`1day`
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
adjustment	stock/etf: `UNADJUSTED` `adj_split` `adj_splitdiv` · futures: `contin_UNadj` `contin_adj_ratio` `contin_adj_absolute`	API default (`adj_splitdiv` for stocks)

# Steps

Resolve the symbol if unsure: GET /v1/{asset}/tickers?search=AAP (or ask).
Fetch: python3 scripts/fetch_bars.py --asset stock --ticker AAPL --timeframe 1day --start 2020-01-01 --out aapl.csv
- 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.
Analyse: python3 scripts/analyze.py aapl.csv --plot aapl.png
- 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.
Report the numbers with their window and adjustment; flag missing sessions instead of filling them.

# Examples

bash

# 1. Five years of daily SPY, summary + chart
python3 scripts/fetch_bars.py --asset etf --ticker SPY --start 2021-01-01 --out spy.csv && python3 scripts/analyze.py spy.csv --plot spy.png

# 2. One week of 5-minute bars for TSLA (intraday: naive US/Eastern timestamps)
python3 scripts/fetch_bars.py --asset stock --ticker TSLA --timeframe 5min --start 2025-08-25 --end 2025-08-29 --out tsla_5m.csv

# 3. Vendor continuous crude oil, ratio-adjusted, to parquet
python3 scripts/fetch_bars.py --asset futures --ticker CL --adjustment contin_adj_ratio --start 2015-01-01 --out cl.parquet

# 4. Several tickers → one long DataFrame
python3 scripts/fetch_bars.py --asset stock --ticker AAPL MSFT NVDA --start 2024-01-01 --out mega.csv

# Gotchas

Intraday datetime is naive US/Eastern (exchange time); daily bars are plain dates. Localise before joining with UTC data.
Stocks default to split+dividend adjusted prices; say so when quoting historical levels.
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).
volume for FX/indices may be 0/absent — do not compute volume statistics on them.
Error TICKER_NOT_FOUND usually means the symbol exists in another asset class (e.g. SPY is etf, not stock).