Options Flow API: Recent Trades, Block Detection and Buyer/Seller Leaderboards

If you are searching for an unusual options activity API, an options block trade endpoint, an options sweep or large-trade feed, an options order flow API, or a buyer vs seller flow API, this is the reference. The new FlashAlpha Raw Flow Data endpoints return recent option trades by underlying, trade-flow totals, large block prints, minute buckets, a cumulative net-flow series, an outlier feed ranked by net notional, and a buyer/seller leaderboard - all as camelCase pass-through JSON, on the Alpha plan. The stock-trade equivalents are parallel endpoints with analogous (not identical) shapes - stock trades drop the option-only contract fields.

Read this first. These endpoints are a trade-flow proxy derived from the FlashAlpha ingest service. They are not exchange-audited consolidated tape, and the buyer/seller side is an inference, not an official designation. Field names are camelCase pass-through and may evolve. Every JSON sample below is an illustrative shape with placeholder numbers - not live market data and not a contractual schema. Use the feed for relative signal (where is size hitting, who is net buying), not for tick-accurate accounting.

The Recent / Blocks / Outliers / Leaderboard / Cumulative Mental Model

The flow API is one dataset viewed five ways. Pick the view that matches the question you are asking:

The single-symbol views (recent, summary, blocks, history, cumulative) take a {symbol} path segment. The cross-market views (leaderboard, outliers) scan the universe and return ranked symbols. The Raw Flow Data endpoints covered in this guide (recent, summary, blocks, history, cumulative, leaderboard, outliers) require the Alpha plan. The Flow Analytics components (/v1/flow/levels, /pin-risk, /summary, /gex, /dex, /dealer-risk) are Growth+ and are covered in a separate guide - see Live Dealer Flow Monitor API: Intraday GEX and Pin Risk and Flow vs Exposure Endpoints: Which GEX API to Use. The raw camelCase tape endpoints in this article do not accept an ?expiry query parameter; an expiry filter is a Flow Analytics (snake_case) feature only. Each raw endpoint takes its own query params instead - limit, minSize, minutes, n, windowMinutes, or minTrades as documented per endpoint below.

The stock-trade equivalents are parallel endpoints with analogous (not identical) shapes: GET /v1/flow/stocks/{symbol}/recent, /summary, /blocks, /history, /cumulative, plus GET /v1/flow/stocks/leaderboard and GET /v1/flow/stocks/outliers. The envelopes match, but stock recent trades omit the option-only instrumentId, expiry, strike, and right fields, stock summary omits contractsWithTrades, and the stock leaderboard rows use vwap instead of avgPremium. Same caveats throughout.

Quick Start: Pull Recent Option Trades

import requests

BASE = "https://lab.flashalpha.com"
HEADERS = {"X-Api-Key": "YOUR_KEY"}

# Recent option trades on the underlying
r = requests.get(f"{BASE}/v1/flow/options/NVDA/recent", headers=HEADERS)
r.raise_for_status()
trades = r.json()

# Fields are camelCase pass-through from the ingest service.
# Treat as a trade-flow proxy, not exchange-audited tape.
for t in trades.get("trades", [])[:5]:
    print(t)

const BASE = 'https://lab.flashalpha.com';
const headers = { 'X-Api-Key': 'YOUR_KEY' };

const res = await fetch(`${BASE}/v1/flow/options/NVDA/recent`, { headers });
if (!res.ok) throw new Error(`HTTP ${res.status}`);
const data = await res.json();

// camelCase pass-through fields - a trade-flow proxy, not audited tape
for (const t of (data.trades || []).slice(0, 5)) {
    console.log(t);
}

using System.Net.Http;
using System.Net.Http.Headers;

var http = new HttpClient { BaseAddress = new Uri("https://lab.flashalpha.com") };
http.DefaultRequestHeaders.Add("X-Api-Key", "YOUR_KEY");

// JSON is camelCase pass-through - deserialize loosely, treat as a flow proxy
var json = await http.GetStringAsync("/v1/flow/options/NVDA/recent");
Console.WriteLine(json);

package main

import (
    "fmt"
    "io"
    "net/http"
)

func main() {
    req, _ := http.NewRequest("GET",
        "https://lab.flashalpha.com/v1/flow/options/NVDA/recent", nil)
    req.Header.Set("X-Api-Key", "YOUR_KEY")

    resp, _ := http.DefaultClient.Do(req)
    defer resp.Body.Close()

    // camelCase pass-through JSON - a trade-flow proxy
    body, _ := io.ReadAll(resp.Body)
    fmt.Println(string(body))
}

curl -H "X-Api-Key: YOUR_KEY" \
  "https://lab.flashalpha.com/v1/flow/options/NVDA/recent"

# Optional limit param (clamped 1..500, default 50)
curl -H "X-Api-Key: YOUR_KEY" \
  "https://lab.flashalpha.com/v1/flow/options/NVDA/recent?limit=200"

Illustrative Response Shapes

The following JSON is an illustrative shape only. Field names are camelCase pass-through from the ingest service and may change; the numbers are placeholders, not live market data; the data is a trade-flow proxy, not exchange-audited tape. Do not hard-code against an exact schema - read fields defensively and treat the side classification as an inference.

GET /v1/flow/options/NVDA/recent - recent option trades by underlying:

{
  "symbol": "NVDA",
  "count": 50,
  "totalAvailable": 21840,
  "trades": [
    {
      "ts": "2026-05-15T15:42:09Z",
      "instrumentId": "NVDA260619C00130000",
      "expiry": "2026-06-19",
      "strike": 130.0,
      "right": "C",
      "price": 4.15,
      "size": 850,
      "side": "buy",
      "isBlock": true,
      "bid": 4.10,
      "ask": 4.20
    }
  ]
}

GET /v1/flow/options/NVDA/summary - buy/sell/mid/net contract volume totals by underlying (note the buy/sell split is an inference):

{
  "symbol": "NVDA",
  "contractsWithTrades": 412,
  "totalTrades": 21840,
  "buyVolume": 184000,
  "sellVolume": 121000,
  "midVolume": 38000,
  "netVolume": 63000,
  "biggestSingleTrade": 5000,
  "lastTradeUtc": "2026-05-15T15:42:09Z"
}

GET /v1/flow/options/NVDA/blocks - large option trades by underlying:

{
  "symbol": "NVDA",
  "minSize": 100,
  "count": 1,
  "blocks": [
    {
      "ts": "2026-05-15T14:58:02Z",
      "expiry": "2026-09-18",
      "strike": 150.0,
      "right": "C",
      "price": 6.40,
      "size": 5000,
      "side": "buy"
    }
  ]
}

GET /v1/flow/options/NVDA/cumulative - cumulative net-flow points, ideal for an intraday line:

{
  "symbol": "NVDA",
  "minutes": 240,
  "count": 4,
  "points": [
    {"ts": "2026-05-15T13:30:00Z", "netVolume": 0, "cumulative": 0, "vwap": 4.05, "tradeCount": 0},
    {"ts": "2026-05-15T14:00:00Z", "netVolume": 1850, "cumulative": 1850, "vwap": 4.08, "tradeCount": 320},
    {"ts": "2026-05-15T14:30:00Z", "netVolume": 1270, "cumulative": 3120, "vwap": 4.11, "tradeCount": 540},
    {"ts": "2026-05-15T15:00:00Z", "netVolume": -380, "cumulative": 2740, "vwap": 4.10, "tradeCount": 610}
  ]
}

GET /v1/flow/options/leaderboard - buyer/seller leaderboard across the universe:

{
  "generatedUtc": "2026-05-15T15:42:11Z",
  "n": 10,
  "windowMinutes": 60,
  "buyers": [
    {"symbol": "NVDA", "netVolume": 63000, "netNotional": 44000000, "buyVolume": 184000, "sellVolume": 121000, "avgPremium": 4.12, "tradeCount": 21840, "lastTradeUtc": "2026-05-15T15:42:09Z"}
  ],
  "sellers": [
    {"symbol": "AAPL", "netVolume": -41000, "netNotional": -19200000, "buyVolume": 88000, "sellVolume": 129000, "avgPremium": 2.80, "tradeCount": 14200, "lastTradeUtc": "2026-05-15T15:42:05Z"}
  ]
}

GET /v1/flow/options/outliers - the unusual-activity feed ranked by absolute net notional:

{
  "generatedUtc": "2026-05-15T15:42:11Z",
  "windowMinutes": 60,
  "tracked": 4200,
  "qualified": 38,
  "limit": 25,
  "outliers": [
    {
      "symbol": "SMCI",
      "tradeCount": 980,
      "buyVolume": 42000,
      "sellVolume": 18000,
      "midVolume": 6000,
      "netVolume": 24000,
      "imbalancePct": 57.1,
      "skew": 0.42,
      "notional": 26800000,
      "netNotional": 12400000,
      "biggestTrade": 4000,
      "biggestTradeUtc": "2026-05-15T15:10:02Z",
      "biggestAgeSec": 1929,
      "lastVwap": 5.18,
      "lastTradeUtc": "2026-05-15T15:42:11Z",
      "lastTradeAgeSec": 0
    }
  ]
}

The outlier feed ranks symbols by absolute netNotional and exposes imbalancePct and skew so you can see how lopsided current flow is for that symbol. Use these to rank and triage, not as absolutes. Treat side and the buy/sell volume splits everywhere as inferences from the proxy, not as exchange-tagged facts.

How To: Build an Unusual Options Activity Scanner

The highest-value thing you can build on this API is a scanner that combines the /outliers feed with per-symbol /blocks confirmation across a watchlist. The mental model: outliers tells you which symbols look unusual; blocks tells you whether there is real size behind it. Cross the two and you have a triage list.

import requests

BASE = "https://lab.flashalpha.com"
HEADERS = {"X-Api-Key": "YOUR_KEY"}
WATCHLIST = {"NVDA", "TSLA", "AAPL", "SMCI", "AMD", "META"}
NET_NOTIONAL_MIN = 5_000_000
BLOCK_MIN_SIZE = 1000

def get(path, **params):
    r = requests.get(f"{BASE}{path}", headers=HEADERS, params=params)
    r.raise_for_status()
    return r.json()

# 1. Outlier feed tells us WHICH symbols look unusual
outliers = get("/v1/flow/options/outliers").get("outliers", [])

flagged = [
    o for o in outliers
    if o.get("symbol") in WATCHLIST
    and abs(o.get("netNotional", 0)) >= NET_NOTIONAL_MIN
]

# 2. For each flagged symbol, confirm with real block size
for o in sorted(flagged, key=lambda x: abs(x.get("netNotional", 0)), reverse=True):
    sym = o["symbol"]
    blocks = get(f"/v1/flow/options/{sym}/blocks", minSize=BLOCK_MIN_SIZE).get("blocks", [])
    if not blocks:
        continue  # flagged unusual but no large prints behind it - skip

    top = max(blocks, key=lambda b: b.get("size", 0))
    print(f"{sym}  netNotional=${o.get('netNotional'):,}  "
          f"skew={o.get('skew')}  imbalancePct={o.get('imbalancePct')}  "
          f"biggest block {top.get('size')} @ {top.get('price')} ({top.get('side')})")
    # send_alert(sym, o, top)  # wire to Slack / Discord / email

const BASE = 'https://lab.flashalpha.com';
const headers = { 'X-Api-Key': 'YOUR_KEY' };
const WATCHLIST = new Set(['NVDA', 'TSLA', 'AAPL', 'SMCI', 'AMD', 'META']);
const NET_NOTIONAL_MIN = 5_000_000;
const BLOCK_MIN_SIZE = 1000;

async function get(path) {
    const res = await fetch(`${BASE}${path}`, { headers });
    if (!res.ok) throw new Error(`HTTP ${res.status}`);
    return res.json();
}

// 1. Which symbols look unusual?
const { outliers = [] } = await get('/v1/flow/options/outliers');
const flagged = outliers
    .filter(o => WATCHLIST.has(o.symbol) && Math.abs(o.netNotional ?? 0) >= NET_NOTIONAL_MIN)
    .sort((a, b) => Math.abs(b.netNotional ?? 0) - Math.abs(a.netNotional ?? 0));

// 2. Confirm with block size
for (const o of flagged) {
    const { blocks = [] } = await get(`/v1/flow/options/${o.symbol}/blocks?minSize=${BLOCK_MIN_SIZE}`);
    if (blocks.length === 0) continue;

    const top = blocks.reduce((m, b) => (b.size > m.size ? b : m));
    console.log(`${o.symbol} netNotional=$${(o.netNotional ?? 0).toLocaleString()} skew=${o.skew} `
        + `biggest ${top.size} @ ${top.price} (${top.side})`);
}

using System.Net.Http;
using System.Text.Json;

var http = new HttpClient { BaseAddress = new Uri("https://lab.flashalpha.com") };
http.DefaultRequestHeaders.Add("X-Api-Key", "YOUR_KEY");

var watchlist = new HashSet<string> { "NVDA", "TSLA", "AAPL", "SMCI", "AMD", "META" };
const long netNotionalMin = 5_000_000;
const long blockMinSize = 1000;

async Task<JsonElement> Get(string path)
{
    var json = await http.GetStringAsync(path);
    return JsonDocument.Parse(json).RootElement;
}

// 1. Outlier feed
var outliers = await Get("/v1/flow/options/outliers");
foreach (var o in outliers.GetProperty("outliers").EnumerateArray())
{
    var sym = o.GetProperty("symbol").GetString();
    var netNotional = o.GetProperty("netNotional").GetInt64();
    if (sym is null || !watchlist.Contains(sym) || Math.Abs(netNotional) < netNotionalMin) continue;

    // 2. Confirm with block size
    var blocks = await Get($"/v1/flow/options/{sym}/blocks?minSize={blockMinSize}");
    foreach (var b in blocks.GetProperty("blocks").EnumerateArray())
    {
        if (b.GetProperty("size").GetInt64() >= blockMinSize)
        {
            Console.WriteLine($"{sym} netNotional={netNotional} confirmed by block size");
            break;
        }
    }
}

package main

import (
    "encoding/json"
    "fmt"
    "math"
    "net/http"
)

const base = "https://lab.flashalpha.com"

func get(path string, out interface{}) error {
    req, _ := http.NewRequest("GET", base+path, nil)
    req.Header.Set("X-Api-Key", "YOUR_KEY")
    resp, err := http.DefaultClient.Do(req)
    if err != nil {
        return err
    }
    defer resp.Body.Close()
    return json.NewDecoder(resp.Body).Decode(out)
}

func main() {
    watch := map[string]bool{"NVDA": true, "TSLA": true, "SMCI": true}

    var feed struct {
        Outliers []struct {
            Symbol      string  `json:"symbol"`
            NetNotional float64 `json:"netNotional"`
            Skew        float64 `json:"skew"`
        } `json:"outliers"`
    }
    get("/v1/flow/options/outliers", &feed)

    for _, o := range feed.Outliers {
        if !watch[o.Symbol] || math.Abs(o.NetNotional) < 5_000_000 {
            continue
        }
        // confirm with /v1/flow/options/{sym}/blocks?minSize=1000 ...
        fmt.Printf("%s flagged netNotional=%.0f skew=%.2f\n", o.Symbol, o.NetNotional, o.Skew)
    }
}

# 1. Outlier feed - which symbols look unusual by net notional
curl -H "X-Api-Key: YOUR_KEY" \
  "https://lab.flashalpha.com/v1/flow/options/outliers"

# 2. Confirm a flagged symbol with its large prints
curl -H "X-Api-Key: YOUR_KEY" \
  "https://lab.flashalpha.com/v1/flow/options/SMCI/blocks"

This two-stage pattern - rank with /outliers, confirm with /blocks - filters out symbols that look unusual on thin, scattered prints. Add a third stage with /summary if you want to require a directional buy-versus-sell imbalance before alerting. Because the side is an inference, treat a "net buyer" flag as a hypothesis to investigate, not a confirmed institutional position.

How To: Chart Cumulative Net Flow

The /cumulative endpoint is purpose-built for one visualization: the intraday running net-flow line. Each point carries a timestamp and a cumulative running net-volume value (plus per-bucket netVolume, vwap, and tradeCount), so you plot it directly with no client-side aggregation. A rising line means net buying is accumulating; a falling line means net selling. This is the cleanest single chart for "is flow building one direction today?"

import requests
import matplotlib.pyplot as plt

BASE = "https://lab.flashalpha.com"
HEADERS = {"X-Api-Key": "YOUR_KEY"}

r = requests.get(f"{BASE}/v1/flow/options/NVDA/cumulative", headers=HEADERS)
r.raise_for_status()
points = r.json().get("points", [])

# camelCase pass-through fields - read defensively
xs = [p["ts"] for p in points]
ys = [p.get("cumulative", 0) for p in points]

plt.plot(xs, ys)
plt.axhline(0, color="#999", linewidth=0.8)
plt.title("NVDA cumulative options net flow (proxy)")
plt.ylabel("Cumulative net volume (contracts)")
plt.xticks(rotation=45)
plt.tight_layout()
plt.savefig("nvda_cumflow.png")

const BASE = 'https://lab.flashalpha.com';
const headers = { 'X-Api-Key': 'YOUR_KEY' };

const res = await fetch(`${BASE}/v1/flow/options/NVDA/cumulative`, { headers });
const { points = [] } = await res.json();

// Feed straight into Chart.js / ECharts / lightweight-charts
const series = points.map(p => ({
    x: p.ts,
    y: p.cumulative ?? 0,
}));

// new Chart(ctx, { type: 'line', data: { datasets: [{ data: series }] } });
console.log(series);

using System.Net.Http;
using System.Text.Json;

var http = new HttpClient { BaseAddress = new Uri("https://lab.flashalpha.com") };
http.DefaultRequestHeaders.Add("X-Api-Key", "YOUR_KEY");

var json = await http.GetStringAsync("/v1/flow/options/NVDA/cumulative");
var root = JsonDocument.Parse(json).RootElement;

foreach (var p in root.GetProperty("points").EnumerateArray())
{
    var ts = p.GetProperty("ts").GetString();
    var cum = p.GetProperty("cumulative").GetInt64();
    Console.WriteLine($"{ts}  {cum:N0}");
}

package main

import (
    "encoding/json"
    "fmt"
    "net/http"
)

func main() {
    req, _ := http.NewRequest("GET",
        "https://lab.flashalpha.com/v1/flow/options/NVDA/cumulative", nil)
    req.Header.Set("X-Api-Key", "YOUR_KEY")
    resp, _ := http.DefaultClient.Do(req)
    defer resp.Body.Close()

    var out struct {
        Points []struct {
            Ts         string `json:"ts"`
            Cumulative int64  `json:"cumulative"`
        } `json:"points"`
    }
    json.NewDecoder(resp.Body).Decode(&out)

    for _, p := range out.Points {
        fmt.Printf("%s  %d\n", p.Ts, p.Cumulative)
    }
}

curl -H "X-Api-Key: YOUR_KEY" \
  "https://lab.flashalpha.com/v1/flow/options/NVDA/cumulative"

# Adjust the lookback window (minutes, default 240)
curl -H "X-Api-Key: YOUR_KEY" \
  "https://lab.flashalpha.com/v1/flow/options/NVDA/cumulative?minutes=390"

If you want minute-resolution bars instead of a running line, use /history for the per-minute buckets and aggregate or stack them yourself. The /cumulative series is the running sum of that same flow, pre-computed for charting. Both take a minutes query param (clamped 1..10080; /history defaults to 60, /cumulative to 240) to set the lookback window - these raw endpoints do not accept an expiry filter.

What This Data Is (and Is Not)

Being precise here protects you from building on a wrong assumption:

• It is a trade-flow proxy. The feed is derived from the FlashAlpha ingest service. It is not the official consolidated options tape and it is not exchange-audited. Use it for relative signal, not for reconciliation or compliance.
• Side is inferred. The side / aggressor / buy-versus-sell notional split is a classification, not an exchange-tagged buyer or seller designation. Treat "net buyer" as a hypothesis.
• Fields are camelCase pass-through. The endpoints pass JSON through from ingest. Field names are camelCase and may evolve. Read defensively, default missing fields, do not pin a strict schema.
• Numbers in this article are illustrative. Every JSON sample uses placeholder values to show shape only. Nothing here is live market data.
• Alpha tier, unlimited rate. The Raw Flow Data endpoints covered in this guide (recent, summary, blocks, history, cumulative, leaderboard, outliers) require the Alpha plan. The Flow Analytics components (/v1/flow/levels, /pin-risk, /summary, /gex, /dex, /dealer-risk) are Growth+, not Alpha-only, and are covered in Live Dealer Flow Monitor API: Intraday GEX and Pin Risk and Flow vs Exposure Endpoints: Which GEX API to Use.

The honest framing is the feature: a fast, well-shaped proxy that surfaces where size is hitting and who is leaning which way, without pretending to be the audited tape.

Why Not Build It Yourself?

You can. Here is what an in-house unusual options activity pipeline requires:

1. A raw option trade feed - tick-level prints across every contract and expiration for the universe. This is a real recurring data cost and a real ingestion problem.
2. Side classification - deciding whether each print is buyer or seller initiated. Quote context, the bid/ask at print time, and tie-break rules. This is the hard part and it is always an inference.
3. Notional and block sizing - normalizing size times price times multiplier, then defining what counts as a "block" per symbol given its typical liquidity.
4. Outlier ranking - net-notional, imbalance, and skew measures per symbol so you can say "this is unusual" with comparable numbers, not just a raw count.
5. Cross-market ranking - rolling the per-symbol aggregates into a leaderboard and an outlier scan that stays consistent across thousands of names.
6. Intraday state and infrastructure - cumulative running sums, minute buckets, windowed lookbacks, and uptime through the full session at low latency.

That is months of work and an ongoing data bill before you render a single row. The FlashAlpha Raw Flow Data endpoints exist so you can skip the ingestion and classification layer and start at the signal.

API Access and Pricing

The Raw Flow Data endpoints covered in this guide (recent, summary, blocks, history, cumulative, leaderboard, outliers) - options and stocks, single-symbol and cross-market - are Alpha plan only. The separate Flow Analytics components (/v1/flow/levels, /pin-risk, /summary, /gex, /dex, /dealer-risk) are Growth+, not Alpha-only - see Live Dealer Flow Monitor API: Intraday GEX and Pin Risk and Flow vs Exposure Endpoints: Which GEX API to Use.

To explore the shapes before wiring code, the interactive API playground lets you test flow calls in the browser with an Alpha key. SDKs are available in Python, JavaScript, C#, Go, and Java, though the flow endpoints are simple enough to call with a plain HTTP client as shown above.

Frequently Asked Questions

Related Reading

• Build a Dealer Positioning Tracker with an API
• Live Dealer Flow Monitor API: Intraday GEX and Pin Risk
• Live GEX vs Settled GEX: Intraday Options Flow Explained
• SpotGamma vs Unusual Whales: A Comparison
• Interactive API Playground