Options & Greeks

Option Greeks in Copinance OS are estimated with European Black–Scholes–Merton using QuantLib’s AnalyticEuropeanEngine (copinance_os.data.analytics.options). Payoffs are European; American exercise or dividends beyond a continuous yield are not modeled.

Aggregate chain analytics (dealer-style positioning summary: bias, IV rank/skew/term, flow scores, gamma regime, GEX profile, max pain, implied move, OI clusters, plus vanna / charm exposure, mispricing vs BSM fair value, moneyness buckets, and pin risk) live in the same package: copinance_os.data.analytics.options.positioning (build_options_positioning, compute_options_positioning_context). Domain types: copinance_os.domain.models.options.positioning with shared AnalysisMethodology from copinance_os.domain.models.common.methodology. These paths are separate from per-row QuantLib Greeks but reuse normalized OptionContract fields (including greeks when present).

Greek reference

Greek	Valid range	Notes
Delta	[−1, 1]	Deep ITM calls → ~1; deep OTM calls → ~0. Puts: ∈ [−1, 0].
Gamma	≥ 0	Peaks near the money; ≈ 0 deep ITM or OTM.
Vega	≥ 0	Largest near the money; tiny in the wings.
Theta	typically < 0	See Theta caveat — QuantLib’s convention differs from “dollars per calendar day.”
Rho	—	Call rho typically positive; European put rho often negative.
Vanna	—	∂²V/∂S∂σ — optional; same BSM inputs as first-order Greeks.
Charm	—	∂Δ/∂T (calendar time) — optional; interpret alongside theta units.
Volga	—	∂²V/∂σ² — optional.

NPV / ITM: When estimation succeeds, contracts may also carry theoretical_price (BSM fair value) and itm_probability (risk-neutral ITM probability) on OptionGreeks, used for aggregate mispricing signals.

Greeks return None when: time to expiry ≤ 0, implied volatility ≤ 0, or spot ≤ 0. Surface None as unavailable, not zero. Higher-order fields are omitted when the estimator cannot compute them for a row.

Theta caveat

QuantLib’s theta() is not the same as “option premium dollars lost per calendar day.” Near expiry and at the money, the reported magnitude can look very large relative to the option’s last price — that reflects QuantLib’s scaling convention, not a literal per-day dollar decay figure. For publication-grade daily theta, convert from QuantLib’s convention or bump the price with a small time step. See QuantLib Greeks reference.

Implied volatility normalization

Raw impliedVolatility from yfinance is normalized when building OptionContract:

Values > 1 are treated as percent points (e.g. 13.67 → σ = 0.1367).
Values ≤ 1 are kept as fractional σ (e.g. 0.25 = 25% annualized vol).

A stored IV of 0.94 in the contract means ~94% annualized σ. The table in copinance market options shows the normalized value; any value printed above 1.0 was already fractional from the provider and was not divided.

Display vs domain model

The copinance market options table formats near-zero Greeks as 0 or scientific notation to suppress floating-point noise. OptionGreeks on OptionContract in code keeps full numeric precision from QuantLib.

Reading the CLI table

copinance market options AAPL
copinance market options AAPL -e 2026-06-19 -s call
copinance market options SPY --no-cache       # refresh if cache predates Greek support
copinance market options MSTR --no-greeks     # hide Greek columns on narrow terminals

Typical moneyness patterns:

Deep in-the-money calls (strike well below spot): delta ≈ 1, gamma ≈ 0, vega ≈ 0.
Deep out-of-the-money puts (strike well below spot, tiny premium): delta ≈ 0, gamma/vega/theta tiny. The table shows 0 for values that round to zero.
Near the money: gamma and vega are largest; call delta moves from ~0 toward 1 as strike falls; put delta moves from ~0 toward −1 as strike rises through the money.

Expiration selection

The default expiration is the earliest listed date on or after today, avoiding expired front months. Pass -e YYYY-MM-DD to select a specific expiry. If the requested expiry is strictly before the evaluation date, Greeks are not computed (returns None).

Methodology contract

OptionsChain.metadata remains provider-facing input metadata (for example, provider and optional dividend_yield). Methodology output is explicit and structured:

OptionsChain.greeks_methodology: AnalysisMethodology | None
OptionsPositioningResult.methodology: AnalysisMethodology

For options positioning, methodology is now component-distributed (no backward-compatible flat spec bundle):

OptionsPositioningResult.methodology.specs includes only cross-cutting specs (Greeks engine when enrichment is enabled, plus aggregate bias and data_quality).
OptionsPositioningResult.signal_categories.<category>.methodology contains the specs that generated that category’s signals.
Standalone component sections (for example iv_metrics, dollar_metrics, delta_exposure, vanna_exposure, charm_exposure, mispricing, moneyness_summary, pin_risk, implied_move_detail) include their own methodology field.

This contract intentionally avoids legacy compatibility wrappers or fallback response shapes. If a metric cannot be computed, it is returned as unavailable (null) rather than synthesized from fallback logic.

For aggregate positioning, missing per-contract Greeks/OI/volume are skipped as unavailable inputs (not treated as zero), so dependent metrics remain null when there is insufficient data.

CLI export path:

copinance analyze --json positioning <SYMBOL> -w near|mid exports RunJobResult, where results is the full OptionsPositioningResult payload.
Non-JSON analyze runs also persist the same structured payload under .copinance/results/v2/.

Financial Literacy Personalization

Deterministic narration is literacy-tiered across analysis surfaces:

Instrument analysis summaries (equity and options)
Market regime and cycle descriptions
Macro interpretation labels
Report-envelope fallback summaries for instrument/market/question-driven runs

The active tier is resolved from financial_literacy (beginner, intermediate, advanced) using resolve_financial_literacy. If not provided, the deterministic default tier is intermediate.

Provider inputs (optional)

Key	Meaning
`provider`	Short name (e.g. `yfinance`)
`dividend_yield`	Continuous dividend yield used in BSM (decimal, e.g. `0.02`). If absent, `COPINANCEOS_OPTION_GREEKS_DIVIDEND_YIELD_DEFAULT` or `AnalysisProfile.preferences` applies.

Greek estimation outputs

Set by estimate_bsm_greeks_for_options_chain / QuantLibBsmGreekEstimator after a successful run:

chain.greeks_methodology.version (envelope version)
chain.greeks_methodology.computed_at (UTC timestamp)
chain.greeks_methodology.specs[*] (id, model_family, assumptions, limitations, references, parameters)
chain.greeks_methodology.data_inputs (symbol, as_of_date, and relevant run context)

This replaces legacy ad-hoc option_greeks_* output keys in OptionsChain.metadata.

Configuration

# Annual risk-free rate (decimal). Unset uses built-in default (0.045).
COPINANCEOS_OPTION_GREEKS_RISK_FREE_RATE=0.045
 
# Default dividend yield when chain metadata has no dividend_yield. Unset = 0.
COPINANCEOS_OPTION_GREEKS_DIVIDEND_YIELD_DEFAULT=0

Profile-level overrides (when you construct QuantLibBsmGreekEstimator(profile=...)):

option_greeks_risk_free_rate
option_greeks_dividend_yield_default

The default DI container uses QuantLibBsmGreekEstimator() with profile=None, so only environment settings apply unless you wire a custom estimator.

Code layout

Module	Role
`copinance_os.data.providers.*`	Vendor adapters (yfinance fetches raw chain)
`copinance_os.data.analytics.options`	QuantLib BSM Greek estimation in `greeks/` and aggregate positioning in `positioning/`
`copinance_os.data.providers.market`	Composed `MarketDataProvider` (fetch + estimate in one call)

See Architecture for layer rules.