v0.2.0: add 0DTE, exposure history, advanced volatility endpoints; SEO-optimized README

New methods: zero_dte(), exposure_history(), adv_volatility()
36 unit tests passing. Updated README with full method reference table.
Bumped version to 0.2.0.

Author: tdobrowolski1

README.md

@@ -4,7 +4,7 @@
 [![Python](https://img.shields.io/pypi/pyversions/flashalpha)](https://pypi.org/project/flashalpha/)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-**Real-time options exposure analytics for Python.** Gamma exposure (GEX), delta (DEX), vanna (VEX), charm (CHEX), key levels, Black-Scholes greeks, implied volatility, Kelly sizing, and more — from the [FlashAlpha API](https://flashalpha.com).
+**Python client for the FlashAlpha options analytics API.** Access real-time gamma exposure (GEX), delta exposure (DEX), vanna exposure (VEX), charm exposure (CHEX), 0DTE analytics, Black-Scholes greeks, implied volatility, volatility surfaces, dealer positioning, Kelly criterion sizing, and more — all from Python.
 
 ```bash
 pip install flashalpha
@@ -15,9 +15,9 @@ pip install flashalpha
 ```python
 from flashalpha import FlashAlpha
 
-fa = FlashAlpha("YOUR_API_KEY")
+fa = FlashAlpha("YOUR_API_KEY")  # Get a free key at flashalpha.com
 
-# Get gamma exposure for SPY
+# Gamma exposure by strike
 gex = fa.gex("SPY")
 print(f"Net GEX: ${gex['net_gex']:,.0f}")
 print(f"Gamma flip: {gex['gamma_flip']}")
@@ -26,110 +26,121 @@ for strike in gex["strikes"][:5]:
     print(f"  {strike['strike']}: net ${strike['net_gex']:,.0f}")
 ```
 
-## What You Can Do
+Get your free API key at [flashalpha.com](https://flashalpha.com) — 10 requests/day, no credit card.
 
-### Exposure Analytics — see where dealers are positioned
+## Features
 
-```python
-# Gamma exposure by strike
-gex = fa.gex("SPY")
-gex = fa.gex("TSLA", expiration="2026-03-21", min_oi=100)
+### Options Exposure Analytics
 
-# Delta, vanna, charm exposure
-dex = fa.dex("AAPL")
-vex = fa.vex("QQQ")
-chex = fa.chex("NVDA")
+Gamma exposure, delta exposure, vanna exposure, and charm exposure by strike. See where dealers are positioned and how they need to hedge.
 
-# Key levels (gamma flip, walls, max pain)
-levels = fa.exposure_levels("SPY")
+```python
+gex = fa.gex("SPY")                                        # Gamma exposure
+dex = fa.dex("AAPL")                                       # Delta exposure
+vex = fa.vex("QQQ")                                        # Vanna exposure
+chex = fa.chex("NVDA")                                     # Charm exposure
+
+levels = fa.exposure_levels("SPY")                          # Key levels
 print(f"Call wall: {levels['levels']['call_wall']}")
 print(f"Put wall: {levels['levels']['put_wall']}")
 print(f"Gamma flip: {levels['levels']['gamma_flip']}")
 
-# Full exposure summary with hedging estimates
-summary = fa.exposure_summary("SPY")  # Growth+
-
-# AI narrative analysis
-narrative = fa.narrative("SPY")  # Growth+
-print(narrative["narrative"]["regime"])
+summary = fa.exposure_summary("SPY")                        # Full summary (Growth+)
+narrative = fa.narrative("SPY")                              # AI narrative (Growth+)
 print(narrative["narrative"]["outlook"])
 ```
 
-### Market Data — live quotes and option chains
-
-```python
-# Stock quote
-quote = fa.stock_quote("AAPL")
-print(f"AAPL: ${quote['mid']}")
-
-# Option quote with greeks
-opt = fa.option_quote("SPY", expiry="2026-03-21", strike=660, type="C")  # Growth+
-print(f"Delta: {opt['delta']}, IV: {opt['implied_vol']}")
+### 0DTE Analytics
 
-# Comprehensive stock summary (price, vol, exposure, macro)
-summary = fa.stock_summary("SPY")
+Real-time zero-days-to-expiration analysis: gamma regime, expected move, pin risk scoring, dealer hedging estimates, theta decay acceleration, and per-strike breakdown.
 
-# Vol surface (public — no API key needed)
-surface = fa.surface("SPY")
+```python
+dte = fa.zero_dte("SPY")                                    # Growth+
+print(f"Pin score: {dte['pin_risk']['pin_score']}/100")
+print(f"Expected move: ±{dte['expected_move']['remaining_1sd_pct']:.2f}%")
+print(f"Theta/hr: ${dte['decay']['theta_per_hour_remaining']:,.0f}")
+print(f"Gamma acceleration: {dte['decay']['gamma_acceleration']}x vs 7DTE")
 ```
 
-### Pricing — Black-Scholes greeks and implied vol
+### Black-Scholes Greeks and Implied Volatility
+
+Full BSM greeks — first order (delta, gamma, theta, vega, rho), second order (vanna, charm, vomma), and third order (speed, zomma, color, ultima).
 
 ```python
-# Full BSM greeks (first, second, third order)
 g = fa.greeks(spot=580, strike=580, dte=30, sigma=0.18, type="call")
 print(f"Delta: {g['first_order']['delta']}")
-print(f"Gamma: {g['first_order']['gamma']}")
 print(f"Vanna: {g['second_order']['vanna']}")
+print(f"Speed: {g['third_order']['speed']}")
+
+iv = fa.iv(spot=580, strike=580, dte=30, price=12.69)
+print(f"IV: {iv['implied_volatility_pct']}%")
+```
+
+### Volatility Analytics
+
+Realized vol, IV-RV spreads, skew profiles, term structure, GEX by DTE, theta decay, put/call breakdowns, OI concentration, hedging scenarios, and liquidity analysis.
+
+```python
+vol = fa.volatility("TSLA")                                 # Growth+
+print(f"ATM IV: {vol['atm_iv']}%")
+print(f"RV 20d: {vol['realized_vol']['rv_20d']}%")
+print(f"VRP: {vol['iv_rv_spreads']['assessment']}")
+print(f"Skew 25d: {vol['skew_profiles'][0]['skew_25d']}")
+```
+
+### Advanced Volatility (SVI, Variance Surfaces, Arbitrage Detection)
+
+Raw SVI parameters per expiry, total variance surface grids, butterfly and calendar arbitrage flags, higher-order greeks surfaces (vanna, charm, volga, speed), and variance swap fair values.
+
+```python
+adv = fa.adv_volatility("SPY")                              # Alpha+
+print(f"SVI params: {adv['svi_parameters'][0]}")
+print(f"Arbitrage flags: {len(adv['arbitrage_flags'])}")
+print(f"Var swap fair vol: {adv['variance_swap_fair_values'][0]['fair_vol']}%")
+```
+
+### Kelly Criterion Position Sizing
 
-# Implied volatility from market price
-result = fa.iv(spot=580, strike=580, dte=30, price=12.69)
-print(f"IV: {result['implied_volatility_pct']}%")
+Optimal position sizing using numerical integration over the full lognormal distribution — not the simplified gambling formula.
 
-# Kelly criterion position sizing
-kelly = fa.kelly(  # Growth+
+```python
+kelly = fa.kelly(                                            # Growth+
     spot=580, strike=580, dte=30,
     sigma=0.18, premium=12.69, mu=0.12,
 )
 print(kelly["recommendation"])
+print(f"Half-Kelly: {kelly['sizing']['half_kelly_pct']}%")
 ```
 
-### Volatility Analytics — skew, term structure, realized vol
+### Market Data
 
 ```python
-vol = fa.volatility("TSLA")  # Growth+
-print(f"ATM IV: {vol['atm_iv']}%")
-print(f"RV 20d: {vol['realized_vol']['rv_20d']}%")
-print(f"VRP assessment: {vol['iv_rv_spreads']['assessment']}")
+quote = fa.stock_quote("AAPL")                              # Live stock quote
+opt = fa.option_quote("SPY", expiry="2026-03-21",           # Option quote (Growth+)
+                       strike=660, type="C")
+summary = fa.stock_summary("SPY")                           # Comprehensive summary
+surface = fa.surface("SPY")                                  # Vol surface (public)
 ```
 
-### Historical Data — minute-by-minute from ClickHouse
+### Historical Data (ClickHouse)
+
+Minute-by-minute stock and option quotes from ClickHouse — 3.5 billion rows across 141 tickers.
 
 ```python
-# Historical stock quotes
 hist = fa.historical_stock_quote("SPY", date="2026-03-05", time="10:30")
-
-# Historical option quotes
 hist_opt = fa.historical_option_quote(
     "SPY", date="2026-03-05", expiry="2026-03-20", strike=580, type="C"
 )
 ```
 
-### Reference & Account
+### Reference Data and Account
 
 ```python
-# All available tickers
-tickers = fa.tickers()
-
-# Option chain metadata (expirations + strikes)
-chain = fa.options("SPY")
-
-# Symbols with live cached data
-symbols = fa.symbols()
-
-# Account info and quota
-account = fa.account()
-print(f"Plan: {account['plan']}, Remaining: {account['remaining']}")
+tickers = fa.tickers()                # All available stock tickers
+chain = fa.options("SPY")             # Option chain metadata
+symbols = fa.symbols()                # Symbols with live cached data
+account = fa.account()                # Plan, usage, quota
+health = fa.health()                  # API health check (public)
 ```
 
 ## Error Handling
@@ -157,18 +168,54 @@ except RateLimitError as e:
     print(f"Rate limited — retry after {e.retry_after}s")
 ```
 
-## Plans
-
-| Plan | Daily Requests | Highlights |
-|------|---------------|------------|
-| **Free** | 50 | Stock quotes, GEX/DEX/VEX/CHEX by strike, levels, greeks, IV, tickers |
-| **Basic** | 250 | Everything in Free |
-| **Growth** | 2,500 | + Option quotes, exposure summary, narrative, volatility, Kelly sizing |
-| **Pro** | Unlimited | Full access |
-
-**Get your API key at [flashalpha.com](https://flashalpha.com)**
+## API Plans
+
+| Plan | Daily Requests | Access |
+|------|---------------|--------|
+| **Free** | 10 | Stock quotes, GEX/DEX/VEX/CHEX by strike, levels, BSM greeks, IV, historical quotes, tickers, options meta, surface, stock summary |
+| **Basic** | 250 | Everything in Free + index symbols (SPX, VIX, RUT, etc.) |
+| **Growth** | 2,500 | + Exposure summary, narrative, 0DTE analytics, volatility analytics, option quotes, full-chain GEX, Kelly sizing |
+| **Alpha** | Unlimited | + Advanced volatility (SVI, variance surfaces, arbitrage detection, greeks surfaces, variance swap) |
+
+Get your API key at **[flashalpha.com](https://flashalpha.com)**
+
+## All Methods
+
+| Method | Endpoint | Plan |
+|--------|----------|------|
+| `fa.gex(symbol)` | Gamma exposure by strike | Free+ |
+| `fa.dex(symbol)` | Delta exposure by strike | Free+ |
+| `fa.vex(symbol)` | Vanna exposure by strike | Free+ |
+| `fa.chex(symbol)` | Charm exposure by strike | Free+ |
+| `fa.exposure_levels(symbol)` | Key levels (gamma flip, walls, max pain) | Free+ |
+| `fa.exposure_summary(symbol)` | Full exposure summary with hedging | Growth+ |
+| `fa.narrative(symbol)` | AI narrative analysis | Growth+ |
+| `fa.zero_dte(symbol)` | 0DTE analytics (regime, pin risk, decay) | Growth+ |
+| `fa.exposure_history(symbol)` | Daily exposure snapshots | Growth+ |
+| `fa.stock_quote(ticker)` | Live stock quote | Free+ |
+| `fa.option_quote(ticker)` | Option quotes with greeks | Growth+ |
+| `fa.stock_summary(symbol)` | Comprehensive stock summary | Public/Free+ |
+| `fa.surface(symbol)` | Volatility surface grid | Public |
+| `fa.historical_stock_quote(ticker)` | Historical stock quotes | Free+ |
+| `fa.historical_option_quote(ticker)` | Historical option quotes | Free+ |
+| `fa.greeks(...)` | BSM greeks (1st, 2nd, 3rd order) | Free+ |
+| `fa.iv(...)` | Implied volatility solver | Free+ |
+| `fa.kelly(...)` | Kelly criterion sizing | Growth+ |
+| `fa.volatility(symbol)` | Comprehensive volatility analytics | Growth+ |
+| `fa.adv_volatility(symbol)` | SVI, variance surface, arb detection | Alpha+ |
+| `fa.tickers()` | All available stock tickers | Free+ |
+| `fa.options(ticker)` | Option chain metadata | Free+ |
+| `fa.symbols()` | Symbols with live data | Free+ |
+| `fa.account()` | Account info and quota | Free+ |
+| `fa.health()` | Health check | Public |
 
 ## Links
 
+- [FlashAlpha](https://flashalpha.com) — API keys, docs, pricing
 - [API Documentation](https://flashalpha.com/docs)
-- [GitHub](https://github.com/FlashAlpha-lab/flashalpha-python)
+- [Examples](https://github.com/FlashAlpha-lab/flashalpha-examples)
+- [GEX Explained](https://github.com/FlashAlpha-lab/gex-explained)
+
+## License
+
+MIT

pyproject.toml

@@ -4,8 +4,8 @@ build-backend = "hatchling.build"
 
 [project]
 name = "flashalpha"
-version = "0.1.0"
-description = "Python SDK for the FlashAlpha options analytics API — gamma exposure (GEX), delta, vanna, charm, greeks, and more."
+version = "0.2.0"
+description = "Python SDK for the FlashAlpha options analytics API — gamma exposure (GEX), delta, vanna, charm, greeks, 0DTE analytics, volatility surfaces, and more."
 readme = "README.md"
 license = "MIT"
 requires-python = ">=3.10"
@@ -25,6 +25,15 @@ keywords = [
     "trading",
     "finance",
     "quantitative finance",
+    "0dte",
+    "zero dte",
+    "volatility surface",
+    "options data",
+    "dealer positioning",
+    "kelly criterion",
+    "vol surface",
+    "SVI",
+    "variance swap",
 ]
 classifiers = [
     "Development Status :: 3 - Alpha",

src/flashalpha/__init__.py

@@ -10,7 +10,7 @@
     TierRestrictedError,
 )
 
-__version__ = "0.1.0"
+__version__ = "0.2.0"
 __all__ = [
     "FlashAlpha",
     "FlashAlphaError",

src/flashalpha/client.py

@@ -187,6 +187,20 @@ def narrative(self, symbol: str) -> dict:
         """Verbal narrative analysis of exposure. Requires Growth+."""
         return self._get(f"/v1/exposure/narrative/{symbol}")
 
+    def zero_dte(self, symbol: str, *, strike_range: float | None = None) -> dict:
+        """Real-time 0DTE analytics: regime, expected move, pin risk, hedging, decay. Requires Growth+."""
+        params: dict[str, Any] = {}
+        if strike_range is not None:
+            params["strike_range"] = strike_range
+        return self._get(f"/v1/exposure/zero-dte/{symbol}", params or None)
+
+    def exposure_history(self, symbol: str, *, days: int | None = None) -> dict:
+        """Daily exposure snapshots for trend analysis. Requires Growth+."""
+        params: dict[str, Any] = {}
+        if days is not None:
+            params["days"] = days
+        return self._get(f"/v1/exposure/history/{symbol}", params or None)
+
     # ── Pricing & Sizing ────────────────────────────────────────────
 
     def greeks(
@@ -262,6 +276,10 @@ def volatility(self, symbol: str) -> dict:
         """Comprehensive volatility analysis. Requires Growth+."""
         return self._get(f"/v1/volatility/{symbol}")
 
+    def adv_volatility(self, symbol: str) -> dict:
+        """Advanced volatility analytics: SVI parameters, variance surface, arbitrage detection, greeks surfaces, variance swap. Requires Alpha+."""
+        return self._get(f"/v1/adv_volatility/{symbol}")
+
     # ── Reference Data ──────────────────────────────────────────────
 
     def tickers(self) -> dict:

tests/test_client.py

@@ -205,6 +205,30 @@ def test_narrative(fa):
     assert "regime" in result["narrative"]
 
 
+@responses.activate
+def test_zero_dte(fa):
+    payload = {"symbol": "SPY", "regime": {"label": "positive_gamma"}, "pin_risk": {"pin_score": 82}, "decay": {"gamma_acceleration": 2.4}}
+    responses.get(f"{BASE}/v1/exposure/zero-dte/SPY", json=payload)
+    result = fa.zero_dte("SPY")
+    assert result["pin_risk"]["pin_score"] == 82
+
+
+@responses.activate
+def test_zero_dte_with_strike_range(fa):
+    payload = {"symbol": "SPY", "strikes": []}
+    responses.get(f"{BASE}/v1/exposure/zero-dte/SPY", json=payload)
+    fa.zero_dte("SPY", strike_range=0.05)
+    assert "strike_range=0.05" in responses.calls[0].request.url
+
+
+@responses.activate
+def test_exposure_history(fa):
+    payload = {"symbol": "SPY", "days": 7, "count": 5, "snapshots": []}
+    responses.get(f"{BASE}/v1/exposure/history/SPY", json=payload)
+    result = fa.exposure_history("SPY", days=7)
+    assert result["days"] == 7
+
+
 # ── Pricing ─────────────────────────────────────────────────────────
 
 
@@ -243,6 +267,14 @@ def test_volatility(fa):
     assert result["atm_iv"] == 48.5
 
 
+@responses.activate
+def test_adv_volatility(fa):
+    payload = {"symbol": "SPY", "svi_parameters": [{"expiry": "2026-04-04", "a": 0.0045}], "arbitrage_flags": []}
+    responses.get(f"{BASE}/v1/adv_volatility/SPY", json=payload)
+    result = fa.adv_volatility("SPY")
+    assert result["svi_parameters"][0]["a"] == 0.0045
+
+
 # ── Reference Data ──────────────────────────────────────────────────