---
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

1. Resolve the symbol if unsure: `GET /v1/{asset}/tickers?search=AAP` (or ask).
2. 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.
3. 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`.
4. 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`).