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

```sh
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](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.