Requirements: TradingAgents Options Module

Defined: 2026-03-29 Core Value: Agents produce actionable multi-leg options recommendations with transparent, educational reasoning

v1 Requirements

Requirements for initial release. Each maps to roadmap phases.

DATA-01: System can retrieve full options chain (strikes, expirations, bid/ask, volume, OI) via Tradier API
DATA-02: System can retrieve options expirations and available strikes for any ticker via Tradier API
DATA-03: System displays 1st-order Greeks (Delta, Gamma, Theta, Vega, Rho) from ORATS via Tradier
DATA-04: System displays implied volatility per contract (bid_iv, mid_iv, ask_iv, smv_vol)
DATA-05: System can filter options chains by DTE range (e.g., 30-60 DTE for income strategies)
DATA-06: System calculates 2nd-order Greeks (Charm, Vanna, Volga/Vomma) via blackscholes library
DATA-07: System can retrieve real-time streaming Greeks and quotes via Tastyworks DXLink WebSocket
DATA-08: System integrates Tradier and Tastyworks as new vendors in the existing data routing layer

VOL-01: System calculates IV Rank using 52-week IV high/low for any ticker
VOL-02: System calculates IV Percentile using 252-day lookback of IV readings
VOL-03: System estimates Probability of Profit (PoP) for each recommended strategy
VOL-04: System constructs volatility surface via SVI parametric fitting across strikes and expirations
VOL-05: System implements TastyTrade rules engine: IVR-based strategy selection (IVR >= 50% = sell premium, IVR < 30% = buy premium)
VOL-06: System implements TastyTrade position management rules: 45 DTE entry, 21 DTE management, 50% profit target, 2x credit stop-loss
VOL-07: System calculates Volatility Risk Premium (VRP) by comparing IV to historical/realized volatility

GEX-01: System computes Net Gamma Exposure (GEX) across all strikes from open interest data
GEX-02: System identifies Call Wall and Put Wall levels (max positive/negative gamma strikes)
GEX-03: System identifies Gamma Flip zone (where cumulative GEX changes sign) and Vol Trigger level
GEX-04: System classifies market regime as positive gamma (mean-reverting) or negative gamma (trending)
FLOW-01: System detects unusual options activity by comparing volume to historical average and open interest
FLOW-02: System classifies flow direction (bullish/bearish) based on trade side, strike location, and OI changes

STRAT-01: System recommends multi-leg options strategies (verticals, iron condors, straddles, strangles, butterflies, jade lizards, diagonals, calendars)
STRAT-02: System selects strategy type based on IV environment (high IV = credit strategies, low IV = debit strategies) and directional bias
STRAT-03: System outputs specific contract recommendations with exact strikes, expirations, and leg quantities
STRAT-04: System outputs alternative strike/expiration ranges when exact contracts are illiquid or close to thresholds
STRAT-05: System calculates max profit, max loss, and breakeven points for each recommended strategy
STRAT-06: System provides transparent reasoning chain showing why each strategy was selected (educational)

AGENT-01: Volatility analysis agent evaluates IV Rank, IV Percentile, VRP, vol surface, and skew
AGENT-02: Greeks analysis agent evaluates 1st and 2nd-order Greeks and their implications for position risk
AGENT-03: Options flow / unusual activity agent identifies smart money signals and flow direction
AGENT-04: Gamma exposure agent analyzes dealer positioning, gamma walls, regime, and structural levels
AGENT-05: Strategy selection agent recommends specific multi-leg strategies based on all analysis inputs
AGENT-06: Position sizing agent calculates risk/reward profiles (max P/L, breakevens, PoP) for recommended strategies
AGENT-07: Options debate phase runs bull/bear debate on the options thesis with configurable rounds
AGENT-08: Options portfolio manager synthesizes all analysis and debate into final recommendation with reasoning
AGENT-09: All options agents follow existing create_*() factory pattern and write to shared AgentState
AGENT-10: Composite Options Score (0-5) computed from IV rank, GEX regime, flow signals, and vol skew

INT-01: Options analysis team runs as parallel section in the LangGraph StateGraph alongside existing stock analysis
INT-02: Options agents are configurable and optional (can be enabled/disabled like existing analysts)
INT-03: CLI updated to support options analysis mode with interactive options-specific prompts
INT-04: Deterministic validation layer checks strategy structural validity, risk limits, and liquidity before output
INT-05: All deterministic math (Black-Scholes, GEX, 2nd-order Greeks, P/L) in pure Python module, not LLM tool calls

Deferred to future release. Tracked but not in current roadmap.

EDATA-01: Historical IV surface storage for backtesting and regime comparison
EDATA-02: 0DTE strategy analysis with sub-minute data refresh
EDATA-03: Multi-ticker batch analysis for portfolio-level options scanning

ADV-01: Portfolio-level Greeks aggregation across multiple positions
ADV-02: Custom volatility models (Heston, local vol) for exotic pricing
ADV-03: Options backtesting engine with historical vol surfaces and fill simulation

Explicitly excluded. Documented to prevent scope creep.

Feature	Reason
Order execution / broker integration	Analysis-only mandate; regulatory complexity
Real-time streaming dashboard	Batch `propagate()` architecture; streaming is for data freshness only
0DTE strategy support	Requires real-time infrastructure not yet in place
Historical IV surface database	Requires ORATS subscription or building own historical DB
Options backtesting engine	Separate domain requiring historical vol surfaces and fill simulation
Custom vol models (Heston, local vol)	Over-engineering; SVI sufficient for equity options
Portfolio-level Greeks aggregation	No position state in analysis-only module
Mobile/web UI	CLI and Python API only

Which phases cover which requirements. Updated during roadmap creation.

Coverage:

Requirements defined: 2026-03-29 Last updated: 2026-03-29 after roadmap creation