trading-agent/docs/options-phase.md

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.