IB-Dashboard/README.md

IB Dashboard

Interactive Brokers dashboard with a small Flask backend and a vanilla JavaScript frontend.

The project currently uses two data paths:

• TWS / IB Gateway API for live positions and pricing
• IB Flex Web Service infrastructure for durable historical trade retrieval

The Flex path is important for lot history because the socket API execution stream is not reliable enough on its own to reconstruct all historical lots in every setup.

Requirements

• Python 3.8+
• IB Gateway or TWS running locally on port 7496
• For full historical lots: a saved IB Flex Query plus a Flex Web Service token

Install

python -m pip install -r requirements.txt

Run

python backend/app.py

Then open http://127.0.0.1:8000 in your browser.

Current API Endpoints

• GET /api/quotes
• GET /api/positions
• GET /api/lots
• GET /api/executions-debug
• GET /api/flex/status
• POST /api/flex/sync

Flex Query Setup

This app now includes the infrastructure needed to pull historical trade data from IB Flex Web Service and save the raw XML locally. This is the recommended foundation for reconstructing lots regardless of how long ago they were acquired.

1. Create a Flex Query in IB Client Portal

In IB Client Portal:

1. Open Performance & Reports.
2. Go to Flex Queries.
3. Create a new query for trades / executions.
4. Include enough fields to reconstruct lots. At minimum, include:
   • account
   • symbol
   • underlying symbol if available
   • asset / security type
   • trade date / trade time
   • quantity
   • trade price
   • buy/sell side
   • strike
   • expiry
   • put/call
   • multiplier
   • conid if available
   • local symbol / trading class if available
5. Save the query and note the Query ID.

2. Create a Flex Web Service Token

In IB Client Portal:

1. Open the Flex Web Service section.
2. Generate or copy your Flex Web Service token.
3. Keep it secure. Treat it like a credential.

IB reference:

• Flex Web Service overview: https://ibkrcampus.com/campus/glossary-terms/flex-web-service/

3. Configure the App

Use the included .env.example as a template.

Set these environment variables before starting the backend:

• IB_FLEX_TOKEN
• IB_FLEX_QUERY_ID
• IB_FLEX_DATA_DIR

Example PowerShell session:

$env:IB_FLEX_TOKEN="your-token"
$env:IB_FLEX_QUERY_ID="123456"
$env:IB_FLEX_DATA_DIR="data/flex"
python backend/app.py

4. Verify Configuration

Check the Flex status endpoint:

GET /api/flex/status

If configured correctly, it returns:

• configured: true
• the configured query id
• the local data directory
• the latest downloaded file if one exists

5. Trigger a Flex Sync

Trigger a manual download of the saved Flex Query:

POST /api/flex/sync

On success, the backend saves the raw XML file under data/flex/ and returns:

• ok: true
• the saved file path
• the request reference code

What The Flex Infrastructure Does Today

The current implementation provides:

• environment-driven Flex configuration
• a backend Flex client for SendRequest and GetStatement
• local persistence of the downloaded XML files under data/flex/
• Flask endpoints to inspect config and trigger a sync

Files added for this:

• backend/flex_query.py
• .env.example
• data/flex/.gitkeep

What Still Needs To Be Wired In

The Flex Query data is not yet merged into /api/lots.

The next implementation step is:

1. Parse the saved Flex XML.
2. Normalize trades into a local fill ledger.
3. Build lots from that persistent history.
4. Use that ledger as the primary source for buy_time, cost_basis, CAGR, and true open lots.

Notes

• The frontend currently focuses on the lot table.
• The backend still uses the IB socket API for live positions and prices.
• The Flex path is intended to become the historical source of truth for lots.