flashalpha 0.3.0__tar.gz → 0.3.2__tar.gz

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

@@ -38,7 +38,14 @@
       "Bash(FLASHALPHA_API_KEY=\"ejbe0oW5f4n7C7drEg7Ggo6bPtFuFpaLPmvmkDrE\" npx jest tests/integration.test.ts -t \"screener\")",
       "Bash(FLASHALPHA_API_KEY=\"ejbe0oW5f4n7C7drEg7Ggo6bPtFuFpaLPmvmkDrE\" \"C:/Users/disea/tools/apache-maven-3.9.14/bin/mvn.cmd\" test -Dtest=\"IntegrationTest#testScreener*\")",
       "Bash(where.exe go:*)",
-      "Bash(npm whoami:*)"
+      "Bash(npm whoami:*)",
+      "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(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.0 → flashalpha-0.3.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: flashalpha
-Version: 0.3.0
+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.0 → flashalpha-0.3.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "flashalpha"
-version = "0.3.0"
+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.0 → flashalpha-0.3.2}/src/flashalpha/__init__.py

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

{flashalpha-0.3.0 → 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(
@@ -375,7 +394,7 @@ class FlashAlpha:
             body["limit"] = limit
         if offset is not None:
             body["offset"] = offset
-        return self._post("/v1/screener/live", body)
+        return self._post("/v1/screener", body)
 
     # ── Account & System ────────────────────────────────────────────
 

{flashalpha-0.3.0 → 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
@@ -336,7 +405,7 @@ def test_screener_empty(fa):
         "meta": {"total_count": 10, "returned_count": 10, "tier": "growth"},
         "data": [{"symbol": "SPY", "price": 656.01}],
     }
-    responses.post(f"{BASE}/v1/screener/live", json=payload)
+    responses.post(f"{BASE}/v1/screener", json=payload)
     result = fa.screener()
     assert result["meta"]["tier"] == "growth"
     assert result["data"][0]["symbol"] == "SPY"
@@ -346,18 +415,18 @@ def test_screener_empty(fa):
 
 @responses.activate
 def test_screener_sends_post_with_json_content_type(fa):
-    responses.post(f"{BASE}/v1/screener/live", json={"meta": {}, "data": []})
+    responses.post(f"{BASE}/v1/screener", json={"meta": {}, "data": []})
     fa.screener(limit=5)
     req = responses.calls[0].request
     assert req.method == "POST"
-    assert req.url == f"{BASE}/v1/screener/live"
+    assert req.url == f"{BASE}/v1/screener"
     assert req.headers.get("Content-Type") == "application/json"
     assert req.headers.get("X-Api-Key") == "test-key"
 
 
 @responses.activate
 def test_screener_leaf_filter(fa):
-    responses.post(f"{BASE}/v1/screener/live", json={"meta": {}, "data": []})
+    responses.post(f"{BASE}/v1/screener", json={"meta": {}, "data": []})
     fa.screener(filters={"field": "regime", "operator": "eq", "value": "positive_gamma"})
     body = _screener_body(responses.calls[0])
     assert body["filters"]["field"] == "regime"
@@ -367,7 +436,7 @@ def test_screener_leaf_filter(fa):
 
 @responses.activate
 def test_screener_and_group(fa):
-    responses.post(f"{BASE}/v1/screener/live", json={"meta": {}, "data": []})
+    responses.post(f"{BASE}/v1/screener", json={"meta": {}, "data": []})
     fa.screener(
         filters={
             "op": "and",
@@ -390,7 +459,7 @@ def test_screener_and_group(fa):
 
 @responses.activate
 def test_screener_or_group(fa):
-    responses.post(f"{BASE}/v1/screener/live", json={"meta": {}, "data": []})
+    responses.post(f"{BASE}/v1/screener", json={"meta": {}, "data": []})
     fa.screener(
         filters={
             "op": "or",
@@ -406,7 +475,7 @@ def test_screener_or_group(fa):
 
 @responses.activate
 def test_screener_nested_and_inside_or(fa):
-    responses.post(f"{BASE}/v1/screener/live", json={"meta": {}, "data": []})
+    responses.post(f"{BASE}/v1/screener", json={"meta": {}, "data": []})
     fa.screener(
         filters={
             "op": "or",
@@ -436,7 +505,7 @@ def test_screener_nested_and_inside_or(fa):
 
 @responses.activate
 def test_screener_between_operator(fa):
-    responses.post(f"{BASE}/v1/screener/live", json={"meta": {}, "data": []})
+    responses.post(f"{BASE}/v1/screener", json={"meta": {}, "data": []})
     fa.screener(filters={"field": "atm_iv", "operator": "between", "value": [15, 25]})
     body = _screener_body(responses.calls[0])
     assert body["filters"]["operator"] == "between"
@@ -445,7 +514,7 @@ def test_screener_between_operator(fa):
 
 @responses.activate
 def test_screener_in_operator(fa):
-    responses.post(f"{BASE}/v1/screener/live", json={"meta": {}, "data": []})
+    responses.post(f"{BASE}/v1/screener", json={"meta": {}, "data": []})
     fa.screener(filters={"field": "term_state", "operator": "in", "value": ["contango", "mixed"]})
     body = _screener_body(responses.calls[0])
     assert body["filters"]["operator"] == "in"
@@ -454,7 +523,7 @@ def test_screener_in_operator(fa):
 
 @responses.activate
 def test_screener_null_operators(fa):
-    responses.post(f"{BASE}/v1/screener/live", json={"meta": {}, "data": []})
+    responses.post(f"{BASE}/v1/screener", json={"meta": {}, "data": []})
     fa.screener(filters={"field": "vrp_regime", "operator": "is_not_null"})
     body = _screener_body(responses.calls[0])
     assert body["filters"]["operator"] == "is_not_null"
@@ -464,7 +533,7 @@ def test_screener_null_operators(fa):
 @responses.activate
 def test_screener_cascading_filters(fa):
     """Cascading filters on expiries/strikes/contracts levels."""
-    responses.post(f"{BASE}/v1/screener/live", json={"meta": {}, "data": []})
+    responses.post(f"{BASE}/v1/screener", json={"meta": {}, "data": []})
     fa.screener(
         filters={
             "op": "and",
@@ -489,7 +558,7 @@ def test_screener_cascading_filters(fa):
 
 @responses.activate
 def test_screener_with_formulas(fa):
-    responses.post(f"{BASE}/v1/screener/live", json={"meta": {}, "data": []})
+    responses.post(f"{BASE}/v1/screener", json={"meta": {}, "data": []})
     fa.screener(
         formulas=[{"alias": "vrp_ratio", "expression": "atm_iv / rv_20d"}],
         filters={"formula": "vrp_ratio", "operator": "gte", "value": 1.2},
@@ -504,7 +573,7 @@ def test_screener_with_formulas(fa):
 
 @responses.activate
 def test_screener_inline_formula(fa):
-    responses.post(f"{BASE}/v1/screener/live", json={"meta": {}, "data": []})
+    responses.post(f"{BASE}/v1/screener", json={"meta": {}, "data": []})
     fa.screener(
         filters={"formula": "atm_iv - rv_20d", "operator": "gt", "value": 6},
     )
@@ -514,7 +583,7 @@ def test_screener_inline_formula(fa):
 
 @responses.activate
 def test_screener_multi_sort(fa):
-    responses.post(f"{BASE}/v1/screener/live", json={"meta": {}, "data": []})
+    responses.post(f"{BASE}/v1/screener", json={"meta": {}, "data": []})
     fa.screener(
         sort=[
             {"field": "dealer_flow_risk", "direction": "asc"},
@@ -530,7 +599,7 @@ def test_screener_multi_sort(fa):
 
 @responses.activate
 def test_screener_pagination(fa):
-    responses.post(f"{BASE}/v1/screener/live", json={"meta": {}, "data": []})
+    responses.post(f"{BASE}/v1/screener", json={"meta": {}, "data": []})
     fa.screener(limit=10, offset=10)
     body = _screener_body(responses.calls[0])
     assert body["limit"] == 10
@@ -539,7 +608,7 @@ def test_screener_pagination(fa):
 
 @responses.activate
 def test_screener_negative_number(fa):
-    responses.post(f"{BASE}/v1/screener/live", json={"meta": {}, "data": []})
+    responses.post(f"{BASE}/v1/screener", json={"meta": {}, "data": []})
     fa.screener(filters={"field": "net_gex", "operator": "lt", "value": -500000})
     body = _screener_body(responses.calls[0])
     assert body["filters"]["value"] == -500000
@@ -547,7 +616,7 @@ def test_screener_negative_number(fa):
 
 @responses.activate
 def test_screener_select_star(fa):
-    responses.post(f"{BASE}/v1/screener/live", json={"meta": {}, "data": []})
+    responses.post(f"{BASE}/v1/screener", json={"meta": {}, "data": []})
     fa.screener(select=["*"])
     body = _screener_body(responses.calls[0])
     assert body["select"] == ["*"]
@@ -555,7 +624,7 @@ def test_screener_select_star(fa):
 
 @responses.activate
 def test_screener_select_star_with_formula(fa):
-    responses.post(f"{BASE}/v1/screener/live", json={"meta": {}, "data": []})
+    responses.post(f"{BASE}/v1/screener", json={"meta": {}, "data": []})
     fa.screener(
         formulas=[{"alias": "ratio", "expression": "call_wall / (put_wall + 30)"}],
         select=["*", "ratio"],
@@ -580,7 +649,7 @@ def test_screener_returns_response_structure(fa):
             {"symbol": "SPY", "price": 656.01, "regime": "positive_gamma", "atm_iv": 20.7}
         ],
     }
-    responses.post(f"{BASE}/v1/screener/live", json=payload)
+    responses.post(f"{BASE}/v1/screener", json=payload)
     result = fa.screener()
     assert result["meta"]["tier"] == "alpha"
     assert result["meta"]["universe_size"] == 250
@@ -594,7 +663,7 @@ def test_screener_tier_restricted_alpha_field(fa):
         "error": "validation_error",
         "message": "Field 'harvest_score' requires the Alpha plan or higher.",
     }
-    responses.post(f"{BASE}/v1/screener/live", json=err_body, status=400)
+    responses.post(f"{BASE}/v1/screener", json=err_body, status=400)
     with pytest.raises(FlashAlphaError) as exc:
         fa.screener(filters={"field": "harvest_score", "operator": "gte", "value": 65})
     assert exc.value.status_code == 400
@@ -608,7 +677,7 @@ def test_screener_formula_error(fa):
         "error": "formula_error",
         "message": "Unexpected token '+' at position 5",
     }
-    responses.post(f"{BASE}/v1/screener/live", json=err_body, status=400)
+    responses.post(f"{BASE}/v1/screener", json=err_body, status=400)
     with pytest.raises(FlashAlphaError):
         fa.screener(formulas=[{"alias": "bad", "expression": "+ atm_iv"}])
 
@@ -622,7 +691,7 @@ def test_screener_tier_restricted_403(fa):
         "current_plan": "Free",
         "required_plan": "Growth",
     }
-    responses.post(f"{BASE}/v1/screener/live", json=err_body, status=403)
+    responses.post(f"{BASE}/v1/screener", json=err_body, status=403)
     with pytest.raises(TierRestrictedError) as exc:
         fa.screener()
     assert exc.value.current_plan == "Free"

{flashalpha-0.3.0 → 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 ────────────────────────────────────────────────────────