Modular quantitative equity options pricing workbench and CLI powered by Black-Scholes-Merton, Cox-Ross-Rubinstein Binomial Trees, and Monte Carlo simulation — complete with live Yahoo Finance options chains, FRED SOFR benchmark rates, Brent implied-volatility inversion, and 4 interactive Plotly analytics modules.
Overview • Pricing Models • UI & Analytics • Architecture • Structure • Setup & Usage • Docker • Tests
CME Equity Options Pricer (khalid-naami/CME-options-data) is a dual-interface quantitative options analysis platform built around a decoupled src/ architecture (models, data, ui, utils, and config). It ingests live equity quotes and multi-expiry options chains from Yahoo Finance, enriches risk-free discounting with live US SOFR term rates from the FRED API (alongside built-in EUR ESTR/EONIA and GBP SONIA reference curves), and benchmarks market option prices against three independent valuation engines through both a Streamlit dashboard (app.py) and a scriptable CLI (cli.py).
| Capability | Implementation Details | Source Module |
|---|---|---|
| Multi-Model Valuation | Black-Scholes-Merton (continuous dividend yield |
src/models/pricing.py |
| Analytical Greeks & IV Solver | Exact Delta, Gamma, daily Theta, Vega (per 1% IV), and Rho (per 1% rate); root-finding Implied Volatility via Brent's method (brentq). |
src/models/pricing.py |
| Live Market & Chain Ingestion | Fetches stock fundamentals, 6-month historical volatility (20d rolling), and options chains (up to 3 expiries in Streamlit cache / 6 in provider) with ITM/ATM/OTM classification. |
src/data/providers.py, src/utils/cache.py
|
| Multi-Currency Rate Curve Engine | Live FRED API fetches for US SOFR (SOFR, SOFR1M, SOFR3M, SOFR6M, SOFR12M) when FRED_API_KEY is set; fallback/reference curves for ESTR, SONIA, and EONIA with expiry-matched tenor recommendations. |
src/data/rates.py |
| Input Validation & Caching | Validates tickers, strikes, rates (@st.cache_data (300s–600s TTL) + simple_cache. |
src/utils/validators.py, src/utils/formatters.py
|
| CLI & Containerized Deployment | Positional CLI (python cli.py AAPL ...), multi-stage python:3.13-slim Dockerfile, docker-compose dev/prod stacks, and PowerShell/Bash management scripts. |
cli.py, Dockerfile, DOCKER.md
|
All core computations reside in OptionsPricingEngine inside src/models/pricing.py:
-
Greeks Scaling:
$\Theta$ is annualized and divided by365(daily decay);$\nu$ (Vega) and$\rho$ (Rho) are divided by100(sensitivity per1%shift in$\sigma$ or$r$ ).
For steps = 100 default,
Terminal payoffs are discounted via backward induction
Terminal spot paths are simulated under risk-neutral GBM (seed = 42, simulations = 10,000 default) and discounted as
Implied volatility solves scipy.optimize.brentq over
Launching streamlit run app.py loads:
-
Sidebar Controls: Quick selector for
SPY,QQQ,IWM,AAPL,MSFT,GOOGL,AMZN,TSLA,NVDA,METAor custom ticker, live risk-free rate refresh (Refresh Rates), and URL override support (?volatility=25.0). -
Stock Overview & Chain Filters: 4-column stock metrics, filters for Option Type (
All,call,put), Expiration Date, Moneyness (ITM,ATMwithin$\pm 2%$ ,OTM), and single-strike isolation. -
Pricing Breakdown & Market Comparison Table: Side-by-side Black-Scholes, Binomial Tree, and Monte Carlo estimates, intrinsic/time value split, and market deviation columns (
theoretical_price,price_diff,price_diff_pct). -
4 Interactive Plotly Tabs (
render_option_analysis_plots):-
📈 Price vs IV: Call/put scatter plots colored by Moneyness, Days to Expiry, or Option Type, optional theoretical price markers, and
UnivariateSplineIV smile curve. -
🎯 Greeks Comparison: Multi-Greek subplots (
delta,gamma,theta,vega,rho) overlaying market vs. theoretical values, optional standardization, andLinearRegressiontrend lines. -
💰 Model Comparison: Benchmarks up to 50 sampled options across Black-Scholes, Binomial (
100steps), and Monte Carlo (5,000paths) with$\pm 10%$ confidence bands, residual distributions, and RMSE, MAE, MAPE, and Correlation cards. -
📊 Sensitivity Analysis: Spot sensitivity (
$0.8S \to 1.2S$ ) and volatility sensitivity ($10% \to 100%$ ) curves for the nearest-to-ATM option.
-
📈 Price vs IV: Call/put scatter plots colored by Moneyness, Days to Expiry, or Option Type, optional theoretical price markers, and
flowchart TD
subgraph Sources["External & Reference Data"]
YF["Yahoo Finance (yfinance)\nSpot, History & Options Chains"]
FRED["FRED API\nLive USD SOFR Term Rates"]
FALL["Reference Rate Tables\nESTR, SONIA, EONIA Fallbacks"]
end
subgraph Core["src/ Application Core"]
PROV["src/data/providers.py\nMarketDataProvider"]
RATES["src/data/rates.py\nRiskFreeRatesProvider"]
CACHE["src/utils/cache.py\n@st.cache_data & simple_cache"]
VAL["src/utils/validators.py & formatters.py"]
ENG["src/models/pricing.py\nOptionsPricingEngine (BSM, Binomial, MC, IV)"]
end
subgraph Interfaces["User Interfaces"]
APP["app.py + src/ui/components.py\nStreamlit Dashboard & 4 Plotly Tabs"]
CLI["cli.py\nCommand-Line Pricer & Chain Viewer"]
end
YF --> CACHE --> PROV
YF --> PROV
FRED --> RATES
FALL --> RATES
PROV --> VAL --> ENG
RATES --> ENG
ENG --> APP
ENG --> CLI
CME-options-data/
├── .devcontainer/
│ └── devcontainer.json # VS Code / Codespaces Python 3.11 container config
├── .dockerignore
├── .gitattributes
├── .gitignore
├── LICENSE # MIT License
├── README.md
├── DOCKER.md # Detailed Docker & Nginx/Redis production guide
├── Dockerfile # Multi-stage python:3.13-slim image (port 8501)
├── docker-compose.yml # Local Streamlit service definition
├── docker-compose.prod.yml # Production stack (Streamlit + Nginx + Redis)
├── docker-run.ps1 # Windows PowerShell Docker lifecycle script
├── docker-run.sh # Linux/macOS Bash Docker lifecycle script
├── requirements.txt # Python package dependencies
├── app.py # Main Streamlit application entrypoint
├── cli.py # Command-line options pricer & chain inspector
├── config/
│ ├── __init__.py
│ └── settings.py # APIConfig, PricingConfig, UIConfig dataclasses
├── src/
│ ├── __init__.py
│ ├── core/
│ │ └── __init__.py # Core package namespace
│ ├── data/
│ │ ├── __init__.py
│ │ ├── providers.py # StockDataProvider, OptionsDataProvider, MarketDataProvider
│ │ └── rates.py # RiskFreeRatesProvider (FRED SOFR + ESTR/SONIA/EONIA)
│ ├── models/
│ │ ├── __init__.py
│ │ └── pricing.py # OptionsPricingEngine (BSM, Binomial, Monte Carlo, Greeks, IV)
│ ├── ui/
│ │ ├── __init__.py
│ │ └── components.py # StreamlitComponents (sidebar, tables, 4 Plotly tabs)
│ └── utils/
│ ├── __init__.py
│ ├── cache.py # Streamlit & in-memory TTL caching helpers
│ ├── formatters.py # DataFormatter & CLIFormatter
│ └── validators.py # DataValidator input checks
├── tests/
│ ├── __init__.py
│ ├── test_pricing.py # Unit tests (BSM, put-call parity, Greeks, validators)
│ ├── test_enhanced_plots.py # Spline, regression & metric verification script
│ ├── test_plots.py # Plot imports & tab workflow verification
│ ├── test_price_fix.py # Live yfinance price fallback check
│ ├── test_rate_update.py # RiskFreeRatesProvider smoke test
│ ├── test_strike_filter.py # Strike-filter workflow simulation
│ ├── validate_fix.py # Session-state rate-update simulation
│ ├── test_final.py # Placeholder test module
│ └── test_options_fix.py # Placeholder test module
└── backups/ # Legacy pre-refactor snapshots
- Python
3.8+(3.11in DevContainer,3.13inDockerfile) - Docker Desktop (optional, for containerized deployment)
git clone https://github.com/khalid-naami/CME-options-data.git
cd CME-options-data
python -m venv .venv# Windows (PowerShell)
.venv\Scripts\Activate.ps1# macOS / Linux
source .venv/bin/activatepip install -r requirements.txtCreate a .env file in the project root (automatically loaded via python-dotenv in config/settings.py) to enable live US SOFR rates from FRED:
FRED_API_KEY=your_fred_api_key_here
ALPHA_VANTAGE_API_KEY=your_optional_alpha_vantage_key
DEBUG=Falsestreamlit run app.pyOpen http://localhost:8501 in your browser (optional query parameter: ?volatility=25.0).
symbol is a positional argument:
# Inspect options chain (first 20 contracts)
python cli.py AAPL --show-chain
# Price a specific call option with full Greeks output
python cli.py AAPL --strike 230 --expiry 2026-12-18 --option-type call
# Custom risk-free rate and volatility, returning theoretical price only
python cli.py SPY --strike 580 --expiry 2026-12-18 --option-type put --rate 0.045 --volatility 0.20 --price-onlyfrom src.models.pricing import OptionsPricingEngine
from src.data.providers import MarketDataProvider
from src.data.rates import get_risk_free_rates
engine = OptionsPricingEngine(risk_free_rate=0.05)
market = MarketDataProvider().get_complete_market_data("SPY")
spot = market["current_price"]
greeks = engine.calculate_greeks(S=spot, K=round(spot), T=0.25, r=0.05, sigma=0.20, option_type="call")
breakdown = engine.calculate_pricing_breakdown(S=spot, K=round(spot), T=0.25, r=0.05, sigma=0.20, option_type="call")Full details are available in DOCKER.md. Quick-start commands:
# Windows PowerShell helper
.\docker-run.ps1 run # Builds image & starts container on port 8501
.\docker-run.ps1 compose # Starts via docker-compose.yml# Linux / macOS helper
chmod +x docker-run.sh
./docker-run.sh run
# Or manual Docker build & run
docker build -t cme-equity-options-pricer:latest .
docker run -d --name cme-equity-options-pricer -p 8501:8501 --env-file .env cme-equity-options-pricer:latest
# Production Compose stack (Streamlit + Nginx + Redis)
docker-compose -f docker-compose.prod.yml up -dRun the core unit test suite (unittest) and auxiliary verification scripts locally:
# Core pricing, put-call parity, Greeks, validator & formatter unit tests
python -m unittest tests/test_pricing.py -v
# Additional verification scripts
python tests/test_enhanced_plots.py
python tests/test_rate_update.py
python tests/validate_fix.pyNote:
tests/test_price_fix.pyperforms live network calls to Yahoo Finance (yfinance).
- Market Data: Yahoo Finance via
yfinance(delayed/public equity quotes, historical bars, and options chains). - Interest Rates: Federal Reserve Economic Data (FRED API) for live USD
SOFRterm rates whenFRED_API_KEYis provided; built-in reference rates forESTR,SONIA,EONIA, and offlineSOFRfallback. - Disclaimer: This software is intended strictly for educational, quantitative research, and analytical use. Theoretical model values depend on volatility, rate, and dividend assumptions and do not constitute financial advice.
- License: Released under the MIT License — see LICENSE.