llms.txt

# FlashAlpha — Python SDK

> FlashAlpha is an institutional-grade options analytics API: dealer
> positioning (GEX/DEX/VEX/CHEX), gamma flip, call/put walls, max pain,
> 0DTE attribution, variance risk premium, IV term structure, and
> macro context — all on one round-trip per endpoint.

This is the live (current-minute) Python SDK. For point-in-time replay
of every analytics endpoint going back to 2018, see the companion
`flashalpha-historical` package.

## Install

```bash
pip install flashalpha
```

## Quickstart

```python
from flashalpha import FlashAlpha

client = FlashAlpha(api_key="YOUR_API_KEY")

# Single-call dashboard — price, IV, HV, VRP, skew, term structure,
# full dealer exposure, macro context.
summary = client.stock_summary("SPY")

# Net dealer Greeks + gamma flip + ±1% hedging estimate.
exp = client.exposure_summary("SPY")

# Same-day-expiry deep dive (±10bp / ±25bp / ±50bp / ±1% buckets,
# pin risk, time-to-close decay).
zdte = client.zero_dte("SPY")

# Variance Risk Premium dashboard (Alpha+).
vrp = client.vrp("SPY")

# Max pain dashboard (Basic+).
mp = client.maxpain("SPY")

# Dealer-flow levels — gamma flip, walls, 0DTE magnet.
levels = client.exposure_levels("SPY")

# LLM-friendly verbal output (Growth+).
narrative = client.exposure_narrative("SPY")
```

## Key endpoints

- `GET /v1/stock/{symbol}/summary` — single best snapshot. Price, IV,
  HV, VRP, 25-delta skew, IV term structure, options flow aggregates,
  full dealer exposure (Greeks, walls, gamma flip, max pain, hedging
  estimate, 0DTE attribution, top strikes), and macro context (VIX,
  VVIX, SKEW, SPX, MOVE, term structure, fear/greed). Dual-mode auth:
  authenticated = live; unauthenticated = previous-day cached snapshot.
- `GET /v1/exposure/summary/{symbol}` — net dealer Greeks
  (gamma/delta/vanna/charm), gamma flip, ±1% hedging estimate,
  verbal regime narratives, 0DTE attribution.
- `GET /v1/exposure/zero-dte/{symbol}` — same-day-expiry deep dive:
  ±10bp / ±25bp / ±50bp / ±1% hedging buckets, pin-risk scoring,
  time-to-close decay, vol context, full strike grid.
- `GET /v1/exposure/levels/{symbol}` — pared-down headline strikes:
  gamma flip, max ±gamma, call wall, put wall, highest OI, 0DTE magnet.
- `GET /v1/exposure/narrative/{symbol}` — LLM-friendly verbal output:
  plain-English narrative strings safe to surface verbatim, paired
  with the numeric data block that backs them. (Growth+)
- `GET /v1/vrp/{symbol}` — Variance Risk Premium dashboard: core IV
  vs RV ladders, directional skew (downside vs upside), term VRP,
  GEX-conditioned harvest score, vanna-conditioned outlook, regime
  classification, strategy suitability scores. (Alpha+)
- `GET /v1/maxpain/{symbol}` — strike where total option-holder pain
  is minimized; per-strike pain curve, OI breakdown, per-expiry
  calendar, GEX-based dealer alignment, expected move, pin
  probability. (Basic+)
- `GET /v1/pricing/greeks` — stateless Black-Scholes-Merton pricer:
  theoretical price plus first/second/third-order Greeks
  (delta, gamma, theta, vega, rho, vanna, charm, vomma, dual delta,
  speed, zomma, color, ultima, lambda, veta).

## Flow — live, simulation-aware (Alpha+)

Intraday trade-tape-adjusted dealer exposure plus the raw options/stock
flow feed — 24 endpoints under `/v1/flow/*`:

- **Analytics** (snake_case): `flow_levels`, `flow_pin_risk`,
  `flow_summary`, `flow_oi`, `flow_gex`, `flow_dex`, `flow_dealer_risk`,
  `flow_live` — live gamma flip / call & put walls / max pain, 0DTE
  pin score, flow direction + headline GEX shift, OI simulator state,
  flow-adjusted GEX/DEX per strike, settled-vs-live dealer risk, and an
  everything-at-once bundle. Optional `expiry="YYYY-MM-DD"` slice.
- **Unusual-flow signals** (snake_case): `flow_signals` /
  `flow_signals_summary` — scored, classified per-print signals
  (block/sweep, NBBO aggressor, opening/closing bias, intent) with a
  0-100 composite score, chain-context enrichment, and a net
  bullish/bearish + opening/closing premium roll-up.
- **Raw flow** (camelCase wire keys): `flow_option_recent` /
  `flow_option_summary` / `flow_option_blocks` / `flow_option_history` /
  `flow_option_cumulative`, the `flow_stock_*` equivalents, and
  cross-symbol `flow_options_leaderboard` / `flow_options_outliers` /
  `flow_stocks_leaderboard` / `flow_stocks_outliers` — per-trade prints,
  large blocks, per-minute buckets, cumulative net-flow series, and
  ranked leaderboards / outliers. All require the Alpha plan.

## Zero-DTE Flow — intraday, simulation-aware

Live intraday view of today's 0DTE dealer-positioning landscape, computed
on effective OI (settled + intraday simulator delta):

- `flow_zero_dte_snapshot` — current live 0DTE shape (same as `zero_dte`
  plus a `flow_direction` block: amplifying / dampening / regime_flip). (Growth+)
- `flow_zero_dte_series` — intraday time series of headline 0DTE metrics
  (net GEX/DEX, gamma flip, walls, magnet, pin score, ATM IV, charm) +
  cumulative dealer hedge-flow. `bar` ∈ 30s/1m/5m/15m. (Growth+)
- `flow_zero_dte_hedge_flow` — estimated dealer hedge-flow time series,
  projectable to `all`/`calls`/`puts`. (Growth+)
- `flow_zero_dte_heatmap` — per-strike intraday heatmap of gex/dex/vex/chex/
  oi/signed_flow, raw or delta mode. (Alpha+)
- `flow_zero_dte_strike_flow` — per-strike signed aggressor flow (delta-$,
  gamma-$, contract count per bar). (Alpha+)
- `flow_dealer_premium` — full-tape Net Dealer Premium roll-up (VWAP-weighted). (Alpha+)
- `flow_stock_bars` — multi-resolution OHLCV+flow bars (1s/1m/5m/15m/30m/1h/4h). (Alpha+)

## Strategy Signals — uniform decision envelope

Ten decision-support endpoints under `/v1/strategies/*`, each scoring one
trading idea 0-100, classifying a regime, and returning ranked tradeable
structures (legs, credit/debit, breakevens, edge/liquidity scores) in the
single shared `StrategyDecisionResponse` shape:

- `strategy_flow_anomaly` — directional flow imbalance (Growth+)
- `strategy_expiry_positioning` — OPEX pin / iron fly (Basic+)
- `strategy_zero_dte` — same-day 0DTE range compression (Growth+, needs 0DTE)
- `strategy_dealer_regime` — dealer gamma regime (Growth+)
- `strategy_vol_carry` — VRP carry / short vol (Alpha+)
- `strategy_yield_enhancement` — covered call / cash-secured put (Growth+)
- `strategy_surface_anomaly` — rich/cheap wings vs SVI fit (Alpha+)
- `strategy_skew` — skew richness (Growth+)
- `strategy_term_structure` — IV term-structure slope (Growth+)
- `strategy_tail_pricing` — tail (deep-wing) pricing richness (Growth+)

## Earnings Analytics

Event-driven volatility analytics under `/v1/earnings/*`:

- `earnings_calendar` — forward earnings calendar (Growth+)
- `earnings_expected_move` — implied-move decomposition: earnings jump vs
  baseline diffusion from the pre/post-event SVI term structure (Growth+)
- `earnings_history` — past events: EPS/revenue surprises, implied-vs-actual
  moves, realized IV crush (Growth+)
- `earnings_iv_crush` — expected IV crush + historical crush distribution (Growth+)
- `earnings_vrp` — earnings VRP richness assessment (Alpha+)
- `earnings_dealer_positioning` — dealer walls / GEX buckets / charm into the event (Alpha+)
- `earnings_strategies` — strategy-suitability scores for the event (Alpha+)
- `earnings_screener` — cross-sectional earnings screener: vrp_richest /
  cheapest_move / highest_crush / importance (Alpha+)

## Structures — pure-math, multi-leg (POST)

Deterministic functions of the legs you supply — no market-data lookup:

- `structure_pnl` — at-expiry P&L curve, breakevens, max profit/loss (Basic+)
- `structure_greeks` — aggregate Black-Scholes greeks across a multi-leg
  position; each leg carries its own expiry + implied vol so calendars and
  diagonals aggregate correctly (Basic+)

## Volatility, dispersion & macro (additional)

- `surface_svi` — live SVI params (a, b, ρ, m, σ) per expiry slice (Alpha+)
- `exposure_sheet` — unified per-strike GEX/DEX/VEX/CHEX/DAG + Line-in-the-Sand
  + gamma peaks + OPEX flags (Growth+)
- `exposure_term_structure` — exposure by DTE bucket and per expiry (Growth+)
- `exposure_basket` — weighted cross-symbol exposure aggregate (Growth+)
- `exposure_oi_diff` — day-over-day open-interest deltas, top-N (Growth+)
- `liquidity` — per-expiry execution score, bid-ask spreads, OI depth (Growth+)
- `skew_term` — 25-delta skew + risk-reversal term structure (Growth+)
- `spot_vol_correlation` — spot-vol correlation 20d/60d (Growth+)
- `dispersion` — implied-vs-realized correlation between an index and a basket
  (correlation premium, per-constituent contribution) for dispersion / vol-arb (Alpha+)
- `expected_move` — straddle-implied expected move per expiry (Basic+)
- `realized_volatility` — range-based realized vol estimators (close-to-close,
  Parkinson, Garman-Klass, Rogers-Satchell, Yang-Zhang) over 10/20/30-day
  windows (Alpha+)
- `volatility_forecast` — conditional vol forecasts (EWMA λ=0.94, HAR-RV,
  GARCH(1,1) MLE); optional `dist` = student_t (default) | gaussian (Alpha+)
- `vrp_history` — daily VRP time series for charting/backtesting (Alpha+)
- `vix_state` — over/under-vixing regime (VIX vs SPX 20d realized vol) (Growth+)
- `universe` — curated tier-1/tier-2 symbol directory (Public)
- `screener_fields` — every screener-referenceable field + type (any key)

## Typed responses

Every endpoint listed above has a corresponding `TypedDict` model in
`flashalpha.types`. At runtime each response is a plain `dict`, so
existing `result["field"]` code keeps working — type checkers and IDEs
just see the field shape and provide autocomplete.

```python
from flashalpha import StockSummaryResponse, ExposureSummaryResponse

summary: StockSummaryResponse = client.stock_summary("SPY")
gamma_flip = summary["exposure"]["gamma_flip"]  # autocompleted
```

## Tier breakdown

- **Free**: dual-mode preview tier — `stock_summary` returns a
  previous-day cached snapshot without an API key.
- **Basic**: live `exposure_summary`, `exposure_levels`, `zero_dte`,
  `maxpain`, `pricing/greeks`.
- **Alpha**: adds `vrp` and full historical replay of the above.
- **Growth**: adds `exposure_narrative` and higher rate limits.
- **Pro / Enterprise**: bespoke; contact sales.

## Links

- Playground (interactive Swagger): https://lab.flashalpha.com/swagger
- Sign up: https://flashalpha.com
- GitHub: https://github.com/flashalpha