trading-bot/docs/data-fetcher.md

Data Fetcher Design

Initial Goal

Create a Python module/tool that fetches daily candlestick data from the IBKR API for a specific ticker and date range.

The intended example workflow is:

• ticker: SPY;
• date range: 2026-06-01 to 2026-06-30;
• bar size: one trading day;
• fields: open, high, low, close, volume;
• output: one Parquet file named for the ticker, such as SPY.parquet.

Current Skeleton

The first implementation is intentionally small:

• hard-coded ticker: SPY;
• hard-coded range: 2026-06-01 to 2026-06-05;
• hard-coded IBKR Gateway target: 127.0.0.1:4002;
• uses the IBKR API through ib_insync;
• prints fetched candles as CSV-like rows;
• does not write Parquet yet;
• does not expose CLI arguments yet;
• does not define storage paths yet.

Run it with:

mise exec -- uv run python src/trading_bot/data/fetch_ibkr_daily.py

This expects a local IBKR Gateway session to be running and accepting API connections on 127.0.0.1:4002.

Manual test instructions are in manual-test/README.md.

Intended Future Behavior

Later, this tool should accept a ticker and date range, fetch daily candles from IBKR, normalize the schema, and write the result to a ticker-named Parquet file.

Decided storage behavior:

• Parquet files are partitioned by ticker, not by date.
• Each ticker should have its own Parquet file, such as SPY.parquet.

Candidate output schema:

Column	Type	Description
date	date	Trading session date
ticker	string	Asset ticker
open	float	Daily open price
high	float	Daily high price
low	float	Daily low price
close	float	Daily close price
volume	integer	Daily traded volume

Open decisions:

• where raw and normalized data files should live;
• how to handle adjusted versus unadjusted prices;
• how to handle missing sessions and IBKR pacing limits;
• whether to use ib_insync long term or a lower-level IBKR client wrapper.