Skip to content

Options workspace implementation — October 20, 2026

Scope: US stock and ETF options, with GLD/SLV featured. Preserve founder authentication, research and learning. Keep automated trading and broker execution off. Build the analysis workspace independently of the retired runtime and its providers.

Product surfaces

  • Overview: featured/saved underlyings, observed quotes with feed and timestamps, saved plans and paper/manual records, clear workflow links.
  • Chain: underlying search, explicit expiry, calls/puts, strike filters, sortable observations, bid/ask quality and missing data. Bound requests and disclose partial results. Selecting a contract sends a leg to the builder.
  • Builder: editable standard-contract legs, strategy templates, expiration payoff and analytically correct bounded/unlimited risk, separate Black–Scholes scenarios with explicit inputs and units. Never present templates or Greeks as validated edge or win probability.
  • Journal: separate paper and self-reported manual records; save/reload/edit/close/review; compute P&L only from entered entry/exit premiums and costs. No automatic fill, mark or broker claim. Export with safe CSV quoting/formula handling.
  • Guide: brief sourced explanations of pricing, risk, assignment and data quality, with links to existing research/learning and official references.

Shared data contract and ownership

qgtm_web/src/lib/options/contracts.ts is the UI/API contract. Root owns this file, shell/navigation/home integration and release work. Frontend agent owns src/components/options/, src/app/options/, and src/lib/options/client.ts. Math/research agent owns src/lib/options/math.ts, its tests and sourced educational material. Backend agent owns qgtm_edge/src/ and qgtm_edge/test/ plus coordinated capability changes. All work is in the fresh integration worktree; only root commits/pushes after coordination so no agent stages another agent's changes.

API

  • GET /api/v1/options/chain?symbol=GLD&expiration=YYYY-MM-DD: ChainResponse. Without exact expiry, use a bounded near-term window and report partial honestly. Parse standard OCC symbols; exclude adjusted/unrecognized roots. Contract multiplier/deliverable is a stated standard-contract assumption, not provider verification. No contract/broker API calls.
  • GET /api/v1/options/quotes?symbols=GLD,SLV,SPY: QuotesResponse, maximum 20 symbols.
  • GET /api/v1/options/workspace: WorkspaceResponse, derived only from authenticated founder identity.
  • PUT /api/v1/options/workspace: { expectedOwner, revision, workspace }; optimistic revision match, 409 conflict, strict bounded validation, same-origin CSRF rules. Return updated WorkspaceResponse. The expectedOwner field only compares identity; never derive the storage owner from the request. A stale tab after an account switch must fail with WORKSPACE_OWNER_CHANGED. Maximum 40 watchlist symbols, 100 plans and 200 journal records; 1–8 standard option legs per record. No delete-all endpoint; ordinary user edits can remove individual saved records.

Private upstream requests are GET-only to allowlisted https://data.alpaca.markets routes, redirects requested in manual mode and every 3xx rejected, bounded response/time/pagination and rate limiting. Use separate MARKETDATA_ALPACA_KEY / MARKETDATA_ALPACA_SECRET environment names and explicit ALPACA_OPTIONS_FEED (default indicative) and stock feed IEX. The user explicitly authorized this read-only connection on October 20, 2026 after the adapter and tests were reviewable. Migration occurs secret-to-secret in the existing hosted workflow. No account, position, order, broker-contract or execution endpoint.

Data errors must remain visible. Indicative quotes are modified derivatives of OPRA, not executable OPRA/NBBO; derived trades are delayed 15 minutes. OPRA needs entitlement. Never silently switch feeds. Missing IV, Greeks, open interest and volume remain null. No realized-vol ×1.2 substitution, invented IV rank, PCR, probability or account balance. New analysis capabilities must not cause legacy providers or order controls to mount.

Verification

Math tests cover payoff extrema/tails, breakevens, short unlimited risk, fees, units, put-call parity, boundary inputs, mixed-expiry rejection and explicit journal P&L. Worker tests cover session/CSRF, founder isolation, revision conflicts, validation, upstream allowlist/pagination/errors/nulls and no execution. Frontend lint/static export and browser flows verify chain/builder/journal round-trips, failures, mobile, existing auth/Research/Learn, every published route and no broker requests. Production verification preserves both existing passwords, Fail closed Pages behavior and trading offline.

User workflow and limits

The home route opens the options overview. Load a chain for GLD, SLV or another US stock/ETF; narrow an explicit expiry/strike window if results are partial. Buy/sell buttons copy a quoted observation into a draft, not an order. Enter the model time explicitly in calendar days (fractional days for intraday analysis); no exchange cutoff or holiday calendar is inferred. Quote age continues updating while a page is open, but refreshing is required to retrieve newer observations.

Templates create structures with blank premiums. Expiration payoffs require a common expiry and include entered opening fees. The separate European Black–Scholes approximation uses explicit rates, yield, time and volatility; it does not model American early exercise, assignment, slippage or margin. Unlimited tails are calculated analytically rather than inferred from the chart boundary.

Save a plan to preserve its legs, assumptions and thesis. Create a paper record for hypothetical tracking or a manual record for a self-reported external trade. Close a journal record by entering each exit premium and closing fee. Only these entered values produce recorded realized P&L; there are no automatic fills, account balances or unrealized marks. CSV export is available for filtered records.

Existing Research, Learning and documentation remain accessible. Former trading pages remain preserved behind an honest offline state; they do not resume the retired engine. No strategy performance, probability of profit, IV rank or backtesting result is claimed by this workspace.

Wheel module — October 20, 2026

Routes under /options/wheel add an options-wheel workflow (cash-secured put → assignment → covered call) on top of the same workspace store and Worker:

  • Dashboard — targets, allocation usage, open-cycle state and next step per symbol, realized results of closed paper/manual cycles. Underlying prices are IEX observations for context only.
  • Screener — loads the bounded chain for one target (puts below spot or calls above spot and basis), computes net premium, period and annualized yield on collateral, breakeven, collateral or if-called return, and shows every check (window, delta band when reported, yield floor, quote quality, allocation, entered earnings date). "Record sale" writes a journal record and a ledger event with the bid as the entered credit; it is not a fill.
  • Cycle ledger — one open cycle per symbol; events sell_put, close_put, put_expired, put_assigned, sell_call, close_call, call_expired, called_away, sell_shares, dividend. Shares, average assignment price, adjusted basis, net premiums, fees, dividends and realized P&L are replayed from the events; impossible sequences stop the replay with a numbered error. Assignments settle at the strike.
  • Universe — per-target allocation, |Δ| band, days-to-expiry window, annualized yield floor, entered earnings date, thesis; selection criteria and candidate verification findings (src/lib/options/wheel-research.ts, pending until the research documents are reviewed).
  • Playbook — the cycle, operator rules with rationale, and sourced mechanics.

Contract: OptionsWorkspace.wheel (optional; targets ≤ 20, cycles ≤ 100, events ≤ 60 per cycle, date-ordered). Validation lives in qgtm_edge/src/options-validation.js; arithmetic and replay in qgtm_web/src/lib/options/wheel.ts with node tests. No probability of profit, unrealized mark, margin or broker data is computed or claimed.