Option AI Pro 2.0

Option AI Pro 2.0 is a small FastAPI + React toolchain that scans for options strategies using the Option Samurai API, applies a custom scoring model to iron condor candidates, and lets you push multi-leg trades to Interactive Brokers (TWS/IB Gateway) directly from the web UI.

Features

• Strategy scanning against Option Samurai with pagination and custom filter templates (backend/settings/strategyFilters.json).
• Risk/edge scoring for iron condors using liquidity, IV rank, expected return, and stock fundamentals (backend/modules/score.py).
• Trade orchestration via IBKR: build OCC contracts, submit limit orders, list/cancel open trades (backend/modules/ibkr_service.py).
• React dashboard (Vite + MUI) with sortable grid, trade drawer, and trade history drawer.
• Local caching of scan results in frontend localStorage and JSON output at backend/data/scored.json.

Project structure

• backend/
  • api/endpoints.py — FastAPI app and IBKR endpoints.
  • modules/ — scanner, scoring, and IBKR service helpers.
  • settings/ — API keys (api_keys.json), filter templates, and config helpers.
  • data/ — sample scan data and latest scored output.
• frontend/ — Vite/React client (MUI, DataGrid, notistack).

Prerequisites

• Python 3.11+ (virtual env recommended)
• Node.js 20+ with pnpm (or npm/yarn if preferred)
• Access to Option Samurai API (Bearer token)
• Running Interactive Brokers TWS/IB Gateway with API enabled (default 127.0.0.1:7497, paper or live)

Backend setup

cd backend
python -m venv .venv
. .venv/Scripts/activate  # on Windows PowerShell: .venv\Scripts\Activate.ps1
pip install -r requirements.txt

Configure API keys at backend/settings/api_keys.json:

{
  "option_samurai": "YOUR_OPTION_SAMURAI_BEARER_TOKEN",
  "ibkr": "(optional placeholder)"
}

The repo currently includes a placeholder token; replace it with your own before running.

Start the API server (defaults to port 8000):

uvicorn api.endpoints:app --reload --host 0.0.0.0 --port 8000

Handy CLI sanity check (prints ranked iron condors to stdout):

python main.py

Frontend setup

cd frontend
pnpm install   # or npm install / yarn
pnpm dev       # serves at http://localhost:5173

The frontend expects the backend at http://localhost:8000 (set in src/App.jsx).

Key API routes (FastAPI)

• GET /api/iron-condor — fetch and score iron condor opportunities.
• GET /ibkr/connect — open/verify IBKR session.
• POST /ibkr/submit-position — submit multi-leg position; body { legs: [...], strategy_size: int }.
• POST /ibkr/cancel-orders — cancel by contract locals; body { contracts: ["AAPL240517C175"] }.
• GET /ibkr/active-strategies — current option positions.
• GET /ibkr/all-trades — combined open/completed trades for the trade history drawer.

Scoring model (iron condor)

• Normalizes expected return, max loss, liquidity, delta, IV rank, and entry cost.
• Blends with stock fundamentals/growth/technical scores into a weighted composite (see backend/modules/score.py).
• Persists enriched results to backend/data/scored.json for reuse or debugging.

IBKR notes

• Uses ib_insync with default host=127.0.0.1, port=7497, clientId=1 (adjust in IBKRService).
• Contracts built from OCC strings (e.g., AAPL240517C175) via build_option_contract.
• Limit prices auto-derived from bid/ask spread (ask - 0.33*spread for sells, bid + 0.33*spread for buys).

Troubleshooting

• 401/403 from /api/iron-condor: verify the Option Samurai bearer token and that strategyFilters.json contains the strategy key you request.
• IBKR not connecting: ensure TWS/IBG API access is enabled and the port matches IBKRService settings.
• Frontend CORS issues: backend allows http://localhost:5173 by default; update allow_origins in api/endpoints.py if needed.

Next steps

• Add .env handling instead of committing api_keys.json.
• Expand scoring to additional strategies (templates live in settings/strategyFilters.json).
• Add unit tests around modules/score.py and IBKR order construction.