Option Chaser

Long Call scenario optimizer. Given YOUR scenario (target price + target date), it scans the current option chain, filters for tradeability, valuates every qualifying Long Call with Black-Scholes under your scenario, bands candidates by Delta (conservative / balanced / aggressive), and prints a deterministic plain-text report with price-ceiling guidance.

It does NOT predict stocks, judge your scenario, estimate probabilities, or give investment advice. Same snapshot + same params = byte-identical output.

Install

pip install -e .

Run (online; saves a snapshot under snapshots/)

option-chaser NVDA --target-price 220 --target-month 2026/9

Re-run offline from a snapshot

option-chaser NVDA --target-price 220 --target-month 2026/9 \
    --snapshot snapshots/NVDA_xxxx.json

Strategies

--strategy long-call          (default) bullish single leg
--strategy long-put           bearish single leg
--strategy bull-call-spread   bullish debit vertical (exhaustive same-expiry pairs)
--strategy bear-put-spread    bearish debit vertical

Direction guard: bullish strategies need target > spot, bearish need target < spot (override with --force). Band-first candidates include a price×date P/L matrix (11 price rows spanning 4 bold anchor prices — spot, target, overshoot (target ±10%), adverse (spot ∓10%) — plus evenly-interpolated rows in between; × up to 7 date columns; add --matrix-all for every candidate).

Removed in v2

--min-days-after / --delay-days and the stress-test section are gone —
the matrix supersedes them.

Key flags

--target-month YYYY/M the scenario's target month; 2028/1, 2028/01, 28/1 and
                      28/01 all mean the same month. Expiries are chosen from
                      the chain around that month's third Friday (see below).
--iv-shifts CSV       IV scenarios, default -0.2,0,0.2 (0 always included)
--min-return X        L3 price ceiling = baseline value / (1+X)
--max-spread-pct / --spread-floor   quality-flag threshold, not a hard
                      gate — open interest, volume, and spread width no
                      longer exclude candidates, they set the ⚠ flag
                      shown on each candidate — spec #61
--delta-bands A,B     |Delta| banding thresholds, default 0.35,0.65
--matrix-all          matrix on every candidate
--md PATH             also write the report to a file

Snapshots are schema v2 (calls + puts). v1 snapshots must be re-fetched.

Reading the report

• Filter stats: how many contracts got cut from the full chain, and why (quote validity / IV solvable). Liquidity and spread width no longer cut candidates — they show up as a per-candidate ⚠ warning instead (spec #61). Which expiries get analysed is decided beforehand by the selection rule, not by a filter.
• Single-leg candidates come in three Delta bands (conservative / balanced / aggressive); spreads are a single ranked list.
• Each candidate: Bid/Mid/Ask (with per-contract dollar amounts), Breakeven, three IV-scenario valuations (value + P/L + return), and a buy-price ceiling guide (flagged if the current Ask exceeds it).
• Resilience vector (new): 7 fixed stress scenarios — no-move, half-way, mostly-there, arrives 30 days late, arrives 90 days late, most-conservative IV, and a natural-fill (Ask/Bid) entry — all priced on a Mid cost basis except S7 (natural fill, taker price). The reported worst-case return is simply the lowest of those 7 numbers: a transparent worst-of-a-fixed-scenario-set value, not a statistical inference. Also reported: a scenario-completion curve (return at 0/25/ 50/75/100% of the way from spot to target), a breakeven threshold (a suffix condition — once completion clears this threshold, any higher completion also doesn't lose money), a no-move retention ratio (leftover value / entry cost if the underlying never moves), and execution friction (as a percentage, plus the absolute dollar amount per share).
• P/L matrix: rows = underlying price (the 4 bold anchor rows above, plus interpolated rows), columns = date (* = target date, last column = expiry payoff), cell = Mid-entry return %.

Known model limitations (read before trusting the numbers)

• No dividend adjustment (q=0): high-yield underlyings make call values look systematically optimistic and put values look conservative; deep-ITM, long-dated contracts are hit hardest — the "floor" line is the built-in guard against this.
• IV is held constant through the target date; realized IV will differ — the ±20% IV scenarios are the hedge for that.
• Quotes are yfinance-delayed data (~15 min); zero-volume contracts get a "stale quote" flag.
• The delayed-arrival scenarios (arrives 30/90 days late) assume a linear price path from spot to target between now and the delayed arrival date — a modeling assumption, not a market forecast.
• Estimates are not guaranteed fills; nothing here is investment advice.

Web app

The interactive web app is a separate Vite + React (TypeScript) frontend backed by a Python serverless API (FastAPI, imports this same option_chaser engine directly) — see docs/deploy-vercel.md for the full architecture, Vercel deployment steps, and connecting Neon Postgres for persistence.

npm install
npm run dev                # frontend dev server, http://localhost:5173
PYTHONPATH=. .venv/bin/python -m pytest    # backend/API tests

This is the beginning of the README. Read the rest at the original. Read the full README ↗