llms.txt

# flashalpha-go

> Official Go SDK for the [FlashAlpha](https://flashalpha.com) options analytics API — institutional-grade gamma exposure (GEX), delta exposure (DEX), vanna/charm exposure, 0DTE pin risk, max pain, variance risk premium (VRP), volatility surfaces, and a live options screener. One round-trip per analytic, typed Go response models, no external dependencies.

FlashAlpha is the analytics API for **options dealer flow**. The same numbers that drive intraday equity-index moves — net dealer GEX, the gamma flip, call/put walls, vanna/charm hedging — are exposed as REST endpoints with typed responses.

This SDK gives Go applications and AI agents direct access to that data. Every endpoint is one method call; the typed response models surface load-bearing fields (dealer-Greek aggregates, 0DTE pin scores, hedging-flow estimates, regime classifiers) with full doc comments so they're discoverable from `gopls` / `go doc` without leaving the editor.

- **Install:** `go get github.com/FlashAlpha-lab/flashalpha-go` (Go 1.21+, no external deps)
- **Sister SDK for replay:** `go get github.com/FlashAlpha-lab/flashalpha-historical-go` — same shape, point-in-time `at=` parameter
- **Sign up & API keys:** [https://flashalpha.com](https://flashalpha.com)
- **Interactive playground:** [https://lab.flashalpha.com/swagger](https://lab.flashalpha.com/swagger)

## Data provenance

Every response carries `data_as_of`: when each upstream feed last delivered to the node
that answered - equity and index spot, their option chains, futures and futures options,
the classified trade tape, settled open interest, and the macro series, each reported
separately because they arrive over different pipes and fail independently. `nil` means
that node has not seen that feed, not that it is broken. Read each feed against its own
cadence: settled open interest dated to the previous session's close is correct, while an
options feed an hour behind during the regular session is not. `endpoint_version`
identifies the deployment. Every response type embeds `ResponseEnvelope`, so both are
promoted fields. Full reference:
https://flashalpha.com/docs/lab-api-overview#response-envelope

## Key endpoints

- `Gex / Dex / Vex / Chex(ctx, symbol, ...)` — per-strike gamma / delta / vanna / charm exposure (Free+).
- `ExposureSummary(ctx, symbol)` — net dealer Greeks, gamma flip, hedging estimates, 0DTE attribution, regime narrative (Growth+).
- `ZeroDte(ctx, symbol, ...)` — same-day-expiry analytics: regime, expected move, pin risk, dealer hedging flow at +/- 10bp / 25bp / 50bp / 1pct, decay, vol context (Growth+).
- `MaxPain(ctx, symbol, ...)` — max-pain strike, pain curve, OI breakdown, dealer-alignment overlay, pin probability (Growth+).
- `Narrative(ctx, symbol)` — server-authored verbal summary of the regime + key levels + flow + outlook. Strings safe to surface verbatim in LLM tool responses (Growth+).
- `ExposureLevels(ctx, symbol)` — compact key-level view (gamma flip, walls, magnet) (Free+).
- `StockSummary(ctx, symbol)` — composite snapshot: price, volatility, options flow, dealer exposure, macro context — one round-trip in lieu of five.
- `Vrp(ctx, symbol)` — variance risk premium: implied-vs-realized vol spread, gamma/vanna conditioning, strategy scores. Returns typed `*VrpResponse` (Alpha+).
- `Volatility / AdvVolatility(ctx, symbol)` — IV ladder, skew, term structure, SVI calibration, variance-swap pricing.
- `Greeks / IV / Kelly(ctx, params)` — Black-Scholes-Merton calculator: theoretical price, full first/second/third-order greeks, implied vol from market price, Kelly-criterion sizing.
- `Screener(ctx, request)` — live options screener — filter and rank by GEX, VRP, harvest scores, custom formulas (Growth+ for 10-symbol universe; Alpha+ for ~250 symbols, formulas, harvest/dealer-flow-risk scores).
- **Flow — live, simulation-aware (Alpha+):** intraday trade-tape-adjusted dealer exposure + scored unusual-flow signals + the raw options/stock flow feed. Analytics: `FlowLevels` / `FlowPinRisk` / `FlowSummary` / `FlowOi` / `FlowGex` / `FlowDex` / `FlowDealerRisk` / `FlowLive` — live gamma flip / walls / max pain, 0DTE pin score, flow direction + GEX shift, OI simulator state, flow-adjusted GEX/DEX, settled-vs-live dealer risk, all-in-one bundle. Signals: `FlowSignals` / `FlowSignalsSummary` — scored per-print signals (block/sweep, NBBO aggressor, opening/closing bias, intent) with 0-100 score + chain enrichment, plus net bullish/bearish + opening/closing premium roll-up. `FlowDealerPremium` — net dealer option premium paid/received over a window. Raw: `FlowOptionRecent|Summary|Blocks|History|Cumulative`, the `FlowStock*` equivalents, `FlowStockBars` (intraday OHLCV stock-flow bars), and `FlowOptionsLeaderboard|Outliers` / `FlowStocksLeaderboard|Outliers`. Every method has a strongly-typed `*Typed` variant (e.g. `FlowLevelsTyped`).
- **Zero-DTE Flow (Growth+/Alpha+):** intraday same-day-expiry flow analytics — `FlowZeroDteSnapshot` (exposure + live flow direction), `FlowZeroDteSeries` (GEX/DEX/pin time series), `FlowZeroDteHedgeFlow` (dealer hedging flow by side), `FlowZeroDteHeatmap` (strike×time gex/dex/vex/chex/oi/signed_flow heatmap), `FlowZeroDteStrikeFlow` (per-strike intraday signed flow).
- **Exposure extras (Growth+):** `ExposureSheet` (full per-strike GEX/DEX/VEX/CHEX sheet), `ExposureTermStructure` (exposure by DTE bucket), `ExposureBasket` (aggregate exposure across a weighted basket), `ExposureOiDiff` (day-over-day OI change, top movers).
- **Volatility extras:** `Liquidity` (spreads/depth quality, Growth+), `SkewTerm` (skew + term-structure grid, Growth+), `SpotVolCorrelation` (leverage effect, Growth+), `ExpectedMove` (straddle-implied move, Basic+, `WithExpectedMoveExpiry`), `Dispersion` (index-vs-single-name correlation trade, Alpha+), `SurfaceSvi` (calibrated SVI surface params, Alpha+), `VrpHistory` (VRP time series, Alpha+), `RealizedVolatility` (range-based realized-vol estimators — close-to-close/Parkinson/Garman-Klass/Rogers-Satchell/Yang-Zhang over 10/20/30d, Alpha+), `VolatilityForecast` (EWMA + HAR-RV + GARCH(1,1) conditional-vol forecasts, Alpha+, `WithForecastDist`).
- **Macro / universe:** `VixState` (VIX regime — level, term structure, percentile, contango/backwardation, Growth+), `Universe` (ranked tradable-universe snapshot, Public, `WithUniverseSort`/`WithUniverseLimit`).
- **Strategy signals (Basic+/Growth+/Alpha+):** ten decision-style endpoints sharing ONE typed `StrategyDecisionResponse` envelope (decision = insufficient_data/avoid/neutral/candidate, score, confidence, regime, best_structures, why/avoid_if, data_quality): `StrategyFlowAnomaly`, `StrategyExpiryPositioning`, `StrategyZeroDte`, `StrategyDealerRegime`, `StrategyVolCarry`, `StrategyYieldEnhancement`, `StrategySurfaceAnomaly`, `StrategySkew`, `StrategyTermStructure`, `StrategyTailPricing`. Tune with `WithStrategyExpiry`, `WithStrategyMinOpenInterest`, `WithStrategyWingWidth`, `WithStrategyTargetShortDelta`/`TargetDelta`, `WithStrategyMaxWidth`, `WithStrategyMinCredit`, `WithStrategyStructure`, `WithStrategyExcludeEarningsBeforeExpiry`.
- **Earnings analytics (Growth+/Alpha+):** `EarningsCalendar`, `EarningsExpectedMove`, `EarningsHistory`, `EarningsIvCrush`, `EarningsVrp`, `EarningsDealerPositioning`, `EarningsStrategies`, `EarningsScreener` — earnings-implied expected move, historical move vs implied, IV-crush, earnings VRP, dealer positioning into the print, suggested structures, and a rankable earnings screener.
- **Multi-leg structures (Basic+, POST, pure-math):** `StructurePnl` (at-expiry payoff curve, breakevens, max profit/loss) and `StructureGreeks` (aggregate quantity-scaled, direction-signed position Greeks across legs/calendars/diagonals). Deterministic — no market-data lookup.
- **Screener discovery:** `ScreenerFields` — enumerate screener fields + operators to build queries dynamically (Free+).

## Tier breakdown

- **Free**: GEX/DEX/VEX/CHEX, ExposureLevels, StockQuote, OptionQuote, Surface, StockSummary, BSM Greeks/IV, Tickers, Options, Symbols, Health, Account, Historical stock/option quotes.
- **Basic**: + Dex/Vex/Chex, MaxPain, ExpectedMove, StrategyExpiryPositioning, StructurePnl/StructureGreeks.
- **Growth**: + ExposureSummary, Narrative, ZeroDte, Volatility, Kelly, Screener (10-symbol universe), ExposureSheet/TermStructure/Basket/OiDiff, Liquidity, SkewTerm, SpotVolCorrelation, VixState, the Zero-DTE Flow group, Earnings analytics, and the Growth-tier Strategy signals (FlowAnomaly, ZeroDte, DealerRegime, YieldEnhancement, Skew, TermStructure, TailPricing).
- **Alpha**: + AdvVolatility, Vrp, VrpHistory, SurfaceSvi, Dispersion, RealizedVolatility, VolatilityForecast, the full `Flow*` tier (incl. FlowSignals/FlowSignalsSummary, FlowDealerPremium, FlowStockBars), Alpha-tier Strategy signals (VolCarry, SurfaceAnomaly), Alpha-tier Earnings (Vrp, DealerPositioning, Strategies, Screener), Screener (full ~250-symbol universe with formulas, harvest scores, dealer-flow-risk scores).

## Authentication

Every request requires an API key passed via the `X-Api-Key` header.

```go
client := flashalpha.NewClient(os.Getenv("FLASHALPHA_API_KEY"))
```

Get a key at [https://flashalpha.com](https://flashalpha.com).

## Documentation

- [README](README.md) — full method tables, examples, error types
- [API reference (docs/api.md)](docs/api.md)
- [Interactive Swagger playground](https://lab.flashalpha.com/swagger)
- [FlashAlpha docs](https://flashalpha.com/docs)