Flow Signals API: How FlashAlpha Scores Unusual Options Activity (Sweeps, Blocks, Opening Bias, Intent)

The unusual-options-flow market is full of black boxes. Vendors publish "scored" feeds without specifying what the score means: which trades qualify, how the score is computed, what threshold separates a meaningful signal from background noise. For a quantitative trader or a developer building a screener, this is unworkable. You cannot calibrate against a number whose derivation is hidden, and you cannot ignore false positives whose drivers you cannot see.

The FlashAlpha Flow Signals API (GET /v1/flow/signals/{symbol}) takes the opposite stance. The score is the deterministic, weighted average of six normalised components. Every component is returned in the response under score_breakdown. The classification of every trade as a sweep or block, an opening or closing flow, a bullish or bearish bet, follows rules documented in code and reproduced in this article. This is the methodology paper.

What the Flow Signals Feed Actually Is

The flow signals endpoint takes the raw block-sized prints from the OPRA tape, groups same-side prints that arrived within 500ms of each other on the same contract into single execution intents, and produces one scored, classified FlowSignal per group. The output is the input layer for any system that needs to react to unusual activity: a trading dashboard, an alert ruleset, a backtest universe selector, or an LLM that needs structured options-flow context.

The pipeline is intentionally split across pure-static components so every step is independently testable on synthetic tapes - no clock, no HTTP, no global state outside the inputs.

Sweep Coalescing: 500ms Same-Side Same-Contract

The single most important pre-processing step is sweep coalescing. A real institutional execution often crosses multiple venues in rapid succession - one bid lifted on PHLX, another at the same instant on CBOE, a third on AMEX - because that is how exchanges route a multi-leg sweep. On the tape, that single intent looks like three prints. Without coalescing, the score-it-once-per-print approach would either double-count the intent or under-rate it.

Same-contract same-side prints whose timestamps fall within 500 milliseconds of the prior print join the current group. Any group with two or more prints is classified as a sweep; a singleton block-sized print is a block. The size used for scoring is the sum across the group; the price is the size-weighted average; the timestamp is the last print in the group.

The Six Scoring Components

Every coalesced group is scored along six axes. Each component is normalised to the unit interval [0,1] before weighting, the components are combined as a weighted average, and the result is scaled to a 0-100 integer. The breakdown is surfaced in every response so you can always answer "why is this score 78 and not 50?" without leaving the JSON.

1. Premium

The notional dollar value of the trade (price × size × 100 multiplier), log-normalised against a $10M cap.

With the default $10M cap, a $1M trade scores about 0.86, a $100K trade about 0.71, and a $10M trade saturates at 1.00. The log normalisation is deliberate: linear scaling would push every $100K-$1M print to noise and only spotlight the largest tape, whereas the log form gives realistic mid-sized prints meaningful score contribution without letting one whale dominate the rank.

2. Size vs Open Interest

The ratio of trade size to the contract's settled OI, capped at 1.0 by default.

This component is the unusual-activity classic. A trade equal to or larger than the entire settled OI is a position change of the highest possible significance for that contract and saturates the score. The default cap of 1.0 means even a trade that is 50% of settled OI scores 0.5 - a meaningful contribution but not full credit until the trade hits the OI itself.

3. Aggressor Strength

The combination of where the print landed inside the NBBO and how aggressive the side classifier called it.

A buyer who lifts the offer scores near 1.0; a buyer who pays the midpoint scores around 0.5; a buyer who somehow gets filled below the mid scores low. Symmetrically for sellers. Mid prints get a flat 0.4 because they cannot be classified as aggressive in either direction with confidence. Crossed or locked NBBOs (spread ≤ 0) get 0.5, neutral, because the spread denominator is undefined.

4. Sweep Structure

Categorical score reflecting the execution structure detected during coalescing.

Sweeps are the highest-value structure because they signal urgency: the participant was willing to walk multiple venues to get filled fast. A standalone block is meaningful but compatible with patient, single-venue execution. The "single" tier exists for completeness - the upstream ring is block-only by construction, so you rarely see it in practice.

5. Opening Bias

Whether the trade opens new positions or closes existing ones, derived from the OI simulator's signed intraday delta for the same contract.

The oi_confidence multiplier is the simulator's per-trade confidence weight, currently 0.43 (see Effective Open Interest Methodology for the calibration story). This is the most important design choice in the entire scorer.

6. Tenor

Days to expiration, normalised so short-dated trades score higher.

With the default tenor_cap_days of 45, a 0DTE print scores 1.0, a 22-DTE print scores 0.51, a 45+-DTE print scores 0. LEAPS get zero credit for tenor. The reasoning: shorter-dated flow has more time-discounted information value, and the unusual-activity use case is primarily a short-horizon signal. If you want a screener that surfaces LEAPS rolls, sort by premium and ignore the tenor component.

The Composite Score

Every component is combined into a single 0-100 integer through a weighted average, with each component's individual contribution rounded and exposed for auditability.

The default weights (tunable via the UnusualFlowWeights record, sum = 5.6) are:

The breakdown lives in the response under score_breakdown:

{
  "score": 78,
  "score_breakdown": {
    "premium":      22,
    "size_vs_oi":   10,
    "aggressor":    13,
    "sweep":        18,
    "opening_bias":  6,
    "tenor":         9
  }
}

This is the audit trail. Add the buckets and you get the score, with rounding to within ±1 from accumulating per-bucket rounds. Any score in the feed can be reconstructed from the trade + OI context using the formulas above. There are no hidden adjustments.

Intent Classification

Once the trade is scored structurally, the scorer assigns a directional intent. The rules are deliberately conservative.

Conviction Labels and the "Golden" Tag

Two human-readable summaries ride alongside the raw score: a conviction bucket and an optional "golden" tag.

The thresholds are calibrated so that, on a typical SPY session, the medium bucket and above contains the prints worth a human review and the high bucket contains the ones you would page someone for. They are absolute, not relative to today's distribution - a quiet session genuinely produces fewer high-conviction signals.

Greeks Enrichment Overlay

Once a signal is scored, the enricher joins it with the settled greek snapshot for the same contract and adds a chain-context overlay. The enrichment is deliberately scoped to fields the data can actually prove.

At the symbol level, the enricher also returns the settled-chain reference levels (call wall, put wall, max pain, gamma flip) computed once per request. Those let a consumer cross-reference whether a high-scoring signal hits a meaningful structural strike or is firing in a no-man's-land.

The Summary Endpoint: Bullish vs Bearish Premium Roll-Up

The companion GET /v1/flow/signals/{symbol}/summary endpoint runs the same pipeline and aggregates premium across the directional and open/close buckets. It is the single number you want on a dashboard.

Plus the top 10 signals (already sorted descending by score). One call gives you a watchlist-friendly direction signal and the underlying prints that produced it.

How to Use It

The endpoint is on the Alpha plan. Defaults are sensible: 240-minute window, top 50 by score, all intents, all structures. Filter parameters narrow the result without re-running the pipeline.

Code Example: Top 10 Bullish Sweeps on SPY

import requests

resp = requests.get(
    "https://lab.flashalpha.com/v1/flow/signals/SPY",
    headers={"X-Api-Key": "YOUR_KEY"},
    params={
        "windowMinutes": 240,
        "intent": "bullish",
        "structure": "sweep",
        "minScore": 70,
        "limit": 10,
    },
)
data = resp.json()

print(f"{data['count']} qualifying signals on {data['symbol']}")
print(f"Chain context: call_wall={data['chain']['call_wall']}, "
      f"put_wall={data['chain']['put_wall']}, "
      f"gamma_flip={data['chain']['gamma_flip']}")

for s in data["signals"]:
    print(
        f"  {s['ts']}  {s['expiry']} {s['strike']}{s['right']}"
        f"  size={s['size']:>5}  ${s['premium']:>10,.0f}"
        f"  score={s['score']}  ({s['conviction']})"
        f"  {','.join(s['tags'])}"
    )

Code Example: Watchlist Direction Card

import requests
from concurrent.futures import ThreadPoolExecutor

WATCHLIST = ["SPY", "QQQ", "IWM", "NVDA", "TSLA", "AAPL"]
HEADERS = {"X-Api-Key": "YOUR_KEY"}

def fetch_summary(symbol):
    r = requests.get(
        f"https://lab.flashalpha.com/v1/flow/signals/{symbol}/summary",
        headers=HEADERS,
        params={"windowMinutes": 60},
    )
    return symbol, r.json()

with ThreadPoolExecutor(max_workers=8) as pool:
    for sym, d in pool.map(fetch_summary, WATCHLIST):
        net = d["net_directional_premium"]
        direction = "BULLISH" if net > 0 else "BEARISH" if net < 0 else "NEUTRAL"
        print(
            f"{sym:6} {direction:8} "
            f"net=${net:>14,.0f}  "
            f"open=${d['opening_premium']:>12,.0f}  "
            f"close=${d['closing_premium']:>12,.0f}"
        )

Use Cases and Honest Scope

The endpoint is designed for four workflows.

What it is not designed for:

• Full tape replay. The notable ring is hard-capped at 512 prints; the endpoint is a windowed scan, not an exhaustive trade history. For full replay, use the raw /v1/flow/options/{symbol}/recent surface.
• Single-print precision intent. Intent is a heuristic from side and call/put. Multi-leg structures (verticals, butterflies, calendars) are not detected at this layer. A bear-call-spread leg that buys the lower call still reads as a bullish single leg here.
• Replacing per-strike GEX. The enrichment provides per-signal greeks, but the chain-level live GEX number lives at /v1/flow/gex, computed against effective OI. Use both: signals for intent and significance, /v1/flow/gex for chain-level dealer exposure.

Why the Score Breakdown Matters

Every unusual-activity vendor in the market publishes a score. Almost none of them tell you what is inside it. The buyer is forced to trust the number, the implicit weighting, and the (undisclosed) calibration choices the vendor made years ago and may or may not have revisited.

The score is the product. The methodology is the warranty.

Limitations and Calibration Notes

Three honest limitations of the current scorer:

Side classification is upstream

The Buy/Sell/Mid label comes from the ingest service's quote-rule classifier (the same Lee-Ready style logic used by the OI simulator). Rapid quote updates around news prints can flip individual classifications. The aggregator effect is monitored in the residual reconciliation pipeline for the OI simulator (see the methodology paper); the same classifier feeds the aggressor strength and the intent classifier here. If you need per-print classification certainty, treat the score as one input among several rather than a standalone signal.

Multi-leg structures are not detected

The pipeline groups same-side same-contract prints into sweeps but does not infer that a simultaneous buy-call-A and sell-call-B is a vertical spread. Each leg is scored independently and labelled with its own (possibly opposite) intent. A higher-level structure detector is a candidate for a future revision but is not in scope today.

The default weights are calibrated, not derived

The 1.0 / 1.0 / 0.8 / 1.0 / 1.2 / 0.6 weighting was set by eye after looking at a representative range of SPY, NVDA, and TSLA sessions. There is no claim that these weights are statistically optimal; they are documented defaults that you can override per-request via the UnusualFlowWeights record at the service layer. If you have a backtest that prefers a different weighting, the API is open to a future ?weights= parameter - we have not built it yet because no customer has asked for it. The audit trail in score_breakdown exists partly so customers can build their own re-weighting on top of our normalised components.

How It Fits Into the Wider Flow Stack

Flow signals are one of three independent flow surfaces on the same API key:

The three surfaces share the same OI simulator state and the same settled greek snapshot, so the numbers across them reconcile. The composite use case is: scan the signals feed for high-conviction intent, cross-check the chain context against /v1/flow/gex, and drop into raw trades for any signal that needs deeper inspection.

Frequently Asked Questions

Related Reading

• Effective Open Interest Methodology - the 0.43 confidence weight calibration that the opening-bias component inherits
• Live GEX vs Settled GEX - the simulation-aware exposure stack that backs the chain context in every signal
• Live Dealer Flow Monitor - the companion chain-level flow surface (levels, pin risk, dealer-risk shift)
• Flow vs Exposure: Which GEX API to Use - how the flow surface and the settled exposure surface coexist
• Options Flow API: Recent Trades, Blocks, Leaderboard - the raw trade surface beneath the signals feed
• Dealer Positioning: A Quantitative Approach - how flow signals fit the broader dealer-positioning model
• Call Walls, Put Walls, and the Gamma Flip - the structural levels surfaced as chain context on every signal