Options Backtesting

Options backtesting

An equity position ends when you sell it. An options position can end five ways, and you control one of them.

A backtest that computes max(S − K, 0) at expiry has modelled rows two and three and silently assumed the others never happen. This skill is about what that costs.

For pricing a single option, Greeks scaling, and vol-surface fitting, go to ../derivatives-pricing/SKILL.md — including its §6, which carries the measured evidence that lastPrice is unusable (54.6% of a live SPY call chain quoted outside its own bid-ask).

0. 🚨 Almost nothing in Python backtests options correctly

✅ Fetched from the PyPI JSON API on 2026-09-04. Of every package on PyPI (the full index, 884,814 names, was swept), exactly one models assignment, exercise, settlement and margin: QuantConnect's LEAN. One more is a genuine multi-leg backtester that explicitly disclaims assignment. Everything else is a pricer, a payoff plotter, or a live-broker SDK.

🚨 optopsy relicensed from GPL-3.0 to AGPL-3.0 on 2026-02-23. ✅ From the repository's own commit history (gh api, fetched 2026-09-05): the LICENSE file was last changed by the commit "chore: switch license from GPL-3.0 to AGPL-3.0", and the LICENSE on main reads GNU AFFERO GENERAL PUBLIC LICENSE Version 3. AGPL's network clause reaches SaaS use — this is load-bearing if you deploy. Anything you remember about this package's licence from before 2026-02-23 is stale, and a GPL-3.0 claim is not wrong, it is seven months out of date.

✅ It is one repository, not a dead fork and a live one. michaelchu/optopsy (created 2017-09-17) redirects to goldspanlabs/optopsy — a transfer, with 1,470 stars and a last commit on 2026-04-02. An earlier draft of this file called the michaelchu repo dead since 2021; the GitHub API says otherwise. PyPI's license field is None with no classifier, so package metadata will not tell you any of this — only the file and the commit log do.

✅ A keyword scan of optopsy's own README: margin 0 hits, exercise 0, settle 0, American/European 0, multiplier 0. assignment appears once, in a disclaimer. Its data contract has no OSI symbol, no multiplier and no deliverable field — assignment modelling is structurally impossible there, not merely unimplemented.

🔑 LEAN's margin is position-group based, and only if you submit the combo. A long ITM call ($29,150) plus a short OTM call ($101,499) margins at $0 as a submitted spread and as naked legs otherwise. ⚠️ Secondhand from QuantConnect's docs. Its DefaultOptionAssignmentModel scans hourly, considering American exercise within 4 days of expiry.

🔴 pip install py_vollib is now wrong. ✅ py-vollib 1.0.12 is an empty shim — its own description says it "intentionally contains no library code" — ✅ the wheel is 1,484 bytes. Use vollib. And py_vollib_vectorized (last released 2021-02-28) works by monkey-patching the now-deprecated namespace. See ../../fin-libraries/skills/lib-vollib/SKILL.md.

🔴 quantconnect-lean on PyPI is a squatted placeholder (v0.1.0, 2020, "reserved for future use"). The real CLI is lean. optionsuite is not on PyPI at all (404) — it is GitHub-only.

1. 🚨 Early assignment is not an edge case on a dividend payer

✅ Measured with scripts/option_lifecycle.py, verified against QuantLib 1.43 to 9.73e-06. American vs European call, S=100, K=90, 30 days:

🔑 At q=0 the premium is exactly zero — a non-dividend-paying American call is never exercised early. That is why this trap is invisible until your universe contains a payer, and then it is everywhere.

🚨 At q≥10% the American value collapses to intrinsic: the option should be exercised immediately. European pricing says 8.8569 against a true 10.00 — understating it by 11.4%.

The rule a backtest needs: a rational holder exercises a call early to capture a dividend whenever the call's remaining time value is less than the dividend. In the script's covered-call example that is time value 0.4586 against a dividend of 1.20 — assignment is not a risk there, it is the expected outcome.

2. 🚨 The assignment error changes sign with the path

This is why it cannot be calibrated away with a haircut. ✅ Same script — a covered call assigned at the ex-dividend date, against a backtest that keeps the position open:

In the last row the backtest reports a $300 loss on a position that actually made $7,500. The shares were called away before the drawdown; the backtest kept holding them down.

A backtest carrying an already-assigned position forward is not paying a fixed cost. It is trading a position that does not exist, and the result is noise with no stable sign — which is far worse for a research process than a known bias.

3. 🚨 Pin risk — one cent decides your Monday

✅ Short 10 calls struck at 100, at the closing bell:

⚠️ And auto-exercise is a default, not a guarantee. A holder may submit contrary instructions — choosing not to exercise an ITM option, or exercising one that is OTM — so the short side's exposure is genuinely unknown until notices arrive.

A backtest cannot resolve pin risk, and should not pretend to. Treat any position open at expiry within a cent of the strike as an unmodelled exposure and report how often it happened. A strategy whose returns depend on that resolution going your way has not been backtested.

4. Multi-leg positions are one position, not N options

A spread's legs do not fill together, do not get assigned together, and do not margin separately.

• Legging risk. A four-leg iron condor filled at four separate mids is a price nobody could have traded. Model the spread's own bid-ask, or state that you assumed simultaneous mid fills.
• Partial assignment. The short leg of a vertical can be assigned while the long leg is still open, which converts a defined-risk position into a stock position overnight. This is the single most common way a "defined risk" backtest understates its worst day.
• Early close of one leg changes the margin requirement of the whole position, not a quarter of it.

5. Margin decides whether the position was ever possible

Three different regimes, and a backtest that assumes the wrong one is sizing an account that cannot exist:

⚠️ This library does not carry verified per-strategy margin formulas or current broker thresholds — get those from your broker's own margin documentation. Reg T basics that apply across equities are in ../us-market-rules/SKILL.md §4.

🔑 The one structural fact worth encoding: margin is a property of the position group, not of the legs. LEAN's numbers above make it concrete — the same two contracts require $0 as a submitted spread and ~$130,649 as separately-submitted legs. A backtest that sums per-leg requirements is not conservative, it is modelling a different account.

A short-premium backtest with no margin model has not established that the strategy is executable, only that it would have been profitable if size were free.

6. Assembling a historical chain panel

The join is the work, and it is where look-ahead enters.

• One row per (underlying, expiry, strike, right, timestamp). Anything flatter loses the information you need.
• Join the underlying at the same timestamp as the quote, not the daily close. An option quoted at 15:59 against a 16:00 close has a built-in edge that is not real. This is the same merge_asof direction problem as ../market-data-engineering/SKILL.md — and here a wrong-side match produces a plausible IV rather than an obvious error.
• Compute your own IV from the mid, per ../derivatives-pricing/SKILL.md §6.
• Expiry conventions change T and therefore every Greek. AM-settled index options settle on the opening prints of the constituents, not a traded price; PM-settled ones settle at the close. An off-by-one on expiry date is an off-by-one on every number downstream.
• Survivorship applies to underlyings. A chain panel built from today's listed names has already dropped every company that was acquired or delisted — see ../research-integrity-guards/SKILL.md.

🚨 No free live API serves expired contracts

⚠️ Yahoo, Tradier and the IBKR TWS API all return zero history for expired options. Yahoo's date parameter selects which currently-listed expiry to return — it is not an as-of date, and expired contracts drop out of the response entirely. Tradier's own documentation states historical options data is unavailable for expired options.

So there is no path from a free live API to an options backtest. That is the structural fact; everything below is about which paid source to buy.

🚨 Polygon.io is now Massive (renamed 2025-10-30). ⚠️ Most third-party pages describing its options tiers and history depth contradict the vendor's own pricing page — check the source, not a blog.

⚠️ Every figure in this table is secondhand and vendor terms move. Re-check pricing and start dates before committing, and treat the DataShop methodology break as a hard join boundary rather than a footnote.

7. 🚨 Option symbols are not tickers

The OSI symbol encodes root, expiry, right and strike, so the same economic contract changes symbol across a corporate action. After a split or a special dividend the deliverable is adjusted and the contract is re-flagged — the strike no longer means 100 shares.

Joining option data across a corporate action on symbol alone silently mixes two different contracts. An adjusted option carrying a non-standard deliverable will price as nonsense against a standard model, and the error looks like a vol anomaly rather than a data bug.

The OSI symbol is 21 characters, in four fixed-width fields:

"SPY   " + "260116" + "P" + "00452500"   ->   SPY   260116P00452500
   6           6        1        8        =   21

AAPL 240119C00190000 decodes to AAPL, 2024-01-19, call, strike 190.000. ⚠️ Many vendors strip the root padding (SPY260116P00452500, 18 chars) — that is a vendor variant, not OSI, and round-tripping requires knowing which your file uses.

⚠️ The OSI layout, the adjusted-root suffix conventions, and the Saturday→Friday change below are secondhand — retrieved from OCC and Cboe documents via search rather than read from the source PDFs, because network access failed mid-verification. The exercise-by-exception rule (§7b) and the dividend-adjustment rule (end of this section) have since been quoted from hashed copies of the OCC Rules and By-Laws; references/_reverify.md records which is which.

Three traps that break cross-time joins

⚠️ Adjusted roots do not increment on re-adjustment, and suffixes are recycled. MSFT becomes MSFT1 on its first adjustment and stays MSFT1 through later ones, with the strike and deliverable changing underneath. A freed suffix goes to the next class that needs one. So root + strike + expiry is not a stable key across time. Key on an OCC-side identity plus an as-of date, and carry the deliverable as a first-class field.

⚠️ GOOG7 / AAPL7 were mini options, not adjusted contracts. The 7 suffix marked 10-share minis from 2013-03-18; 8 marked corporate/quarterly series. These collide with the 1-9 adjusted suffix space, so a regex that reads a trailing digit as "adjusted" mislabels them.

⚠️ Expiration moved from Saturday to Friday on 2015-02-01. Standard contracts legally expired the Saturday after the third Friday before that. Pre-2015 YYMMDD fields may hold the Saturday in one dataset and the Friday in another — which silently breaks DTE arithmetic and symbol reconstruction across the boundary.

The multiplier stays 100 while the deliverable diverges

That is the dangerous shape. After a 3:2 split the deliverable becomes 150 shares but the multiplier is still 100; after a special cash dividend it becomes 100 shares plus a fixed cash amount. ⚠️ Real OCC examples: BABA1 = 100 ADS + ~$66.00 cash; CRES1 = 100 ADS + cash-in-lieu + 2 IRSA GDS.

🚨 So notional = 100 × price stays right while intrinsic = max(S − K, 0) goes wrong. The error looks like a volatility anomaly rather than a data bug, which is why it survives review.

Which cash dividends adjust the contract — the "10% rule" is gone

✅ OCC By-Laws Art. VI §3A(a)(3) and Interpretation .01, quoted in references/regulatory-sources.md §4: no adjustment for ordinary cash dividends, nor for any cash dividend under $.125 per unit of trading; dividends "(regardless of size)" paid under "a policy or practice … on a quarterly or other regular basis" are ordinary.

So the test is regularity first, then a $0.125-per-share floor — $12.50 on a standard contract. The "10% of market value" rule in older material, and in most models' training data, is not in the current by-laws. 🚨 Getting this wrong flips whether the deliverable carries a cash component — the silent-intrinsic error above.

7b. ✅ Exercise by exception is $0.01 × multiplier

✅ Quoted verbatim, with page numbers and document hashes, in references/regulatory-sources.md. The rules themselves:

• Equity options — OCC Rule 805(d)(2): exercised by exception when the strike is inside the underlying's closing price by $0.01 or more per share, and "such multiple shall be applied to the closing price" for non-standard units — the × multiplier in this section's title, in the rule's own words. Last amended 2025-12-31 (SR-OCC-2025-017).
• Index options — Rule 1804(c): $1.00 or more per contract at multiplier ≠ 1, $0.01 per contract at multiplier 1. $1.00 per standard contract is $0.01 × 100 — which is where the misquoted "$0.01 per contract" comes from.
• History — Cboe RG08-073, June 13, 2008: moved "from $.05 to $.01" for customer, firm and market-maker accounts alike, effective the June 2008 expiration — "Saturday, June 21st", a pre-2015 Saturday expiration in a primary document.
• Caveat — OCC Interpretation .02: the thresholds are administrative and "not intended to dictate to Clearing Members which positions in customers' accounts" — your broker's can differ.

🚨 Two claims to stop repeating:

• "$0.05" is stale — that was the October 2006 value.
• "$0.01 per contract" is a units error that appears in Cboe and OIC material itself. OCC Rule 1804(b) states the index threshold as $1.00 per contract, and $0.01 per contract applies to One Multiplier Options, which are 1/100th the size. Encode threshold = $0.01 × multiplier.

⚠️ And it is not absolute: when a corporate action is unresolved at expiry, OCC removes a class from exercise-by-exception, and then expiring positions are not exercised regardless of how far in the money they are. A deep-ITM option can expire worthless. Your broker's threshold may also differ from OCC's.

7c. 🚨 SPY and SPX options are not the same instrument class

⚠️ Secondhand, from Cboe product specifications:

Same exposure, different instrument. SPY options are early-assignable — notably around SPY's quarterly ex-dividend, which is exactly §1's trap — and trade a day longer than standard SPX. Any code path treating them as one class is broken.

⚠️ SET is not Friday's open. Each constituent is priced at its own first trade on its primary exchange, so the quote finalises only after every name has printed, and it routinely differs from both Thursday's close and the 9:30 index print — most on the volatile expirations you care about.

7d. Assignment is random at the top, and the deadline is not 4:00 pm

⚠️ Secondhand, from OCC and FINRA Rule 2360 material. Assignment is two-stage: OCC allocates to clearing members randomly, then the member allocates to customers by FIFO, random, or another approved method. Model assignment as a probability, not a rule — and note that two random stages mean a small account's realised rate can deviate far from the aggregate.

🚨 The 4:00 → 5:30 pm window is the whole of pin risk. Moneyness for exercise-by-exception is set off the closing price, but holders have until 5:30 pm ET to submit instructions. So an option OTM at the close can still be exercised, and one ITM by $0.01 or more can be abandoned. For |S_close − K| small, assignment is a draw driven by the after-hours move, not by the close.

8. What still needs a second source

The ⚠️ markers above are a queue, not a permanent hedge. references/_reverify.md lists exactly which claims need re-fetching and why, ranked — the optopsy LICENSE file, a hashed copy of the OCC Rules PDF, and the ThetaData pricing conflict are the top three. It also records what is already citation-grade so nobody re-does it.

9. Scripts

scripts/option_lifecycle.py — the early-exercise premium table, the pin-risk boundary, and the sign-flipping assignment error. Carries its own CRR binomial tree, so it runs and makes its point with QuantLib absent; where QuantLib is importable every value is checked against it.