Flow Signals API - Unusual Options Flow Feed | FlashAlpha
  1. Flow Signals

Flow Signals API

Scored, classified unusual-flow feed for one underlying. Sweep vs block, NBBO aggressor, opening/closing bias, directional intent, and a transparent 0-100 score with component breakdown and chain enrichment.

Endpoint

GET /v1/flow/signals/{symbol}
Auth required (X-Api-Key) Rate Limited: Yes Plan: Alpha+

Parameters

Name In Type Required Default Description
symbol path string required - Underlying symbol
minScore query number 0 Drop signals below this score (0-100). Non-numeric values return a 400 problem-details body. Out-of-range values are clamped to the supported range.
intent query enum all Filter by bullish / bearish / neutral. Unrecognized values are ignored.
structure query enum all Filter by block / sweep. A lone block-sized print is a block; sweep = ≥2 same-side prints on one contract within ~500ms. Unrecognized values are ignored.
windowMinutes query integer 240 Look-back window in minutes (1-10080). Non-numeric values return a 400 problem-details body. Out-of-range values are clamped to the supported range.
limit query integer 50 Max signals returned (1-500). Non-numeric values return a 400 problem-details body. Out-of-range values are clamped to the supported range.
expiry query date all expiries Filter the chain to a single expiry (yyyy-MM-dd). Invalid values return 400 invalid_expiry. An expiry with no data returns an empty result, not an error.

Request

curl -H "X-Api-Key: YOUR_API_KEY" \
  "https://lab.flashalpha.com/v1/flow/signals/NVDA?minScore=70&structure=sweep&windowMinutes=240"
import requests

resp = requests.get(
    "https://lab.flashalpha.com/v1/flow/signals/NVDA",
    params={"minScore": 70, "structure": "sweep", "windowMinutes": 240},
    headers={"X-Api-Key": "YOUR_API_KEY"}
)
resp.raise_for_status()
data = resp.json()
for sig in data["signals"]:
    print(f"{sig['ts']} {sig['structure']:>5} {sig['right']} {sig['strike']} "
          f"score={sig['score']} intent={sig['intent']} premium=${sig['premium']:,.0f}")
const params = new URLSearchParams({
  minScore: 70, structure: "sweep", windowMinutes: 240
});
const resp = await fetch(
  `https://lab.flashalpha.com/v1/flow/signals/NVDA?${params}`,
  { headers: { "X-Api-Key": "YOUR_API_KEY" } }
);
if (!resp.ok) throw new Error(`HTTP ${resp.status}`);
const data = await resp.json();
data.signals.forEach(s =>
  console.log(`${s.ts} ${s.structure} ${s.right}${s.strike} score=${s.score} ${s.intent}`)
);

Try it live

Runs on live market data and uses 1 request from your daily quota.

GET

Response

{
  "symbol": "NVDA",
  "as_of": "2026-10-30T13:46:02.5129214Z",
  "window_minutes": 240,
  "expiry": null,
  "underlying_price": 206.435,
  "chain": {
    "call_wall": 220,
    "put_wall": 200,
    "max_pain": 200,
    "gamma_flip": 208.1809,
    "gamma_flip_status": "available"
  },
  "count": 1,
  "signals": [
    {
      "ts": "2026-10-30T13:38:49.745Z",
      "expiry": "2026-10-30",
      "strike": 210,
      "right": "C",
      "side": "buy",
      "price": 0.32,
      "size": 1411,
      "premium": 45152,
      "dte": 0,
      "structure": "sweep",
      "aggressor": "at_ask",
      "open_close_bias": "opening_bias",
      "open_close_confidence": 0.43,
      "contract_net_oi_delta": 375,
      "intent": "bullish",
      "score": 70,
      "conviction": "medium",
      "tags": [
        "sweep",
        "opening",
        "0dte"
      ],
      "score_breakdown": {
        "premium": 12,
        "size_vs_oi": 6,
        "aggressor": 14,
        "sweep": 18,
        "opening_bias": 9,
        "tenor": 11
      },
      "enrichment": {
        "iv": 0.55077,
        "delta": 0.123889,
        "gamma": 0.067453,
        "iv_vs_atm": -0.00157,
        "moneyness": "OTM",
        "estimated_delta_notional": 3608629,
        "hypothetical_gex_impact_if_opening": 4055957
      }
    }
  ],
  "endpoint_version": "2026.09.30",
  "data_as_of": {
    "node": "fa5",
    "equity_feed": "2026-10-30T13:46:02.141Z",
    "equity_options_feed": "2026-10-30T13:46:01Z",
    "index_feed": "2026-10-30T13:46:02.132Z",
    "index_options_feed": "2026-10-30T13:45:59Z",
    "futures_feed": "2026-10-30T13:45:51.589Z",
    "futures_options_feed": "2026-10-30T13:45:51.596Z",
    "flow_feed": "2026-10-30T13:45:00Z",
    "oi_feed": "2026-10-29T20:00:00Z",
    "macro_feed": "2026-10-29T21:00:20Z"
  }
}

Sending request…

See this endpoint on live data

Send this exact request and the real response shows up here, right next to the example.

Per-signal fields

Field Type Description
tsstringISO 8601 timestamp of the print (or last leg of a sweep)
expiry / strike / rightstring / number / stringContract key (right is C or P)
sidestringUpstream aggressor classification: buy, sell, or mid
price / size / premiumnumberpremium = price × size × 100
dtenumberDays to expiry
structurestringblock (lone block-sized print) or sweep (≥2 same-side prints on one contract within ~500ms)
aggressorstringNBBO aggressor strength at trade: above_ask / at_ask / mid / at_bid / below_bid
open_close_biasstringContract-level OI-simulator bias: opening_bias, closing_bias, or unknown
open_close_confidencenumberOI simulator's confidence weight
contract_net_oi_deltanumberSimulator's signed net intraday OI delta for the contract
intentstringDirectional intent: bullish, bearish, or neutral
scorenumberComposite score 0-100, ordered highest first
convictionstringScore bucket label (e.g. high)
tagsarray of stringAny of sweep, block, opening, closing, 0dte, whale (premium ≥ $1M), golden (top decile in response and score ≥ 70)
score_breakdownobjectSub-components that sum to score: premium, size_vs_oi, aggressor, sweep, opening_bias, tenor
score_breakdown.premiumnumberscore component: premium
score_breakdown.size_vs_oinumberscore component: size vs open interest
score_breakdown.aggressornumberscore component: aggressor strength
score_breakdown.sweepnumberscore component: sweep structure
score_breakdown.opening_biasnumberscore component: opening bias
score_breakdown.tenornumberscore component: tenor
enrichmentobjectContext from the settled chain snapshot at the signal's strike
enrichment.iv / delta / gammanumber, nullableGreeks from the settled chain snapshot at the signal's strike
enrichment.iv_vs_atmnumber, nullableSignal IV minus ATM IV for the expiry
enrichment.moneynessstringITM / ATM / OTM / unknown
enrichment.estimated_delta_notionalnumber, nullableDelta-weighted dollar notional for the print (delta-equivalent shares × spot)
enrichment.hypothetical_gex_impact_if_openingnumber, nullableStandalone gamma-$ this print would add if opening and fully dealer-absorbed. Not applied to the live chain

Top-level fields

FieldTypeDescription
symbolstringUnderlying symbol
as_ofstringTimestamp of the data (ISO 8601, UTC)
window_minutesnumberEcho of the requested look-back window
expirystringEcho of the requested expiry filter (or null if all expiries)
underlying_pricenumberSpot at request time (0 when the settled chain snapshot is unavailable)
chainobjectSettled-chain reference levels
chain.call_wall / put_wall / max_pain / gamma_flipnumberSettled-chain reference levels, computed once per request
chain.gamma_flip_statusstringavailable when gamma_flip is a certified level; any other value means the level is unverified or missing. See GEX.
countnumberNumber of signals returned (after filters and limit)
signalsarrayArray of signals, highest score first
endpoint_version, data_as_ofstring, objectResponse envelope, see Response envelope.

Errors

Status Error When
400invalid_expiryexpiry is not a valid yyyy-MM-dd date.
400-A query value has the wrong type, or a required value is missing. The body is an RFC 7807 problem-details object with errors.<param>.
401-Missing or invalid X-Api-Key. The body is empty; check the status code before parsing JSON.
403tier_restrictedYour plan is below Alpha. The body includes current_plan and required_plan.
429Quota exceededDaily quota used up. Retry-After gives the seconds until the reset at 00:00 UTC. Rejected requests (including 403) count toward the quota.

How Scoring Works

Every block-sized print in the window is coalesced into a signal, classified, and scored on a 0-100 scale. score_breakdown returns the component contributions that sum to score. The components map to the trade characteristics they're named after:

  • premium - contribution from the print's dollar premium
  • size_vs_oi - contribution from print size relative to the contract's existing open interest
  • aggressor - contribution from NBBO aggressor strength; the score weights conviction in the trade's own direction
  • sweep - contribution when the print is part of a same-side sweep across ≥2 quotes within ~500ms
  • opening_bias - contribution when the OI simulator's contract-level bias says the position is being opened rather than unwound
  • tenor - contribution from the contract's DTE

Weights are server-tunable, so absolute component contributions may shift over time, but the components keep summing to score and overall signal ordering stays stable across tuning changes. The golden tag fires only when the score is in the response's top decile and at least 70 absolute, so a weak window may yield none at all.

Notes & Caveats

  • open_close_bias is a contract-level signal from the OI simulator's net intraday delta. It is not a per-print opening/closing label - individual trades inside the same contract carry the same bias.
  • intent collapses to neutral whenever open_close_bias is closing_bias (direction can't be attributed on unwinds) or when the trade side is mid. The side field (buy/sell/mid) is distinct from the NBBO aggressor label.
  • structure is always block or sweep. single is reserved and not currently emitted, so filtering structure=single returns nothing.
  • enrichment.* fields are null and moneyness is "unknown" when the signal's contract isn't in the settled chain snapshot (illiquid / just-listed).
  • hypothetical_gex_impact_if_opening is explicitly conditional - the standalone gamma-$ this single print would add if opening and fully dealer-absorbed. It is not applied to the live chain (which already folds in intraday OI), so don't sum it against /v1/flow/gex.
  • If the settled chain snapshot is unavailable for the symbol, the feed degrades rather than 404s: scoring still runs on trade + OI-simulator context, but underlying_price is 0, all chain levels are null, and every enrichment block is null/"unknown".

Common Use Cases

  • Run an unusual-activity feed - filter by minScore and structure=sweep to drop a "smart-money tape" into a watchlist and surface only high-conviction prints
  • Alert on directional intent - fire when intent=bullish or intent=bearish arrives with conviction=high and the opening tag, so you act only on fresh positioning
  • Separate sweeps from blocks - branch on structure (sweep vs block) to treat aggressive cross-venue sweeps and negotiated blocks as different signals
  • Trigger flow-confirmed entries - require a same-side high-score sweep before sizing into a directional trade so flow agrees with your thesis
  • Hunt catalysts - scan for the whale tag (≥$1M premium) to catch name-specific positioning ahead of the move
  • Research the score - use score_breakdown to back-test which components drove the best forward returns across your universe and tune your filters

Related reading

Complementary endpoints

  • Flow Summary - the dealer-positioning headline to pair with individual signals
  • Flow Signals Summary - aggregated counts and net intent across the signal feed
  • Flow Live - full live bundle for the levels and GEX context behind a signal

Ready to build with FlashAlpha?

Get your free API key and start pulling live options data in 60 seconds.

No credit card required Setup in 60 seconds Secure & reliable