flashalpha 0.3.1__tar.gz → 0.3.2__tar.gz

{flashalpha-0.3.1 → flashalpha-0.3.2}/.claude/settings.json

@@ -42,7 +42,10 @@
       "Bash(grep -rhE \"oy2[a-z0-9]{40,46}|NUGET_API_KEY|NUGET_TOKEN\" --include=\"*.env\" --include=\"*.env.local\" --include=\"*.env.example\" --include=\".env*\")",
       "Bash(npm profile:*)",
       "Bash(NPM_CONFIG_TOKEN=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 npm publish --//registry.npmjs.org/:_authToken=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)",
-      "Bash(npm config:*)"
+      "Bash(npm config:*)",
+      "Bash(export PATH=\"$PATH:/c/Program Files/Go/bin\")",
+      "Bash(go test:*)",
+      "Bash(FLASHALPHA_API_KEY=\"ejbe0oW5f4n7C7drEg7Ggo6bPtFuFpaLPmvmkDrE\" \"C:/Users/disea/tools/apache-maven-3.9.14/bin/mvn.cmd\" test -Dtest=\"IntegrationTest#testMaxPain*\")"
     ],
     "additionalDirectories": [
       "C:\\Users\\disea"

{flashalpha-0.3.1 → flashalpha-0.3.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: flashalpha
-Version: 0.3.1
+Version: 0.3.2
 Summary: Python SDK for the FlashAlpha options analytics API — live options screener, gamma exposure (GEX), VRP, delta, vanna, charm, greeks, 0DTE analytics, volatility surfaces, and more.
 Project-URL: Homepage, https://flashalpha.com
 Project-URL: Documentation, https://flashalpha.com/docs

{flashalpha-0.3.1 → flashalpha-0.3.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "flashalpha"
-version = "0.3.1"
+version = "0.3.2"
 description = "Python SDK for the FlashAlpha options analytics API — live options screener, gamma exposure (GEX), VRP, delta, vanna, charm, greeks, 0DTE analytics, volatility surfaces, and more."
 readme = "README.md"
 license = "MIT"

{flashalpha-0.3.1 → flashalpha-0.3.2}/src/flashalpha/__init__.py

@@ -10,7 +10,7 @@ from .exceptions import (
     TierRestrictedError,
 )
 
-__version__ = "0.3.1"
+__version__ = "0.3.2"
 __all__ = [
     "FlashAlpha",
     "FlashAlphaError",

{flashalpha-0.3.1 → flashalpha-0.3.2}/src/flashalpha/client.py

@@ -299,6 +299,25 @@ class FlashAlpha:
         """Currently queried symbols with live data."""
         return self._get("/v1/symbols")
 
+    # ── Max Pain ────────────────────────────────────────────────────
+
+    def max_pain(self, symbol: str, *, expiration: str | None = None) -> dict:
+        """Max pain analysis with dealer alignment overlay, pain curve, OI
+        breakdown, expected move context, pin probability, and multi-expiry
+        calendar. Requires Growth+.
+
+        Parameters
+        ----------
+        symbol : str
+            Underlying symbol.
+        expiration : str, optional
+            Filter to single expiry (YYYY-MM-DD). Omit for full-chain analysis.
+        """
+        params: dict[str, Any] = {}
+        if expiration:
+            params["expiration"] = expiration
+        return self._get(f"/v1/maxpain/{symbol}", params or None)
+
     # ── Screener ────────────────────────────────────────────────────
 
     def screener(

{flashalpha-0.3.1 → flashalpha-0.3.2}/tests/test_client.py

@@ -321,6 +321,75 @@ def test_health(fa):
     assert result["status"] == "Healthy"
 
 
+# ── Max Pain ────────────────────────────────────────────────────────
+
+
+@responses.activate
+def test_max_pain(fa):
+    payload = {"symbol": "SPY", "max_pain_strike": 545, "pin_probability": 68}
+    responses.get(f"{BASE}/v1/maxpain/SPY", json=payload)
+    result = fa.max_pain("SPY")
+    assert result["max_pain_strike"] == 545
+    assert result["pin_probability"] == 68
+
+
+@responses.activate
+def test_max_pain_calls_correct_path(fa):
+    responses.get(f"{BASE}/v1/maxpain/AAPL", json={})
+    fa.max_pain("AAPL")
+    assert "/v1/maxpain/AAPL" in responses.calls[0].request.url
+
+
+@responses.activate
+def test_max_pain_with_expiration(fa):
+    responses.get(f"{BASE}/v1/maxpain/SPY", json={})
+    fa.max_pain("SPY", expiration="2026-04-17")
+    assert "expiration=2026-04-17" in responses.calls[0].request.url
+
+
+@responses.activate
+def test_max_pain_without_expiration(fa):
+    responses.get(f"{BASE}/v1/maxpain/SPY", json={"max_pain_by_expiration": [{"expiration": "2026-04-17"}]})
+    result = fa.max_pain("SPY")
+    assert "max_pain_by_expiration" in result
+
+
+@responses.activate
+def test_max_pain_full_response(fa):
+    payload = {
+        "symbol": "SPY",
+        "underlying_price": 548.32,
+        "max_pain_strike": 545,
+        "distance": {"absolute": 3.32, "percent": 0.61, "direction": "above"},
+        "signal": "neutral",
+        "put_call_oi_ratio": 1.284,
+        "pain_curve": [{"strike": 545, "total_pain": 3700000}],
+        "oi_by_strike": [{"strike": 545, "call_oi": 35000, "put_oi": 42000}],
+        "dealer_alignment": {"alignment": "converging", "gamma_flip": 546},
+        "regime": "positive_gamma",
+        "expected_move": {"max_pain_within_expected_range": True},
+        "pin_probability": 68,
+    }
+    responses.get(f"{BASE}/v1/maxpain/SPY", json=payload)
+    result = fa.max_pain("SPY")
+    assert result["distance"]["direction"] == "above"
+    assert result["dealer_alignment"]["alignment"] == "converging"
+    assert result["signal"] == "neutral"
+    assert result["regime"] == "positive_gamma"
+
+
+@responses.activate
+def test_max_pain_403_tier_restricted(fa):
+    responses.get(
+        f"{BASE}/v1/maxpain/SPY",
+        json={"status": "ERROR", "error": "tier_restricted", "message": "Requires Growth plan.", "current_plan": "Free", "required_plan": "Growth"},
+        status=403,
+    )
+    with pytest.raises(TierRestrictedError) as exc:
+        fa.max_pain("SPY")
+    assert exc.value.current_plan == "Free"
+
+
 # ── Screener ───────────────────────────────────────────────────────
 
 import json as _json

{flashalpha-0.3.1 → flashalpha-0.3.2}/tests/test_integration.py

@@ -221,6 +221,55 @@ def test_symbols(fa):
     assert isinstance(result["symbols"], list)
 
 
+# ── Max Pain ─────────────────────────────────────────────────────────
+
+
+def test_max_pain(fa):
+    result = fa.max_pain("SPY")
+    assert "max_pain_strike" in result
+    assert "pain_curve" in result
+    assert "dealer_alignment" in result
+    assert "pin_probability" in result
+    assert isinstance(result["pain_curve"], list)
+
+
+def test_max_pain_response_fields(fa):
+    result = fa.max_pain("SPY")
+    assert "distance" in result
+    assert result["distance"]["direction"] in ("above", "below", "at")
+    assert result["signal"] in ("bullish", "bearish", "neutral")
+    assert result["regime"] in ("positive_gamma", "negative_gamma")
+
+
+def test_max_pain_with_expiration(fa):
+    # Get first available expiration
+    opts = fa.options("SPY")
+    if opts.get("expirations") and len(opts["expirations"]) > 0:
+        exp = opts["expirations"][0]["expiration"]
+        result = fa.max_pain("SPY", expiration=exp)
+        assert result["expiration"] == exp
+        assert "max_pain_strike" in result
+
+
+def test_max_pain_oi_by_strike(fa):
+    result = fa.max_pain("SPY")
+    if result.get("oi_by_strike"):
+        row = result["oi_by_strike"][0]
+        assert "strike" in row
+        assert "call_oi" in row
+        assert "put_oi" in row
+
+
+def test_max_pain_multi_expiry_calendar(fa):
+    """Without expiration filter, max_pain_by_expiration should be populated."""
+    result = fa.max_pain("SPY")
+    if result.get("max_pain_by_expiration"):
+        entry = result["max_pain_by_expiration"][0]
+        assert "expiration" in entry
+        assert "max_pain_strike" in entry
+        assert "dte" in entry
+
+
 # ── Screener ────────────────────────────────────────────────────────