From acddf9135f3ce203a5dc0b12a5d5c855b09e444f Mon Sep 17 00:00:00 2001 From: Aryan Singh Date: Wed, 1 Jul 2026 16:29:40 -0500 Subject: [PATCH] docs: options phase-6 (spreads) plan Co-Authored-By: Claude Opus 4.8 Claude-Session: https://claude.ai/code/session_016DvdRZkyCy9NJpHYDdPqmS --- docs/options-phase.md | 42 ++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 42 insertions(+) create mode 100644 docs/options-phase.md diff --git a/docs/options-phase.md b/docs/options-phase.md new file mode 100644 index 0000000..0d8b233 --- /dev/null +++ b/docs/options-phase.md @@ -0,0 +1,42 @@ +# Phase 6 (planned) — Options trading + +Prereq met: all 3 paper accounts are **options Level 3** (long calls/puts + spreads). +Build in two increments; ship 6a first. + +## 6a — Single-leg long calls/puts +The smallest coherent options feature: an agent expresses a directional thesis by buying a +**call** (bullish) or **put** (bearish) instead of / alongside shares. + +**Schema** (`agents/schemas.py`) +- Add `instrument: "equity" | "option"` to `Pick` (default equity — nothing else changes). +- Option fields: `option_right: "call"|"put"`, `expiry: date`, `strike: float`, and a derived + OCC `contract_symbol` (e.g. `AAPL260717C00300000`). Validator: expiry in the future, strike > 0. + +**Data tools** (`tools/options.py`, added to `build_toolset`) +- `get_option_chain(underlying, around="atm", dte=30..45)` → nearby strikes/expiries with + bid/ask/last/IV/OI. Backend: alpaca-py `OptionHistoricalDataClient` / option chain endpoint. +- `get_option_quote(contract_symbol)` → latest premium. +- Prompt guidance: default ~30–45 DTE, near-the-money, adequate open interest/volume. + +**Execution** (`execution/broker.py`, `guardrails.py`, `run_market_open.py`) +- `submit_option_order(contract_symbol, qty_contracts, side, limit_price)` — Alpaca + `LimitOrderRequest` with the OCC symbol. ⚠️ **Verify** Alpaca supports bracket/OTO on options; + if not, place entry + a separate take-profit limit (and optional stop) rather than a bracket. +- Guardrails: size by **premium × 100 × contracts** vs equity cap; `max_contracts`, + `max_premium_pct`, min DTE / max DTE, liquidity floor. Whole contracts only. + +**State/dashboard** +- `orders`/`positions` gain `instrument_type` + contract columns; dashboard shows options + positions distinctly (premium, expiry, right/strike, Greeks if available). + +**Verification**: place one live long call + one long put during market hours; confirm fills, +position, and that the chosen exit mechanism works. + +## 6b — Spreads / multi-leg (later) +Vertical spreads (defined risk), greeks-aware strike selection, multi-leg order submission. +Much larger surface (leg pairing, spread margin, assignment/expiry handling) — do after 6a is solid. + +## Open risks to resolve during build +- Alpaca options **bracket/OTO** support (drives the exit design above). +- Options market-data availability/latency on the paper plan. +- Expiry & assignment handling for positions held to/near expiration.