Initial hello world IBKR API connection.

2026-07-25 22:19:31 +03:00
parent 470e243526
commit 8d3e663e71
11 changed files with 456 additions and 3 deletions
@@ -0,0 +1,64 @@
+# 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.