# spx-dealer-gamma

Computes SPX dealer gamma exposure (GEX) from **free CBOE delayed option quotes**
(~15-minute delay, official open interest and implied volatility — no brokerage
market-data entitlement required). Exposed as an MCP tool for Claude Desktop.

## Why CBOE delayed quotes

CBOE lists SPX/SPXW natively, so this is a first-party source for OI and IV on the
exact index most dealer-gamma analysis targets — not a proxy via SPY. The public
endpoint (`https://cdn.cboe.com/api/global/delayed_quotes/options/_SPX.json`) also
returns CBOE's own precomputed per-contract Greeks (delta, gamma, vega, theta),
so the current-spot GEX snapshot uses their greeks directly rather than a
re-derived model.

## Method

- **Current-spot net GEX**: `sign * gamma * open_interest * 100 * spot^2 * 0.01`,
  summed over all contracts with open interest > 0. Calls contribute positively,
  puts negatively — the standard convention used by most public GEX calculators
  (dealers modeled as net long gamma via calls / net short via puts). This is a
  modeling assumption, not directly observable dealer positioning.
- **Zero-gamma flip level**: the current-spot GEX above is a single point. To find
  where dealer gamma flips sign, this recomputes Black-Scholes gamma for every
  contract with a valid IV across a scan of hypothetical spot prices (default
  ±15% band, 121 steps), holding each contract's own quoted IV/strike/expiry
  fixed, and finds where cumulative signed GEX crosses zero. This does **not**
  shift the vol surface with spot (no skew dynamics) — a known simplification
  shared by most open-source GEX trackers.
- Contracts with `iv <= 0` (stale/no recent quote) are excluded from the flip
  scan but still included in the current-spot snapshot via CBOE's own gamma.

## Files

- `gamma.py` — data fetch + calculation, runnable standalone (`python gamma.py`)
- `server.py` — MCP server wrapper exposing `spx_dealer_gamma` as a tool

## Setup

```bash
python -m venv .venv
./.venv/Scripts/pip install -r requirements.txt   # Windows
# ./.venv/bin/pip install -r requirements.txt      # macOS/Linux
```

## Claude Desktop

Add to `claude_desktop_config.json`:

```json
"spx-dealer-gamma": {
  "command": "C:\\path\\to\\spx-dealer-gamma\\.venv\\Scripts\\python.exe",
  "args": ["C:\\path\\to\\spx-dealer-gamma\\server.py"]
}
```

## Limitations

- 15-minute delayed data, not live.
- Aggregates *all* listed SPX/SPXW expiries (including LEAPS), not just the
  front-month/0DTE window some trackers restrict to — net GEX magnitude isn't
  directly comparable to trackers that scope differently.
- Dealer-side sign convention is an assumption, not observed fact.
- No vol-surface skew shift in the flip scan (see Method above).