Plain-English GEX: The Narrative API That Reads Dealer Positioning for You

If you are looking for a plain-English gamma exposure API, an AI-generated options market commentary endpoint, an LLM-ready dealer positioning summary, or a way to get a one-sentence GEX read instead of raw numbers, this is the reference. The FlashAlpha GET /v1/exposure/narrative/{symbol} endpoint returns an AI-generated briefing on the current options exposure picture, regime, key levels, flow, vanna, charm, 0DTE and outlook as sentences, plus a data block with the underlying numbers, on the Growth plan.

Read this first. The narrative is a structured, plain-English summary of the same settled-OI exposure model behind the GEX endpoint, it describes the current positioning, it does not predict price or give trade advice. The JSON below is an illustrative shape with placeholder numbers. Treat the outlook sentence as a characterisation of the current regime, not a forecast. The data block carries the exact numbers if you need to act programmatically rather than parse prose.

Why a Narrative Endpoint Exists

Two shifts make a words-first endpoint valuable:

• LLM agents are now first-class API consumers. An assistant answering "what's dealer positioning in SPY?" works far better when the data arrives as grounded sentences it can relay and reason over, rather than four billion-dollar figures it has to interpret and risk getting backwards. FlashAlpha exposes this over its MCP connector, so an agent can pull the narrative directly.
• Humans want the read, not the raw. Alerts, morning briefings, dashboard headers, and Discord bots all want a sentence, "Dealers are long gamma, expect range-bound action, watch the 600 call wall", not a table the reader has to decode.

The narrative endpoint is the interpretation layer over the exposure stack: it runs the same regime, level, flow, vanna, charm, and 0DTE reads the individual endpoints expose, and writes them up.

Quick Start

Just the symbol, no other parameters. You get the full briefing back.

from flashalpha import FlashAlpha

fa = FlashAlpha("YOUR_API_KEY")

n = fa.narrative("SPY")["narrative"]

print(n["regime"])
print(n["key_levels"])
print(n["outlook"])
# Need the raw numbers too? They're right there:
print("net GEX:", n["data"]["net_gex"], " VIX:", n["data"]["vix"])

import { FlashAlpha } from 'flashalpha';

const fa = new FlashAlpha('YOUR_API_KEY');

const { narrative: n } = await fa.narrative('SPY');

console.log(n.regime);
console.log(n.key_levels);
console.log(n.outlook);
console.log('net GEX:', n.data.net_gex, ' VIX:', n.data.vix);

using FlashAlpha;

var client = new FlashAlphaClient("YOUR_API_KEY");

var data = await client.NarrativeAsync("SPY");
var n = data.GetProperty("narrative");

Console.WriteLine(n.GetProperty("regime").GetString());
Console.WriteLine(n.GetProperty("outlook").GetString());

package main

import (
    "context"
    "fmt"

    flashalpha "github.com/FlashAlpha-lab/flashalpha-go"
)

func main() {
    fa := flashalpha.NewClient("YOUR_API_KEY")

    data, err := fa.Narrative(context.Background(), "SPY")
    if err != nil {
        panic(err)
    }

    n := data["narrative"].(map[string]interface{})
    fmt.Println(n["regime"])
    fmt.Println(n["outlook"])
}

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

Response Shape

An illustrative shape with placeholder numbers. Each narrative.* field is a sentence; narrative.data carries the structured values behind them.

{
  "symbol": "SPY",
  "underlying_price": 597.505,
  "as_of": "2026-06-13T16:30:45Z",
  "narrative": {
    "regime": "Dealers are long gamma (net GEX +$2.9B) - expect mean-reverting, range-bound price action.",
    "gex_change": "Net GEX increased from +$2.6B to +$2.9B (+11.5%) - gamma cushion strengthening.",
    "key_levels": "Call wall at 600, Put wall at 595, Gamma flip at 595.25.",
    "flow": "Top OI changes: +5,000 call OI at 600 strike, -2,000 put OI at 595 strike.",
    "vanna": "Positive vanna (+$1.2B) with VIX at 18.5 - vol compression supports upside.",
    "charm": "Positive charm (+$850M) - time decay pushing dealers to buy, providing support.",
    "zero_dte": "0DTE accounts for 10% of total GEX - minimal intraday impact.",
    "outlook": "Positive gamma regime with strengthening cushion. Testing 600 call wall.",
    "data": {
      "net_gex": 2850000000,
      "net_gex_prior": 2600000000,
      "net_gex_change_pct": 9.6,
      "vix": 18.5,
      "gamma_flip": 595.25,
      "call_wall": 600.0,
      "put_wall": 595.0,
      "regime": "positive_gamma",
      "zero_dte_pct": 10.0,
      "top_oi_changes": [{"strike": 600.0, "type": "C", "oi_change": 5000, "volume": 1250}]
    }
  }
}

How To: Ground an LLM Agent

The narrative endpoint is purpose-built as a tool for an LLM. Instead of handing the model a raw GEX number and hoping it reasons about dealer mechanics correctly, you hand it grounded sentences it can relay and build on. The cleanest path is the MCP connector, the model calls the narrative tool itself, but you can also inject it into a prompt directly:

from flashalpha import FlashAlpha

fa = FlashAlpha("YOUR_API_KEY")

def positioning_context(symbol):
    n = fa.narrative(symbol)["narrative"]
    return "\n".join([
        f"Regime: {n['regime']}",
        f"Levels: {n['key_levels']}",
        f"Vanna: {n['vanna']}",
        f"Charm: {n['charm']}",
        f"Outlook: {n['outlook']}",
    ])

# Drop straight into a system/context message for the model
context = positioning_context("SPY")
prompt = (
    "You are an options desk assistant. Use only the dealer-positioning context below.\n\n"
    f"{context}\n\n"
    "Question: Is SPY set up to trend or mean-revert today, and which level matters most?"
)
# -> send `prompt` to your model of choice

Because the sentences are grounded in the live exposure model, the model isn't inventing a regime read, it's relaying one. And the data block is right there if you want the agent to cite an exact number.

How To: Auto-Generate Market Commentary & Alerts

For humans, the same endpoint is a ready-made alert body. A morning briefing, a regime-flip Discord post, or a dashboard header is one call and a couple of fields:

syms = ["SPY", "QQQ", "IWM"]
lines = []
for s in syms:
    n = fa.narrative(s)["narrative"]
    lines.append(f"**{s}** - {n['regime']}\n  {n['key_levels']}\n  {n['outlook']}")

briefing = "Morning dealer-positioning briefing\n\n" + "\n\n".join(lines)
# post_to_discord(briefing)  /  send_email(briefing)  /  render_dashboard_header(briefing)

For a regime-flip alert specifically, branch on the structured field rather than the prose, watch narrative.data.regime for a transition between positive_gamma and negative_gamma, and fire the human-readable regime / outlook sentences as the alert body. You get reliable triggering off the data and clean copy off the words.

This is the building block behind automated market commentary, the narrative endpoint is the sentence generator you would otherwise have to write and maintain yourself.

API Access and Pricing

The narrative endpoint is on the Growth plan and higher, and is exposed over the FlashAlpha MCP connector for LLM agents.

Try the shape in the browser via the narrative endpoint docs (live "Try It" widget) or the interactive API playground. To wire it into an assistant, see Connect Claude to FlashAlpha over MCP. SDKs cover Python, JavaScript, C#, Go, and Java.

Frequently Asked Questions

Related Reading

• The Complete Flow & Dealer-Positioning API Map, every flow and exposure endpoint in one index
• Connect Claude to FlashAlpha over MCP
• AI Trade Alerts API: Build Automated Market Commentary
• What Is Gamma Exposure (GEX), Explained
• Narrative Analysis API Reference
• Interactive API Playground