Build a Live Dealer Flow Monitor: Intraday GEX, Live Pin Risk and Regime Flips in One API Call

If you're searching for a live gamma exposure API, a real-time dealer positioning API, an intraday pin risk API, or trying to figure out how to detect a gamma regime flip during the session, this is the guide. The FlashAlpha /v1/flow/* surface returns simulation-aware live GEX/DEX, live key levels, a 0-100 pin-risk score with sub-score breakdown, a settled-vs-live dealer-risk shift, and a flow_direction classifier that fires intraday - all from a handful of calls covering 6,000+ US equities and ETFs.

The Problem: Settled OI Is Yesterday-Anchored

Every dealer-positioning tool built on the /v1/exposure/* surface uses settled OPRA open interest. Settled OI is authoritative, but it has one structural limitation: it reflects positions as of the previous session's close. During today's session, traders are opening and closing contracts continuously. Dealers are hedging that flow in real time. The settled snapshot does not move until tomorrow.

That gap matters most exactly when you care most. Into a 0DTE close, positioning can shift enough to move the gamma flip through spot - turning a pinned, mean-reverting tape into a fragile, momentum-amplifying one. A settled-OI monitor shows you that change the next morning, after the move already happened.

The Solution: Simulation-Aware Effective OI

The FlashAlpha flow surface is simulation-aware. Effective OI = settled OPRA OI + an intraday simulator delta. The simulator classifies the day's trades into buy/sell sides and applies a confidence weight of 0.43 to the side-classified volume before folding it into OI. The result is an estimate of where positioning sits right now, not where it settled yesterday.

This is a separate surface from /v1/exposure/*. The flow endpoints are independent and never alter settled exposure numbers. Field names disambiguate deliberately: settled GEX is gex, the live simulation-aware figure is live_gex. If you want the full derivation of effective OI and the 0.43 weight, the pillar article covers it: Live GEX vs Settled GEX: Intraday Options Flow Explained. This guide focuses on building the monitor.

The Hero Concept: flow_direction

The single highest-value field on the flow surface is flow_direction. It classifies how today's flow has moved dealer gamma positioning relative to the settled baseline. This is the alert you actually want - it fires while the session is live, not next morning.

The selling point versus any settled-OI tool: a regime_flip or amplifying signal fires during the session. You do not wait for tomorrow's OI print to learn the tape turned fragile at 2pm.

The API Approach: Flow Endpoints

FlashAlpha provides seven endpoints for the live dealer-flow surface (the raw-trade family is separate). One returns the entire headline bundle in a single call (Alpha+). The rest return individual components (Growth+) so users below Alpha can assemble the same picture from cheaper parts.

If you are on Alpha, /v1/flow/live is the whole monitor in one request. If you are on Growth, you compose the same dashboard from /flow/summary, /flow/levels, /flow/pin-risk, and /flow/dealer-risk. The aggregate live_net_gex from the per-strike surfaces differs from settled net_gex by exactly the flow contribution.

All flow endpoints accept an optional ?expiry=YYYY-MM-DD filter. The expiry value must be a literal YYYY-MM-DD date - the string today is not accepted and returns 400 invalid_expiry. An invalid expiry returns 400 invalid_expiry; a valid date with no contracts returns 404. To get a 0DTE-only live view, pass today's US/Eastern (ET) market date, e.g. expiry=2026-05-15 - the most actionable filter into the close.

Quick Start: Your First Live Flow Call

from flashalpha import FlashAlpha

fa = FlashAlpha("YOUR_KEY")

# Alpha tier: the whole live picture in one call
live = fa.flow_live("SPY")

print(f"Flow direction: {live['flow_direction']}")
print(f"Live GEX:       ${live['live_gex']:,.0f}")
print(f"GEX shift:      {live['flow_gex_pct_shift']:+.1%}")
print(f"Live gamma flip:{live['levels']['live_gamma_flip']}")
print(f"Live pin risk:  {live['pin_risk']['live_pin_risk']}/100")

# Growth tier: the cheap watchlist card
card = fa.flow_summary("SPY")
print(f"{card['symbol']}: {card['flow_direction']} "
      f"({card['contracts_with_flow']}/{card['contracts_total']} contracts)")

import { FlashAlpha } from 'flashalpha';

const fa = new FlashAlpha('YOUR_KEY');
const live = await fa.flowLive('SPY');

console.log(`Flow direction: ${live.flow_direction}`);
console.log(`Live GEX: ${live.live_gex}`);
console.log(`Live gamma flip: ${live.levels.live_gamma_flip}`);
console.log(`Live pin risk: ${live.pin_risk.live_pin_risk}/100`);

using FlashAlpha;

var fa = new FlashAlphaClient("YOUR_KEY");
var live = await fa.FlowLiveAsync("SPY");

Console.WriteLine($"Flow direction: {live.FlowDirection}");
Console.WriteLine($"Live GEX: {live.LiveGex:N0}");
Console.WriteLine($"Live gamma flip: {live.Levels.LiveGammaFlip}");
Console.WriteLine($"Live pin risk: {live.PinRisk.LivePinRisk}/100");

package main

import (
    "context"
    "fmt"
    flashalpha "github.com/FlashAlpha-lab/flashalpha-go"
)

func main() {
    fa := flashalpha.NewClient("YOUR_KEY")
    live, _ := fa.FlowLive(context.Background(), "SPY")

    fmt.Printf("Flow direction: %s\n", live.FlowDirection)
    fmt.Printf("Live GEX: %d\n", live.LiveGex)
    fmt.Printf("Live gamma flip: %.2f\n", live.Levels.LiveGammaFlip)
}

import com.flashalpha.FlashAlphaClient;
import com.google.gson.JsonObject;

FlashAlphaClient fa = new FlashAlphaClient("YOUR_KEY");
JsonObject live = fa.flowLive("SPY");

System.out.println("Flow direction: " + live.get("flow_direction").getAsString());
System.out.println("Live GEX: " + live.get("live_gex").getAsLong());
System.out.println("Live pin risk: " + live.getAsJsonObject("pin_risk").get("live_pin_risk"));

curl -H "X-Api-Key: YOUR_KEY" \
  "https://lab.flashalpha.com/v1/flow/live/SPY"

# Growth tier - cheap watchlist card
curl -H "X-Api-Key: YOUR_KEY" \
  "https://lab.flashalpha.com/v1/flow/summary/SPY"

Full Response Walkthrough

Here is what the flow summary endpoint returns for SPY into the close. This is the cheap card you call across an entire watchlist:

{
  "symbol": "SPY",
  "as_of": "2026-05-15T16:30:45Z",
  "underlying_price": 597.50,
  "expiry": "2026-05-15",
  "flow_direction": "amplifying",
  "intraday_oi_delta": 12450,
  "contracts_with_flow": 1842,
  "contracts_total": 4586,
  "live_gex": 12500000000,
  "flow_gex_pct_shift": 0.067
}

Read this top to bottom: flow exists on 1,842 of 4,586 contracts, the simulator added 12,450 contracts of effective OI, live GEX sits at $12.5B, and that is a +6.7% shift versus the settled baseline in the same direction - so the regime is being reinforced. flow_gex_pct_shift is null when settled GEX is zero but live is nonzero (no baseline to divide by), and 0 when both are zero.

The live levels endpoint returns the simulation-aware key levels:

{
  "symbol": "SPY",
  "as_of": "2026-05-15T16:30:45Z",
  "underlying_price": 597.50,
  "expiry": "2026-05-15",
  "live_gamma_flip": 595.50,
  "live_call_wall": 600,
  "live_put_wall": 590,
  "live_max_pain": 595
}

And the pin-risk endpoint returns a scored 0-100 magnet read with its component breakdown:

{
  "symbol": "SPY",
  "as_of": "2026-05-15T16:30:45Z",
  "underlying_price": 597.50,
  "expiry": "2026-05-15",
  "live_pin_risk": 67,
  "magnet_strike": 597.0,
  "distance_to_magnet_pct": 0.084,
  "time_to_close_hours": 1.234,
  "breakdown": {
    "oi_score": 78,
    "proximity_score": 92,
    "time_score": 45,
    "gamma_score": 60
  }
}

Every field your live dealer flow monitor needs is in these responses. On Alpha, /v1/flow/live returns all of this nested under one object so you make a single call. Let's wire each section into a dashboard.

Building the Dashboard: Section by Section

1. flow_direction Regime Banner

The flow_direction field is the headline of the whole monitor. Render it as a large, color-coded banner at the top of the dashboard - it tells a trader in one glance whether today's flow is reinforcing, weakening, or reversing the dealer regime.

card = fa.flow_summary("SPY")

direction = card['flow_direction']
shift = card['flow_gex_pct_shift']

banner = {
    "no_flow":     ("QUIET",      "#71717a", "No intraday flow yet. Live picture equals settled."),
    "neutral":     ("NEUTRAL",    "#3b82f6", "Flow is present but the regime has not moved."),
    "amplifying":  ("AMPLIFYING", "#dc2626", "Today's flow is reinforcing the regime - stronger pin or fragility."),
    "dampening":   ("DAMPENING",  "#16a34a", "The regime is weakening - the wall is losing grip."),
    "regime_flip": ("REGIME FLIP","#b91c1c", "Dealer hedging behavior has reversed INTRADAY."),
}

label, color, msg = banner[direction]
shift_txt = "n/a" if shift is None else f"{shift:+.1%}"
print(f"[{label}]  GEX shift: {shift_txt}")
print(msg)

Make regime_flip visually unmissable - it is the event the entire monitor exists to catch. The difference from a settled-OI dashboard is that this banner changes during the session, so a trader sees the regime turn the moment the flow tips it, not the next morning.

2. Live Levels vs Settled Levels Delta

The most actionable visualization is the gap between live and settled levels. If the settled gamma flip is at 596 but the live flip has slid to 595.50, dealers' hedging pivot has already moved - and a settled-only chart would not show it.

live_lv = fa.flow_levels("SPY")
settled_lv = fa.exposure_levels("SPY")['levels']
price = live_lv['underlying_price']

rows = [
    ("Gamma flip", settled_lv['gamma_flip'], live_lv['live_gamma_flip']),
    ("Call wall",  settled_lv['call_wall'],  live_lv['live_call_wall']),
    ("Put wall",   settled_lv['put_wall'],   live_lv['live_put_wall']),
]

print(f"Spot: {price}")
print(f"{'Level':<12}{'Settled':>10}{'Live':>10}{'Shift':>10}")
for name, settled, live in rows:
    shift = live - settled
    flag = "  <-- moved through spot" if (settled - price) * (live - price) < 0 else ""
    print(f"{name:<12}{settled:>10}{live:>10}{shift:>+10.2f}{flag}")

Plot both sets of levels on the price chart: settled as dashed lines, live as solid. When the live gamma flip crosses spot while the settled one has not, that is your earliest mechanical warning that the tape is about to change character.

3. Live Pin Risk Gauge with Sub-Score Breakdown

The pin-risk endpoint returns a single 0-100 score plus the four components that produced it. The composite is weighted 30% OI + 25% proximity + 25% time + 20% gamma. Display the headline number as a gauge and the four sub-scores as a small stacked bar so traders can see why the score is what it is.

pin = fa.flow_pin_risk("SPY")

score = pin['live_pin_risk']
magnet = pin['magnet_strike']
b = pin['breakdown']

weights = {'oi_score': 0.30, 'proximity_score': 0.25,
           'time_score': 0.25, 'gamma_score': 0.20}

print(f"Live pin risk: {score}/100  -> magnet {magnet}")
print(f"Distance to magnet: {pin['distance_to_magnet_pct']:.3f}%")
print(f"Time to close: {pin['time_to_close_hours']:.2f}h\n")

for k, w in weights.items():
    contrib = b[k] * w
    bar = "#" * int(b[k] / 4)
    print(f"  {k:<16} {b[k]:>3}  (x{w:.2f} = {contrib:5.1f})  {bar}")

The breakdown is what makes this gauge useful rather than a black box. A pin risk of 67 driven by a 92 proximity score and a 45 time score means price is glued to the magnet but there is still time for it to drift; the same 67 with a high time score and low proximity means the clock is the binding constraint. Surface the dominant sub-score as a one-line caption under the gauge.

4. Dealer-Risk Shift Panel

The dealer-risk endpoint pairs the settled and live dealer-positioning state and attaches the same flow_direction classifier. Use it for a compact "what changed today" panel.

dr = fa.flow_dealer_risk("SPY")

print(f"Direction:  {dr['flow_direction']}")
print(f"Settled GEX:${dr['settled_gex']:,.0f}")
print(f"Live GEX:   ${dr['live_gex']:,.0f}")
print(f"Shift:      {dr['flow_gex_pct_shift']:+.1%}"
      if dr['flow_gex_pct_shift'] is not None else "Shift:      n/a (no settled baseline)")

if dr['flow_direction'] == 'regime_flip':
    print("\nACTION: dealer hedging has reversed - reassess short premium and stops.")
elif dr['flow_direction'] == 'amplifying':
    print("\nNOTE: existing regime reinforced - expect stronger pin or stronger trend.")

This is the panel a discretionary trader checks before sizing into the close. It answers one question: is today's flow making the dealer regime stronger, weaker, or opposite to what settled OI says?

5. Multi-Symbol Watchlist Scanner

The /flow/summary card is cheap by design - call it across an entire universe to find where intraday flow is doing something. This is the scanner that surfaces the symbol you should be watching before it moves.

from flashalpha import FlashAlpha

fa = FlashAlpha("YOUR_KEY")
universe = ["SPY", "QQQ", "IWM", "TSLA", "NVDA", "AAPL", "AMZN", "META", "GOOGL", "MSFT"]

rank = {"regime_flip": 0, "amplifying": 1, "dampening": 2, "neutral": 3, "no_flow": 4}
results = []

for sym in universe:
    try:
        c = fa.flow_summary(sym)
        results.append(c)
    except Exception as e:
        print(f"Skipping {sym}: {e}")

# Surface regime flips and amplifying flow first
results.sort(key=lambda c: (rank[c['flow_direction']],
                            -(abs(c['flow_gex_pct_shift']) if c['flow_gex_pct_shift'] else 0)))

print(f"{'Symbol':>6}  {'Direction':>12}  {'GEX Shift':>10}  {'Flow/Total':>12}")
print("-" * 50)
for c in results:
    shift = c['flow_gex_pct_shift']
    shift_txt = " n/a" if shift is None else f"{shift:+.1%}"
    cov = f"{c['contracts_with_flow']}/{c['contracts_total']}"
    print(f"{c['symbol']:>6}  {c['flow_direction']:>12}  {shift_txt:>10}  {cov:>12}")

Symbols with regime_flip or large-magnitude amplifying flow rise to the top. These are your highest-conviction watchlist candidates - the names where the dealer regime is actively changing right now, not where it settled yesterday.

6. Intraday regime_flip Alert Poller

The highest-value alert in a live flow monitor is the moment flow_direction transitions into regime_flip (or into amplifying from a calmer state). Here is a poller that catches it intraday and fires a notification:

from flashalpha import FlashAlpha
from datetime import datetime
from zoneinfo import ZoneInfo
import time

fa = FlashAlpha("YOUR_KEY")
symbol = "SPY"
last_direction = None

ESCALATIONS = {("neutral", "amplifying"), ("dampening", "amplifying"),
               ("amplifying", "regime_flip"), ("neutral", "regime_flip"),
               ("no_flow", "regime_flip")}

while True:
    try:
        # today's US/Eastern (ET) market date gives the 0DTE-only live view
        # into the close - never the local machine date or UTC
        today_et = datetime.now(ZoneInfo("America/New_York")).date().isoformat()
        c = fa.flow_summary(symbol, expiry=today_et)
        direction = c['flow_direction']

        if last_direction and direction != last_direction:
            pair = (last_direction, direction)
            urgent = pair in ESCALATIONS or direction == "regime_flip"
            shift = c['flow_gex_pct_shift']
            shift_txt = "n/a" if shift is None else f"{shift:+.1%}"
            print(f"{'ALERT' if urgent else 'note'}: "
                  f"{last_direction} -> {direction}  (GEX shift {shift_txt})")
            if urgent:
                send_alert(symbol, last_direction, direction, c)

        last_direction = direction
        time.sleep(60)  # poll once a minute through the session
    except Exception as e:
        print(f"Error: {e}")
        time.sleep(60)

Passing today's US/Eastern (ET) market date as an explicit YYYY-MM-DD value (e.g. expiry=2026-05-15) narrows the poller to the 0DTE book, which is where intraday regime flips happen fastest and matter most into the close. Compute it from the ET clock, not the local machine date or UTC. When the transition fires, it fires while you can still act on it - that is the entire point of a simulation-aware monitor.

Using Live Flow Data with AI Agents

The Flow Analytics surface (/v1/flow/*) is REST-only currently - it has no MCP tools. FlashAlpha does run an MCP server, but it exposes other surfaces (exposure, volatility, VRP, and similar), not the live flow endpoints. So an AI agent consumes the flow surface the same way your code does: via plain authenticated REST or SDK calls, or by wrapping that REST call in your own agent tool.

from flashalpha import FlashAlpha

fa = FlashAlpha("YOUR_KEY")

# Define a tool your agent can call - it wraps the REST flow endpoints
def get_live_flow(symbol: str) -> dict:
    """Return simulation-aware flow_direction and live levels for a symbol."""
    summary = fa.flow_summary(symbol)
    levels = fa.flow_levels(symbol)
    return {
        "flow_direction": summary["flow_direction"],
        "flow_gex_pct_shift": summary["flow_gex_pct_shift"],
        "live_gamma_flip": levels["live_gamma_flip"],
        "underlying_price": levels["underlying_price"],
    }

Register get_live_flow as a tool with your agent framework. When asked "Has SPY's dealer regime flipped intraday, and how far is the live gamma flip from spot?" the agent calls the tool, which hits /v1/flow/summary and /v1/flow/levels over REST, then interprets the flow_direction classifier and the live-vs-settled level gap and answers in natural language. The classifier is well-suited to agents because it is already a discrete, pre-interpreted signal - the agent does not need to reason about raw OI deltas.

Why Not Build It Yourself?

You can. But notice this is strictly harder than a settled-OI tracker - you need everything that requires plus a live simulation layer:

1. A raw trade feed - Real-time options trade prints across all strikes and expirations for 6,000+ symbols, not just end-of-day chains. Few providers supply this and it is the expensive tier.
2. Side classification - For every trade, decide whether it was buyer-initiated or seller-initiated. This is a non-trivial inference problem (quote context, tick rules, sweep detection) and getting it wrong corrupts every downstream number.
3. A position-change simulator - Translate classified flow into an effective-OI delta with a calibrated confidence weight (FlashAlpha uses 0.43). Too aggressive and the live picture is noise; too timid and it never diverges from settled.
4. Live Greeks recomputation - Recompute gamma/delta on effective OI continuously through the session, not once at close.
5. Live level detection - Re-derive the gamma flip, call wall, put wall, and max pain on the moving effective-OI surface every snapshot, and detect zero-crossings as they happen.
6. Pin-risk scoring - Compose OI, proximity, time-to-close, and gamma sub-scores into a stable 0-100 number with documented weights.
7. The flow_direction classifier - Implement the same-sign / sign-change / zero-baseline logic with a calibrated neutral band so it does not flicker on noise.
8. Infrastructure - Run all of this in real time during market hours, reconcile against settled OPRA OI nightly, and keep the live surface strictly independent of the settled one.

That is a multi-month build before the banner shows a single regime, and the simulator calibration alone is an ongoing research problem. The FlashAlpha flow endpoints exist so you can skip all of it.

API Access and Pricing

The flow component endpoints (summary, levels, pin-risk, dealer-risk, per-strike GEX/DEX) are on the Growth plan. The single-call /v1/flow/live bundle is Alpha. The Free and Basic tiers do not include the flow surface; use them to evaluate the settled /v1/exposure/* endpoints first.

To evaluate before committing, the interactive API playground lets you test flow calls in the browser with your API key. The per-stock dashboards visualize the live flow surface, so you can see exactly what you are building against before writing code.

SDKs available in Python, JavaScript, C#, Go, and Java. All SDKs include typed exceptions (RateLimitError, TierRestrictedError) and automatic retries.

Frequently Asked Questions

Related Reading

• Live GEX vs Settled GEX: Intraday Options Flow Explained
• Build a Dealer Positioning Tracker with an API
• Pin Risk Score 0-100: How to Read the 0DTE Pin Magnet
• Call Wall, Put Wall, Gamma Flip: Options Levels Explained
• Options Flow API: Recent Trades, Blocks, and Leaderboard
• Interactive API Playground