Initial hello world IBKR API connection.

docs/README.md

@@ -10,6 +10,10 @@ Build a Python-based trading bot that uses machine learning to determine which a
 
 Responsible for acquiring and storing market, asset, and any future feature data needed for model training and evaluation.
 
+The first planned tool is an IBKR daily candle fetcher. It should fetch open, high, low, close, and volume data for a ticker and date range, then eventually persist that data to a ticker-named Parquet file. See [data-fetcher.md](data-fetcher.md).
+
+Parquet files are partitioned by ticker, not by date.
+
 Open decisions:
 
 - asset universe;
@@ -72,7 +76,7 @@ Possible scope:
 ## Near-Term Priorities
 
 1. Decide the initial project package structure.
-2. Add Python packaging and dependency management.
+2. Keep Python packaging and dependency management current with `uv`.
 3. Add a minimal configuration system.
 4. Define interfaces for data collection, model artifacts, and broker execution.
 5. Add tests for the core trading decision boundaries before connecting real broker behavior.

docs/data-fetcher.md

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

docs/manual-test/README.md

@@ -0,0 +1,64 @@
+# Manual Test Instructions
+
+## IBKR Daily Fetcher Skeleton
+
+This test checks the first hard-coded IBKR data fetcher without writing any data files.
+
+The fetcher currently requests:
+
+- gateway: `127.0.0.1:4002`;
+- client id: `101`;
+- ticker: `SPY`;
+- date range: `2026-06-01` to `2026-06-05`;
+- bar size: `1 day`;
+- data type: `TRADES`;
+- regular trading hours only;
+- output: printed CSV-like rows.
+
+## Prerequisites
+
+1. Start IBKR Gateway.
+2. Log in to the paper trading account.
+3. Confirm API access is enabled in IBKR Gateway.
+4. Confirm the API socket port is `4002`.
+5. Confirm no other API client is already using client id `101`.
+6. Sync Python dependencies:
+
+```sh
+mise exec -- uv sync
+```
+
+## Run The Test
+
+From the repository root, run:
+
+```sh
+mise exec -- uv run python src/trading_bot/data/fetch_ibkr_daily.py
+```
+
+## Expected Output
+
+The tool should first print the hard-coded request range and connection target:
+
+```text
+Fetching SPY daily candles from 2026-06-01 to 2026-06-05
+Connecting to IBKR Gateway at 127.0.0.1:4002 with client id 101
+```
+
+If the request succeeds, it should then print a header and one row per returned trading day:
+
+```text
+date,ticker,open,high,low,close,volume
+2026-06-01,SPY,...
+```
+
+Exact prices and volume depend on what IBKR returns.
+
+## Common Issues
+
+- Connection refused: IBKR Gateway is not running, the port is not `4002`, or API access is disabled.
+- Client id already in use: change `IBKR_CLIENT_ID` in the fetcher or disconnect the other client.
+- No historical bars: confirm the account has market data permissions and that IBKR accepts the requested historical data range.
+- Pacing or permission errors: note the IBKR error message before changing the request.
+
+This skeleton does not write Parquet files yet.