1.0.1: add flow signals endpoints

- flow_signals(symbol, ...) — scored, classified unusual-flow feed
  (block/sweep, NBBO aggressor, opening/closing bias, intent) with a
  0-100 composite score, transparent component breakdown, and
  chain-context enrichment (greeks, IV-vs-ATM, moneyness, est.
  delta-notional).
- flow_signals_summary(symbol, ...) — net bullish/bearish +
  opening/closing premium roll-up plus the top 10 signals.
- New TypedDicts: FlowSignal, FlowSignalsResponse,
  FlowSignalsSummaryResponse, FlowSignalsChain,
  FlowSignalScoreBreakdown, FlowSignalEnrichment.
- llms.txt + CHANGELOG.md updated for the 24-endpoint flow surface.
- Live integration tests for both endpoints.

All endpoints require Alpha+.

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

Author: tdobrowolski1

CHANGELOG.md

@@ -1,5 +1,20 @@
 # Changelog
 
+## 1.0.1 - 2026-05-21
+
+### Added
+- `flow_signals(symbol, ...)` and `flow_signals_summary(symbol, ...)` —
+  scored, classified unusual-flow feed for one underlying. Each notable
+  print is coalesced into a signal (block/sweep, NBBO aggressor,
+  opening/closing bias, intent), scored 0-100 with a transparent
+  component breakdown, and enriched with chain context (greeks,
+  IV-vs-ATM, moneyness, estimated delta-notional). Summary endpoint
+  rolls up net bullish/bearish and opening/closing premium plus the top
+  10 signals. New `TypedDict` types: `FlowSignal`, `FlowSignalsResponse`,
+  `FlowSignalsSummaryResponse`, `FlowSignalsChain`,
+  `FlowSignalScoreBreakdown`, `FlowSignalEnrichment`. Requires Alpha.
+- Live integration tests for both signals endpoints.
+
 ## 1.0.0 - 2026-05-15
 
 ### Added

llms.txt

@@ -81,14 +81,19 @@ narrative = client.exposure_narrative("SPY")
 ## Flow — live, simulation-aware (Alpha+)
 
 Intraday trade-tape-adjusted dealer exposure plus the raw options/stock
-flow feed — 22 endpoints under `/v1/flow/*`:
+flow feed — 24 endpoints under `/v1/flow/*`:
 
 - **Analytics** (snake_case): `flow_levels`, `flow_pin_risk`,
   `flow_summary`, `flow_oi`, `flow_gex`, `flow_dex`, `flow_dealer_risk`,
   `flow_live` — live gamma flip / call & put walls / max pain, 0DTE
   pin score, flow direction + headline GEX shift, OI simulator state,
   flow-adjusted GEX/DEX per strike, settled-vs-live dealer risk, and an
   everything-at-once bundle. Optional `expiry="YYYY-MM-DD"` slice.
+- **Unusual-flow signals** (snake_case): `flow_signals` /
+  `flow_signals_summary` — scored, classified per-print signals
+  (block/sweep, NBBO aggressor, opening/closing bias, intent) with a
+  0-100 composite score, chain-context enrichment, and a net
+  bullish/bearish + opening/closing premium roll-up.
 - **Raw flow** (camelCase wire keys): `flow_option_recent` /
   `flow_option_summary` / `flow_option_blocks` / `flow_option_history` /
   `flow_option_cumulative`, the `flow_stock_*` equivalents, and

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "flashalpha"
-version = "1.0.0"
+version = "1.0.1"
 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"

src/flashalpha/__init__.py

@@ -38,6 +38,12 @@
     FlowOutlierRow,
     FlowPinRiskBreakdown,
     FlowPinRiskResponse,
+    FlowSignal,
+    FlowSignalEnrichment,
+    FlowSignalScoreBreakdown,
+    FlowSignalsChain,
+    FlowSignalsResponse,
+    FlowSignalsSummaryResponse,
     FlowStockBlock,
     FlowStockBlocksResponse,
     FlowStockCumulativeResponse,
@@ -347,4 +353,10 @@
     "FlowStockLeaderRow",
     "FlowStockLeaderboardResponse",
     "FlowStockOutliersResponse",
+    "FlowSignalsChain",
+    "FlowSignalScoreBreakdown",
+    "FlowSignalEnrichment",
+    "FlowSignal",
+    "FlowSignalsResponse",
+    "FlowSignalsSummaryResponse",
 ]

src/flashalpha/client.py

@@ -38,6 +38,8 @@
         FlowOptionRecentResponse,
         FlowOptionSummaryResponse,
         FlowPinRiskResponse,
+        FlowSignalsResponse,
+        FlowSignalsSummaryResponse,
         FlowStockBlocksResponse,
         FlowStockCumulativeResponse,
         FlowStockHistoryResponse,
@@ -479,6 +481,65 @@ def flow_stocks_outliers(
             params["windowMinutes"] = window_minutes
         return self._get("/v1/flow/stocks/outliers", params or None)
 
+    # Flow signals (unusual-flow feed, Alpha+).
+
+    def flow_signals(
+        self,
+        symbol: str,
+        *,
+        min_score: int | None = None,
+        intent: str | None = None,
+        structure: str | None = None,
+        window_minutes: int | None = None,
+        limit: int | None = None,
+        expiry: str | None = None,
+    ) -> FlowSignalsResponse:
+        """Scored unusual-flow feed for one underlying. Requires Alpha.
+
+        Each notable print is coalesced into a signal, classified
+        (block/sweep, NBBO aggressor, opening/closing bias, intent), and
+        scored 0–100 with a transparent component breakdown. Ranked by
+        score, highest first.
+
+        ``min_score`` drops signals below the threshold; ``intent``
+        filters to ``"bullish"``/``"bearish"``/``"neutral"``;
+        ``structure`` filters to ``"block"``/``"sweep"``;
+        ``window_minutes`` sets the look-back (1–10080, default 240);
+        ``limit`` caps the response (1–500, default 50); ``expiry``
+        filters to a single ``YYYY-MM-DD`` cycle.
+        """
+        params: dict[str, Any] = {}
+        if min_score is not None:
+            params["minScore"] = min_score
+        if intent:
+            params["intent"] = intent
+        if structure:
+            params["structure"] = structure
+        if window_minutes is not None:
+            params["windowMinutes"] = window_minutes
+        if limit is not None:
+            params["limit"] = limit
+        if expiry:
+            params["expiry"] = expiry
+        return self._get(f"/v1/flow/signals/{_seg(symbol)}", params or None)
+
+    def flow_signals_summary(
+        self,
+        symbol: str,
+        *,
+        window_minutes: int | None = None,
+        expiry: str | None = None,
+    ) -> FlowSignalsSummaryResponse:
+        """Net bullish/bearish + opening/closing premium roll-up plus
+        the top 10 signals. Cheap "smart-money tilt" read. Requires Alpha.
+        """
+        params: dict[str, Any] = {}
+        if window_minutes is not None:
+            params["windowMinutes"] = window_minutes
+        if expiry:
+            params["expiry"] = expiry
+        return self._get(f"/v1/flow/signals/{_seg(symbol)}/summary", params or None)
+
     # ── Pricing & Sizing ────────────────────────────────────────────
 
     def greeks(

src/flashalpha/types.py

@@ -3457,3 +3457,181 @@ class FlowStockOutliersResponse(TypedDict, total=False):
     limit: int
     # Imbalance-ranked flagged symbols.
     outliers: List[FlowOutlierRow]
+
+
+# ── Flow signals (unusual-flow feed, Alpha+) ─────────────────────────
+#
+# Per-underlying scored/classified unusual-flow signals. Snake_case wire
+# shape (analytics family). Both endpoints reuse ``FlowSignal``.
+
+
+class FlowSignalsChain(TypedDict, total=False):
+    """Settled-chain reference levels echoed alongside the signals.
+
+    Computed once per request from the settled snapshot — independent of
+    the live flow surface. All fields are ``None`` when the chain
+    snapshot is unavailable.
+    """
+
+    call_wall: Optional[float]
+    put_wall: Optional[float]
+    max_pain: Optional[float]
+    gamma_flip: Optional[float]
+
+
+class FlowSignalScoreBreakdown(TypedDict, total=False):
+    """Component contributions that sum to the headline ``score``.
+
+    Weights are server-tunable so absolute values may shift, but the
+    ordering of components is stable.
+    """
+
+    premium: int
+    size_vs_oi: int
+    aggressor: int
+    sweep: int
+    opening_bias: int
+    tenor: int
+
+
+class FlowSignalEnrichment(TypedDict, total=False):
+    """Chain-derived context attached to a signal.
+
+    All numeric fields are ``None`` and ``moneyness`` is ``"unknown"``
+    when the contract isn't in the settled chain snapshot.
+    """
+
+    iv: Optional[float]
+    delta: Optional[float]
+    gamma: Optional[float]
+    # IV minus the nearest ATM IV (signed).
+    iv_vs_atm: Optional[float]
+    # ``"OTM"`` / ``"ATM"`` / ``"ITM"`` / ``"unknown"``.
+    moneyness: str
+    # Estimated dollar delta-notional of this print.
+    estimated_delta_notional: Optional[float]
+    # Standalone gamma-$ this print would add if it were opening and
+    # fully dealer-absorbed. **Not** applied to the live chain — don't
+    # sum it against ``/v1/flow/gex``.
+    hypothetical_gex_impact_if_opening: Optional[float]
+
+
+class FlowSignal(TypedDict, total=False):
+    """One scored unusual-flow signal.
+
+    A signal is a coalesced view of one notable (block-sized) print on a
+    single contract: classification, scoring, and chain-context
+    enrichment. Same shape across ``/v1/flow/signals/{symbol}`` and
+    ``/v1/flow/signals/{symbol}/summary``'s ``top_signals``.
+    """
+
+    # Trade timestamp (ISO-8601 UTC).
+    ts: str
+    # Contract expiry (``YYYY-MM-DD``).
+    expiry: str
+    # Contract strike price.
+    strike: float
+    # ``"C"`` (call) or ``"P"`` (put).
+    right: str
+    # Upstream buy/sell/mid aggressor classification (distinct from the
+    # NBBO ``aggressor`` label).
+    side: str
+    # Trade price.
+    price: float
+    # Trade size in contracts.
+    size: int
+    # Dollar premium of this print: ``price * size * 100``.
+    premium: float
+    # Days to expiry at trade time.
+    dte: int
+    # ``"block"`` (lone block-sized print) or ``"sweep"`` (≥2 same-side
+    # prints on one contract within ~500ms).
+    structure: str
+    # NBBO position at trade: ``"above_ask"`` / ``"at_ask"`` / ``"mid"`` /
+    # ``"at_bid"`` / ``"below_bid"``.
+    aggressor: str
+    # Contract-level OI-simulator inference: ``"opening_bias"`` /
+    # ``"closing_bias"`` / ``"unknown"``. Not a per-print label.
+    open_close_bias: str
+    # Simulator confidence weight for the bias above.
+    open_close_confidence: float
+    # Signed simulator estimate of contracts opened (+) or closed (−)
+    # today on this contract.
+    contract_net_oi_delta: int
+    # ``"bullish"`` / ``"bearish"`` / ``"neutral"``. Neutral whenever
+    # ``open_close_bias == "closing_bias"`` (can't attribute on unwinds)
+    # or ``side == "mid"``.
+    intent: str
+    # 0–100 composite (components sum to this).
+    score: int
+    # ``"low"`` / ``"medium"`` / ``"high"``.
+    conviction: str
+    # Subset of ``"sweep"``, ``"block"``, ``"opening"``, ``"closing"``,
+    # ``"0dte"``, ``"whale"`` (premium ≥ $1M), ``"golden"`` (top decile
+    # in this response set *and* score ≥ 70 absolute).
+    tags: List[str]
+    score_breakdown: FlowSignalScoreBreakdown
+    enrichment: FlowSignalEnrichment
+
+
+class FlowSignalsResponse(TypedDict, total=False):
+    """Scored, classified unusual-flow feed from
+    ``GET /v1/flow/signals/{symbol}``.
+
+    Each notable print in the look-back window is coalesced into a
+    signal, scored 0–100, and ranked highest score first. Requires the
+    Alpha plan.
+    """
+
+    # Underlying ticker echoed from the request path.
+    symbol: str
+    # Timestamp this snapshot was computed for (ISO-8601 UTC).
+    as_of: str
+    # Look-back window applied (minutes).
+    window_minutes: int
+    # Expiration filter echoed back, or ``None``.
+    expiry: Optional[str]
+    # Spot mid at the snapshot time.
+    underlying_price: Optional[float]
+    # Settled-chain reference levels (computed once per request).
+    chain: FlowSignalsChain
+    # Number of signals returned (after server-side filtering).
+    count: int
+    # Signals, highest score first.
+    signals: List[FlowSignal]
+
+
+class FlowSignalsSummaryResponse(TypedDict, total=False):
+    """Net-directional roll-up from
+    ``GET /v1/flow/signals/{symbol}/summary``.
+
+    Sums classified premium across the window into bullish/bearish and
+    opening/closing buckets — a cheap "smart-money tilt" read for one
+    underlying. Requires the Alpha plan.
+    """
+
+    # Underlying ticker echoed from the request path.
+    symbol: str
+    # Timestamp this snapshot was computed for (ISO-8601 UTC).
+    as_of: str
+    # Look-back window applied (minutes).
+    window_minutes: int
+    # Expiration filter echoed back, or ``None``.
+    expiry: Optional[str]
+    # Spot mid at the snapshot time.
+    underlying_price: Optional[float]
+    # Total signal count in the window (full count, not the
+    # ``top_signals`` length).
+    signal_count: int
+    # Sum of signal premium with ``intent == "bullish"``.
+    bullish_premium: float
+    # Sum of signal premium with ``intent == "bearish"``.
+    bearish_premium: float
+    # ``bullish_premium - bearish_premium``.
+    net_directional_premium: float
+    # Sum of signal premium with ``open_close_bias == "opening_bias"``.
+    opening_premium: float
+    # Sum of signal premium with ``open_close_bias == "closing_bias"``.
+    closing_premium: float
+    # Highest-scoring signals (≤ 10). Same shape as ``FlowSignal``.
+    top_signals: List[FlowSignal]

tests/test_integration.py

@@ -1804,3 +1804,47 @@ def test_flow_stocks_outliers(fa):
                                     "lastVwap", "lastTradeUtc",
                                     "lastTradeAgeSec"],
                  "flow/stocks/outliers.outliers[0]")
+
+
+_SIGNAL_FIELDS = ["ts", "expiry", "strike", "right", "side", "price", "size",
+                  "premium", "dte", "structure", "aggressor",
+                  "open_close_bias", "open_close_confidence",
+                  "contract_net_oi_delta", "intent", "score", "conviction",
+                  "tags", "score_breakdown", "enrichment"]
+
+
+def test_flow_signals(fa):
+    r = _flow(lambda: fa.flow_signals(FLOW_SYMBOL, window_minutes=240,
+                                       limit=10))
+    _require(r, ["symbol", "as_of", "window_minutes", "expiry",
+                "underlying_price", "chain", "count", "signals"],
+             "flow/signals")
+    assert r["symbol"] == FLOW_SYMBOL
+    _require(r["chain"], ["call_wall", "put_wall", "max_pain", "gamma_flip"],
+             "flow/signals.chain")
+    assert isinstance(r["signals"], list)
+    if r["signals"]:
+        _require(r["signals"][0], _SIGNAL_FIELDS, "flow/signals.signals[0]")
+        _require(r["signals"][0]["score_breakdown"],
+                 ["premium", "size_vs_oi", "aggressor", "sweep",
+                  "opening_bias", "tenor"],
+                 "flow/signals.signals[0].score_breakdown")
+        _require(r["signals"][0]["enrichment"],
+                 ["iv", "delta", "gamma", "iv_vs_atm", "moneyness",
+                  "estimated_delta_notional",
+                  "hypothetical_gex_impact_if_opening"],
+                 "flow/signals.signals[0].enrichment")
+
+
+def test_flow_signals_summary(fa):
+    r = _flow(lambda: fa.flow_signals_summary(FLOW_SYMBOL, window_minutes=240))
+    _require(r, ["symbol", "as_of", "window_minutes", "expiry",
+                "underlying_price", "signal_count", "bullish_premium",
+                "bearish_premium", "net_directional_premium",
+                "opening_premium", "closing_premium", "top_signals"],
+             "flow/signals/summary")
+    assert r["symbol"] == FLOW_SYMBOL
+    assert isinstance(r["top_signals"], list)
+    if r["top_signals"]:
+        _require(r["top_signals"][0], _SIGNAL_FIELDS,
+                 "flow/signals/summary.top_signals[0]")