Add MaxPain typed model with rich field docs

- Add MaxPainResponse and supporting TypedDict types for
  GET /v1/maxpain/{symbol}: MaxPainDistance, MaxPainCurveRow,
  MaxPainOiRow, MaxPainByExpirationRow, MaxPainDealerAlignment,
  MaxPainExpectedMove. Every field has rich docstrings with
  the published heuristics (pin_probability inputs 30/25/25/20,
  signal thresholds, dealer alignment categories, etc.).
- Re-export from __init__.py.
- Update integration tests + docs/api.md for the new endpoint.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: tdobrowolski1

docs/api.md

@@ -654,12 +654,12 @@ curl -H "X-Api-Key: YOUR_API_KEY" \
   "hedging_estimate": {
     "spot_down_1pct": {
       "dealer_shares_to_trade": 4780000,
-      "direction": "BUY",
+      "direction": "buy",
       "notional_usd": 2852000000
     },
     "spot_up_1pct": {
       "dealer_shares_to_trade": -4780000,
-      "direction": "SELL",
+      "direction": "sell",
       "notional_usd": 2852000000
     }
   },
@@ -675,9 +675,27 @@ curl -H "X-Api-Key: YOUR_API_KEY" \
 
 | Field | Description |
 |-------|-------------|
-| `regime` | `positive_gamma`, `negative_gamma`, or `undetermined` |
-| `hedging_estimate` | Estimated dealer hedging flow if spot moves +/-1% |
-| `zero_dte` | Same-day expiration contribution to total GEX |
+| `symbol` | Requested underlying symbol |
+| `underlying_price` | Spot price used for the exposure calculation |
+| `as_of` | UTC timestamp of the exposure snapshot |
+| `gamma_flip` | Strike where net GEX crosses zero |
+| `regime` | `positive_gamma`, `negative_gamma`, `neutral`, or `undetermined` |
+| `exposures.net_gex` | Net gamma exposure in USD notional |
+| `exposures.net_dex` | Net delta exposure in USD notional |
+| `exposures.net_vex` | Net vanna exposure in USD notional |
+| `exposures.net_chex` | Net charm exposure in USD notional |
+| `interpretation.gamma` | Gamma-regime interpretation |
+| `interpretation.vanna` | Vanna-flow interpretation |
+| `interpretation.charm` | Charm/time-decay interpretation |
+| `hedging_estimate.spot_down_1pct.dealer_shares_to_trade` | Estimated shares dealers need to trade after a -1% spot move |
+| `hedging_estimate.spot_down_1pct.direction` | Lowercase `buy` or `sell` |
+| `hedging_estimate.spot_down_1pct.notional_usd` | Estimated USD notional of the hedge |
+| `hedging_estimate.spot_up_1pct.dealer_shares_to_trade` | Estimated shares dealers need to trade after a +1% spot move |
+| `hedging_estimate.spot_up_1pct.direction` | Lowercase `buy` or `sell` |
+| `hedging_estimate.spot_up_1pct.notional_usd` | Estimated USD notional of the hedge |
+| `zero_dte.net_gex` | Same-day expiration net GEX contribution |
+| `zero_dte.pct_of_total_gex` | Same-day expiration GEX as a percentage of total GEX |
+| `zero_dte.expiration` | Same-day expiration date, or `null` when unavailable |
 
 ---
 

src/flashalpha/__init__.py

@@ -25,6 +25,13 @@
     VrpStrategyScores,
     VrpTermItem,
     VrpVannaConditioned,
+    MaxPainResponse,
+    MaxPainDistance,
+    MaxPainCurveRow,
+    MaxPainOiRow,
+    MaxPainByExpirationRow,
+    MaxPainDealerAlignment,
+    MaxPainExpectedMove,
     ZeroDteDecay,
     ZeroDteExpectedMove,
     ZeroDteExposures,
@@ -83,4 +90,12 @@
     "VrpRegime",
     "VrpStrategyScores",
     "VrpMacro",
+    # ── MaxPain ──
+    "MaxPainResponse",
+    "MaxPainDistance",
+    "MaxPainCurveRow",
+    "MaxPainOiRow",
+    "MaxPainByExpirationRow",
+    "MaxPainDealerAlignment",
+    "MaxPainExpectedMove",
 ]

src/flashalpha/types.py

@@ -709,3 +709,193 @@ class VrpResponse(TypedDict, total=False):
     warnings: List[str]
     # Macro context. See ``VrpMacro``.
     macro: VrpMacro
+
+
+# ─── MaxPain ─────────────────────────────────────────────────────────────────
+#
+# Typed model for ``GET /v1/maxpain/{symbol}`` (Basic+).
+#
+# Max pain is the strike where total option-holder intrinsic value across all
+# OI in the chain is minimized — equivalently, the strike at which dealers
+# (the counterparty) lose the least to expiring contracts. The endpoint also
+# overlays GEX-based dealer alignment, a multi-expiry calendar (full chain
+# only), and a 0-100 pin probability score.
+
+
+class MaxPainDistance(TypedDict, total=False):
+    """Distance from spot to the max-pain strike."""
+
+    # Dollar distance: ``|underlying_price - max_pain_strike|``.
+    absolute: Optional[float]
+    # Percent of spot: ``absolute / underlying_price * 100``. Use this to
+    # compare across symbols of different price levels.
+    percent: Optional[float]
+    # ``"above"`` (spot > max_pain), ``"below"`` (spot < max_pain), or
+    # ``"at"`` (within rounding). The signal field uses this + a 5%
+    # threshold to derive the bullish/bearish/neutral classification.
+    direction: Optional[Literal["above", "below", "at"]]
+
+
+class MaxPainCurveRow(TypedDict, total=False):
+    """One row of the strike-by-strike pain curve.
+
+    Each row is the dollar pain (intrinsic value × OI × 100 contract
+    multiplier) summed across all expirations at that strike. The strike
+    where ``total_pain`` is minimized is the max-pain strike.
+    """
+
+    strike: Optional[float]
+    # Dollar intrinsic value of all calls at this strike summed across the
+    # chain (when spot pins here, this is what call holders collectively win
+    # vs the dealer side).
+    call_pain: Optional[float]
+    # Dollar intrinsic value of all puts at this strike. Mirror of
+    # ``call_pain`` for the put side.
+    put_pain: Optional[float]
+    # ``call_pain + put_pain``. The pain curve's minimum identifies max pain.
+    total_pain: Optional[float]
+
+
+class MaxPainOiRow(TypedDict, total=False):
+    """One row of the OI-by-strike breakdown.
+
+    Per-strike open interest and volume by side. Lets you see where the
+    OI is concentrated independent of the dollar-weighted pain calculation.
+
+    Note: on the Historical API, ``call_volume`` and ``put_volume`` are
+    always ``0`` (placeholder fields — the minute table doesn't carry
+    intraday volume).
+    """
+
+    strike: Optional[float]
+    call_oi: Optional[int]
+    put_oi: Optional[int]
+    total_oi: Optional[int]
+    call_volume: Optional[int]
+    put_volume: Optional[int]
+
+
+class MaxPainByExpirationRow(TypedDict, total=False):
+    """Per-expiry max-pain breakdown when no ``expiration`` filter is applied.
+
+    Lets you see how max pain shifts across the term structure — useful for
+    spotting cases where the front-week max pain differs sharply from the
+    LEAP max pain (often a sign of where the dealer flow is most active).
+
+    This list is ``None`` when the request specifies an ``expiration``
+    filter — the response is then scoped to that single expiry and the
+    multi-expiry view is suppressed.
+    """
+
+    # ``"yyyy-MM-dd"`` of this expiry.
+    expiration: Optional[str]
+    # Max-pain strike for this expiry's option chain alone.
+    max_pain_strike: Optional[float]
+    # Days to expiry (counting from ``as_of``).
+    dte: Optional[int]
+    # Sum of OI across all contracts at this expiry.
+    total_oi: Optional[int]
+
+
+class MaxPainDealerAlignment(TypedDict, total=False):
+    """GEX-based dealer-alignment overlay on the max-pain view.
+
+    Re-uses the same gamma-exposure inputs as ``/v1/exposure/levels`` and
+    ``/v1/exposure/summary``. The headline ``alignment`` label tells you
+    whether dealer hedging will REINFORCE the max-pain pin or fight it:
+
+        - ``"converging"``: max pain near gamma flip and between the
+          walls — dealer hedging supports the pin (strongest pin setup).
+        - ``"moderate"``: max pain between the walls but far from flip.
+        - ``"diverging"``: max pain outside the wall range — dealer
+          hedging actively pushes spot away from max pain.
+        - ``"unknown"``: insufficient data to classify.
+    """
+
+    alignment: Optional[Literal["converging", "moderate", "diverging", "unknown"]]
+    # Plain-English explanation. Safe to surface verbatim.
+    description: Optional[str]
+    # Strike where net dealer gamma crosses zero. Same definition as
+    # ``exposure_summary.gamma_flip``.
+    gamma_flip: Optional[float]
+    # Strike with highest absolute call GEX (dealer-side resistance).
+    call_wall: Optional[float]
+    # Strike with highest absolute put GEX (dealer-side support).
+    put_wall: Optional[float]
+
+
+class MaxPainExpectedMove(TypedDict, total=False):
+    """Implied move from the ATM straddle, contextualized vs max pain.
+
+    Tells you whether the max-pain strike is even reachable within the
+    options-implied 1σ move. If ``max_pain_within_expected_range`` is
+    ``False``, the pin is unlikely to play out by expiry under the current
+    IV regime — the magnet exists but spot probably can't get there.
+    """
+
+    # ATM straddle mid in dollars. Rough proxy for the 1σ implied move.
+    straddle_price: Optional[float]
+    # ATM implied volatility (annualised %, e.g. 18.5 = 18.5%).
+    atm_iv: Optional[float]
+    # ``True`` when ``|spot - max_pain_strike| <= straddle_price``.
+    max_pain_within_expected_range: Optional[bool]
+
+
+class MaxPainResponse(TypedDict, total=False):
+    """Max pain dashboard from ``GET /v1/maxpain/{symbol}``.
+
+    Returns the strike where total option-holder pain (intrinsic value × OI)
+    is minimized, plus:
+
+        - per-strike pain curve and OI breakdown
+        - per-expiry calendar (when no ``expiration`` filter is set)
+        - GEX-based dealer alignment overlay (call wall / put wall /
+          gamma flip — same numbers as ``/v1/exposure/levels``)
+        - expected move from the ATM straddle
+        - 0-100 pin probability composite
+
+    The endpoint accepts an optional ``expiration`` query filter
+    (``yyyy-MM-dd``). When present, the response is scoped to that single
+    expiry and ``max_pain_by_expiration`` is ``None``. When absent, the
+    full-chain max pain is returned alongside the multi-expiry calendar.
+
+    Returns 403 ``tier_restricted`` for Free-tier users; requires Basic+.
+    """
+
+    symbol: str
+    underlying_price: Optional[float]
+    as_of: str
+    # The headline number. Strike where total chain pain is minimized.
+    max_pain_strike: Optional[float]
+    # Distance from spot to ``max_pain_strike`` (absolute, percent, direction).
+    distance: MaxPainDistance
+    # ``"bullish"`` (spot >= 5% below max_pain — pin attracts upside),
+    # ``"bearish"`` (>= 5% above), or ``"neutral"`` (within 5%).
+    signal: Optional[Literal["bullish", "bearish", "neutral"]]
+    # Expiration this view is scoped to. When the request omits the
+    # ``expiration`` filter, this field is the front-month expiry the
+    # full-chain max pain happened to land on.
+    expiration: Optional[str]
+    # Total put OI / total call OI across the relevant chain. >1.0 means
+    # put-heavy positioning. Often correlates with ``signal == "bullish"``
+    # (puts are protection; heavy-put chains often have spot below max pain).
+    put_call_oi_ratio: Optional[float]
+    # Strike-by-strike pain curve. The minimum is at ``max_pain_strike``.
+    pain_curve: List[MaxPainCurveRow]
+    # Per-strike OI + volume breakdown. Same strike grid as ``pain_curve``.
+    oi_by_strike: List[MaxPainOiRow]
+    # Per-expiry calendar. ``None`` when the request specified an expiry.
+    max_pain_by_expiration: Optional[List[MaxPainByExpirationRow]]
+    # GEX-based dealer alignment overlay. See ``MaxPainDealerAlignment``.
+    dealer_alignment: MaxPainDealerAlignment
+    # Same gamma classification as on ``exposure_summary``:
+    # positive_gamma | negative_gamma | neutral | undetermined.
+    regime: Optional[Literal["positive_gamma", "negative_gamma",
+                              "neutral", "undetermined"]]
+    # Expected move from the ATM straddle, contextualized vs max pain.
+    expected_move: MaxPainExpectedMove
+    # 0-100 composite — likelihood of pinning to ``max_pain_strike``.
+    # Inputs: OI concentration (30%), magnet proximity (25%), time
+    # remaining (25%), gamma magnitude (20%). Most meaningful for near-term
+    # expiries — for LEAPs this score will be low regardless of OI shape.
+    pin_probability: Optional[int]

tests/test_integration.py

@@ -554,6 +554,78 @@ def test_max_pain_multi_expiry_calendar(fa):
         assert "dte" in entry
 
 
+def test_max_pain_every_field_declared_in_poco_must_be_referenced(fa):
+    """Every leaf field declared in MaxPainResponse must be referenced.
+
+    100% field-coverage discipline (mirrors VRP / ExposureSummary contract).
+    Customer traps explicitly checked: signal/regime literal sets,
+    distance.direction casing, oi_by_strike row shape, dealer_alignment
+    structure, expected_move structure.
+    """
+    r = fa.max_pain("SPY")
+
+    # ── top-level scalars ──
+    assert r["symbol"] == "SPY"
+    assert isinstance(r["underlying_price"], (int, float)) and r["underlying_price"] > 0
+    assert isinstance(r["as_of"], str) and r["as_of"]
+    assert isinstance(r["max_pain_strike"], (int, float))
+    assert r["signal"] in ("bullish", "bearish", "neutral")
+    assert isinstance(r["expiration"], str) and r["expiration"]
+    assert isinstance(r["put_call_oi_ratio"], (int, float))
+    assert r["regime"] in ("positive_gamma", "negative_gamma", "neutral", "undetermined")
+    assert isinstance(r["pin_probability"], int) and 0 <= r["pin_probability"] <= 100
+
+    # ── distance{absolute, percent, direction} ──
+    dist = r["distance"]
+    assert isinstance(dist["absolute"], (int, float))
+    assert isinstance(dist["percent"], (int, float))
+    assert dist["direction"] in ("above", "below", "at")
+
+    # ── pain_curve[]{strike, call_pain, put_pain, total_pain} ──
+    pc = r["pain_curve"]
+    assert isinstance(pc, list) and len(pc) > 0
+    row = pc[0]
+    assert isinstance(row["strike"], (int, float))
+    assert isinstance(row["call_pain"], (int, float))
+    assert isinstance(row["put_pain"], (int, float))
+    assert isinstance(row["total_pain"], (int, float))
+
+    # ── oi_by_strike[]{strike, call_oi, put_oi, total_oi, call_volume, put_volume} ──
+    oi = r["oi_by_strike"]
+    assert isinstance(oi, list) and len(oi) > 0
+    oirow = oi[0]
+    assert isinstance(oirow["strike"], (int, float))
+    assert isinstance(oirow["call_oi"], int)
+    assert isinstance(oirow["put_oi"], int)
+    assert isinstance(oirow["total_oi"], int)
+    assert isinstance(oirow["call_volume"], int)
+    assert isinstance(oirow["put_volume"], int)
+
+    # ── max_pain_by_expiration[]{expiration, max_pain_strike, dte, total_oi} ──
+    # Populated when no expiration filter is applied (this call uses none).
+    mpe = r["max_pain_by_expiration"]
+    assert isinstance(mpe, list) and len(mpe) > 0
+    mrow = mpe[0]
+    assert isinstance(mrow["expiration"], str) and mrow["expiration"]
+    assert isinstance(mrow["max_pain_strike"], (int, float))
+    assert isinstance(mrow["dte"], int)
+    assert isinstance(mrow["total_oi"], int)
+
+    # ── dealer_alignment{alignment, description, gamma_flip, call_wall, put_wall} ──
+    da = r["dealer_alignment"]
+    assert da["alignment"] in ("converging", "moderate", "diverging", "unknown")
+    assert isinstance(da["description"], str) and da["description"]
+    assert isinstance(da["gamma_flip"], (int, float))
+    assert isinstance(da["call_wall"], (int, float))
+    assert isinstance(da["put_wall"], (int, float))
+
+    # ── expected_move{straddle_price, atm_iv, max_pain_within_expected_range} ──
+    em = r["expected_move"]
+    assert isinstance(em["straddle_price"], (int, float))
+    assert isinstance(em["atm_iv"], (int, float))
+    assert isinstance(em["max_pain_within_expected_range"], bool)
+
+
 # ── Screener ────────────────────────────────────────────────────────