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 Raw Flow Data endpoints return, as camelCase pass-through JSON on the Alpha plan:

• Recent option trades by underlying, each print side-tagged with bid and ask at the time.
• Summary totals: buy, sell, mid and net contract volume, calls vs puts.
• Blocks: the large prints, with strike, expiry and notional.
• History: minute buckets, and Cumulative: the running intraday net-flow line.
• Leaderboard of net buyers and net sellers across the universe.
• Outliers: the unusual-activity feed ranked by absolute net notional.

The buy/sell side on each print is classified from where it traded relative to the quote rather than exchange-tagged, so read net-buyer and net-seller figures as a relative signal (where size is hitting, who is leaning which way). Every JSON sample below is an illustrative shape with placeholder numbers, not live market data.

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:

• Single-symbol views (recent, summary, blocks, history, cumulative) take a {symbol} path segment.
• Cross-market views (leaderboard, outliers) scan the universe and return ranked symbols.
• Plan: all seven Raw Flow Data endpoints require Alpha.

Not covered here: the Flow Analytics family (/v1/flow/levels, /pin-risk, /summary, /gex, /dex, /dealer-risk) is Growth+ and has its own guides: Live Dealer Flow Monitor API and Flow vs Exposure Endpoints.

Query parameters: the raw camelCase tape endpoints do not accept ?expiry; an expiry filter is a Flow Analytics (snake_case) feature only. Each raw endpoint takes its own 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.

Coverage, Polling Cadence and Cost

The raw tape endpoints require Alpha; Growth's flow analytics is a different endpoint family. Check pricing and the recent-trades reference before sizing a job.

Worked polling budget for a five-symbol monitor, refreshed once a minute over the 390-minute session:

Alpha has no daily cap, so this is a client schedule, not a feed-latency promise. Polling faster cannot make stale source data fresh; compare successive trade timestamps instead.

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.
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
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
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
    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"

Captured Response and Illustrative Shapes

Download a populated SPY recent-trades capture: five records requested from the historical tape route at 2026-03-05T15:30:00 Eastern, captured September 17, 2026. The JSON retains its trade timestamps and archive provenance; it is a historical replay example, not current market activity. The examples below illustrate additional views with placeholder values.

The following JSON is an illustrative shape only: field names are camelCase pass-through from the ingest service and the numbers are placeholders, not live market data. Read fields defensively rather than hard-coding an exact schema.

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:

{
  "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.

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.

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")
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.

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
• Net Dealer Premium: Are Dealers Long or Short the Tape?
• The Complete Flow & Dealer-Positioning API Map
• Interactive API Playground

The FlashAlpha options flow API gives you five views of one dataset: recent prints, trade-flow totals, large blocks, minute history, and a cumulative net-flow series per symbol, plus a cross-market buyer/seller leaderboard and a net-notional outlier scan, with parallel stock-trade endpoints that drop the option-only contract fields. It is camelCase pass-through JSON off the ingest service, on the Alpha tier. Rank unusual symbols with /outliers, confirm size with /blocks, and chart conviction with /cumulative. You skip the raw-feed ingestion and side-classification engineering and start at the signal. This is the article that says the unusual-flow feature now exists, go build the scanner.