flashalpha 1.2.2__tar.gz → 1.2.3__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (9) hide show
  1. {flashalpha-1.2.2 → flashalpha-1.2.3}/PKG-INFO +5 -5
  2. {flashalpha-1.2.2 → flashalpha-1.2.3}/README.md +393 -393
  3. {flashalpha-1.2.2 → flashalpha-1.2.3}/pyproject.toml +99 -99
  4. {flashalpha-1.2.2 → flashalpha-1.2.3}/src/flashalpha/__init__.py +1 -1
  5. {flashalpha-1.2.2 → flashalpha-1.2.3}/.gitignore +0 -0
  6. {flashalpha-1.2.2 → flashalpha-1.2.3}/LICENSE +0 -0
  7. {flashalpha-1.2.2 → flashalpha-1.2.3}/src/flashalpha/client.py +0 -0
  8. {flashalpha-1.2.2 → flashalpha-1.2.3}/src/flashalpha/exceptions.py +0 -0
  9. {flashalpha-1.2.2 → flashalpha-1.2.3}/src/flashalpha/types.py +0 -0
{flashalpha-1.2.2 → flashalpha-1.2.3}/PKG-INFO RENAMED
@@ -1,6 +1,6 @@
1
- Metadata-Version: 2.4
1
+ Metadata-Version: 2.5
2
2
  Name: flashalpha
3
- Version: 1.2.2
3
+ Version: 1.2.3
4
4
  Summary: Python SDK for the FlashAlpha options analytics API — live options screener, gamma exposure (GEX), VRP, delta, vanna, charm, greeks, 0DTE analytics, volatility surfaces, and more.
5
5
  Project-URL: Homepage, https://flashalpha.com
6
6
  Project-URL: Documentation, https://flashalpha.com/docs
@@ -373,16 +373,16 @@ Get your API key at **[flashalpha.com](https://flashalpha.com)**
373
373
  | `fa.structure_pnl(legs, ...)` | Multi-leg at-expiry P&L, breakevens, max P/L | Basic+ |
374
374
  | `fa.structure_greeks(legs, spot=...)` | Aggregate multi-leg Black-Scholes greeks | Basic+ |
375
375
 
376
- ## Futures (CME equity-index)
376
+ ## Futures (CME)
377
377
 
378
- FlashAlpha serves the full options-analytics stack for **CME equity-index futures** — **`ES=F`** (E-mini S&P 500) and **`NQ=F`** (E-mini Nasdaq-100). Options-on-futures are priced with **Black-76** (forward-priced) using the correct CME contract multipliers. Everything that works for an equity works for futures: gamma exposure (GEX), DEX, VEX, CHEX, key levels, max pain, the IV surface, exposure summary, narrative, and live flow.
378
+ FlashAlpha serves the full options-analytics stack for **CME futures** across six complexes - equity index (`ES=F`, `NQ=F`, `RTY=F`, `YM=F`, `MES=F`, `MNQ=F`), metals (`GC=F` gold, `SI=F` silver), energy (`CL=F` crude oil, `NG=F` natural gas), the Treasury curve (`ZT=F`, `ZF=F`, `ZN=F`, `TN=F`, `ZB=F`, `UB=F`), grains (`ZC=F` corn, `ZS=F` soybeans, `ZW=F` wheat) and crypto (`BTC=F` bitcoin). Options-on-futures are priced with **Black-76** (forward-priced) and each root carries its own CME contract multiplier, so notionals and dollar gamma are in real dollars. Note the quote conventions: Treasuries are quoted in points of par and grains in cents, so their multipliers are the contract size divided by 100. Everything that works for an equity works for futures: gamma exposure (GEX), DEX, VEX, CHEX, key levels, max pain, the IV surface, exposure summary, narrative, and live flow.
379
379
 
380
380
  ```python
381
381
  gex = fa.gex("ES=F") # Gamma exposure for the E-mini S&P 500 future
382
382
  print(f"Net GEX: ${gex['net_gex']:,.0f}")
383
383
  ```
384
384
 
385
- Use the `=F` suffix — bare `ES`/`NQ` are equities, not futures. In raw REST paths URL-encode the `=` as `%3D` (e.g. `GET /v1/exposure/gex/ES%3DF`); SDK methods take the plain string `"ES=F"`. Historical replay for futures is coming; live analytics are available now.
385
+ Use the `=F` suffix - bare `ES`/`NQ` are equities, not futures. In raw REST paths URL-encode the `=` as `%3D` (e.g. `GET /v1/exposure/gex/GC%3DF`); SDK methods take the plain string `"GC=F"`. Futures symbols require the Growth plan or higher. Historical replay for futures is coming; live analytics are available now.
386
386
 
387
387
  ## Other SDKs
388
388
 
{flashalpha-1.2.2 → flashalpha-1.2.3}/README.md RENAMED
@@ -1,393 +1,393 @@
1
- # FlashAlpha Python SDK
2
-
3
- [![PyPI](https://img.shields.io/pypi/v/flashalpha)](https://pypi.org/project/flashalpha/)
4
- [![Python](https://img.shields.io/pypi/pyversions/flashalpha)](https://pypi.org/project/flashalpha/)
5
- [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
6
- [![CI](https://github.com/FlashAlpha-lab/flashalpha-python/actions/workflows/ci.yml/badge.svg)](https://github.com/FlashAlpha-lab/flashalpha-python/actions/workflows/ci.yml)
7
-
8
- Python client for the [FlashAlpha options analytics API](https://flashalpha.com). Access a **live options screener** (filter/rank symbols by gamma exposure, VRP, IV, greeks, harvest scores, and custom formulas), real-time gamma exposure (GEX), delta exposure (DEX), vanna exposure (VEX), charm exposure (CHEX), 0DTE analytics, Black-Scholes greeks, implied volatility, volatility surfaces, dealer positioning, Kelly criterion sizing, and more — all from Python.
9
-
10
- > 🔑 **[Get a free API key at flashalpha.com →](https://flashalpha.com)** · 📚 [API documentation](https://flashalpha.com/docs) · 💹 [FlashAlpha options analytics API](https://flashalpha.com)
11
-
12
- ```bash
13
- pip install flashalpha
14
- ```
15
-
16
- ## Quick Start
17
-
18
- ```python
19
- from flashalpha import FlashAlpha
20
-
21
- fa = FlashAlpha("YOUR_API_KEY") # Get a free key at flashalpha.com
22
-
23
- # Gamma exposure by strike
24
- gex = fa.gex("SPY")
25
- print(f"Net GEX: ${gex['net_gex']:,.0f}")
26
- print(f"Gamma flip: {gex['gamma_flip']}")
27
-
28
- for strike in gex["strikes"][:5]:
29
- print(f" {strike['strike']}: net ${strike['net_gex']:,.0f}")
30
- ```
31
-
32
- Get your free API key at [flashalpha.com](https://flashalpha.com) — no credit card required.
33
-
34
- ## Features
35
-
36
- ### Live Options Screener
37
-
38
- Filter and rank symbols in real time across your universe by gamma exposure,
39
- VRP, implied volatility, greeks, harvest scores, dealer flow risk, and custom
40
- formulas. Data is live from an in-memory store refreshed every 5-10 seconds.
41
-
42
- ```python
43
- # Harvestable VRP setups with low dealer flow risk
44
- result = fa.screener(
45
- filters={
46
- "op": "and",
47
- "conditions": [
48
- {"field": "regime", "operator": "eq", "value": "positive_gamma"},
49
- {"field": "vrp_regime", "operator": "eq", "value": "harvestable"},
50
- {"field": "dealer_flow_risk", "operator": "lte", "value": 40},
51
- {"field": "harvest_score", "operator": "gte", "value": 65},
52
- ],
53
- },
54
- sort=[{"field": "harvest_score", "direction": "desc"}],
55
- select=["symbol", "price", "harvest_score", "dealer_flow_risk"],
56
- )
57
- for row in result["data"]:
58
- print(f"{row['symbol']}: score={row['harvest_score']} risk={row['dealer_flow_risk']}")
59
-
60
- # Custom formula — rank by IV premium over realized vol
61
- result = fa.screener(
62
- formulas=[{"alias": "iv_premium", "expression": "atm_iv - rv_20d"}],
63
- sort=[{"formula": "iv_premium", "direction": "desc"}],
64
- select=["symbol", "atm_iv", "rv_20d", "iv_premium"],
65
- limit=20,
66
- )
67
- ```
68
-
69
- Cascading filters on expiries, strikes, and contracts (e.g. `expiries.days_to_expiry`,
70
- `strikes.call_oi`, `contracts.delta`) trim the tree at each level and return only the
71
- matching subtree. See the [Screener spec](https://flashalpha.com/docs/lab-api-screener)
72
- and [cookbook](https://flashalpha.com/docs/lab-api-screener-cookbook) for all fields,
73
- operators, and recipes.
74
-
75
- ### Options Exposure Analytics
76
-
77
- Gamma exposure, delta exposure, vanna exposure, and charm exposure by strike. See where dealers are positioned and how they need to hedge.
78
-
79
- ```python
80
- gex = fa.gex("SPY") # Gamma exposure
81
- dex = fa.dex("AAPL") # Delta exposure
82
- vex = fa.vex("QQQ") # Vanna exposure
83
- chex = fa.chex("NVDA") # Charm exposure
84
-
85
- levels = fa.exposure_levels("SPY") # Key levels
86
- print(f"Call wall: {levels['levels']['call_wall']}")
87
- print(f"Put wall: {levels['levels']['put_wall']}")
88
- print(f"Gamma flip: {levels['levels']['gamma_flip']}")
89
-
90
- summary = fa.exposure_summary("SPY") # Full summary (Growth+)
91
- narrative = fa.narrative("SPY") # AI narrative (Growth+)
92
- print(narrative["narrative"]["outlook"])
93
- ```
94
-
95
- ### 0DTE Analytics
96
-
97
- Real-time zero-days-to-expiration analysis: gamma regime, expected move, pin risk scoring, dealer hedging estimates, theta decay acceleration, and per-strike breakdown.
98
-
99
- ```python
100
- dte = fa.zero_dte("SPY") # Growth+
101
- print(f"Pin score: {dte['pin_risk']['pin_score']}/100")
102
- print(f"Expected move: ±{dte['expected_move']['remaining_1sd_pct']:.2f}%")
103
- print(f"Theta/hr: ${dte['decay']['theta_per_hour_remaining']:,.0f}")
104
- print(f"Gamma acceleration: {dte['decay']['gamma_acceleration']}x vs 7DTE")
105
- ```
106
-
107
- ### Black-Scholes Greeks and Implied Volatility
108
-
109
- Full BSM greeks — first order (delta, gamma, theta, vega, rho), second order (vanna, charm, vomma), and third order (speed, zomma, color, ultima).
110
-
111
- ```python
112
- g = fa.greeks(spot=580, strike=580, dte=30, sigma=0.18, type="call")
113
- print(f"Delta: {g['first_order']['delta']}")
114
- print(f"Vanna: {g['second_order']['vanna']}")
115
- print(f"Speed: {g['third_order']['speed']}")
116
-
117
- iv = fa.iv(spot=580, strike=580, dte=30, price=12.69)
118
- print(f"IV: {iv['implied_volatility_pct']}%")
119
- ```
120
-
121
- ### Volatility Analytics
122
-
123
- Realized vol, IV-RV spreads, skew profiles, term structure, GEX by DTE, theta decay, put/call breakdowns, OI concentration, hedging scenarios, and liquidity analysis.
124
-
125
- ```python
126
- vol = fa.volatility("TSLA") # Growth+
127
- print(f"ATM IV: {vol['atm_iv']}%")
128
- print(f"RV 20d: {vol['realized_vol']['rv_20d']}%")
129
- print(f"VRP: {vol['iv_rv_spreads']['assessment']}")
130
- print(f"Skew 25d: {vol['skew_profiles'][0]['skew_25d']}")
131
- ```
132
-
133
- ### Advanced Volatility (SVI, Variance Surfaces, Arbitrage Detection)
134
-
135
- Raw SVI parameters per expiry, total variance surface grids, butterfly and calendar arbitrage flags, higher-order greeks surfaces (vanna, charm, volga, speed), and variance swap fair values.
136
-
137
- ```python
138
- adv = fa.adv_volatility("SPY") # Alpha+
139
- print(f"SVI params: {adv['svi_parameters'][0]}")
140
- print(f"Arbitrage flags: {len(adv['arbitrage_flags'])}")
141
- print(f"Var swap fair vol: {adv['variance_swap_fair_values'][0]['fair_vol']}%")
142
- ```
143
-
144
- ### Strategy Signals (decision envelope)
145
-
146
- Ten decision-support endpoints that score a single trading idea 0-100, classify a regime, and return ranked tradeable structures (legs, credit/debit, breakevens) in one uniform `StrategyDecisionResponse`: flow anomaly, expiry positioning, 0DTE range compression, dealer gamma regime, vol-carry (VRP), yield enhancement (covered call / cash-secured put), surface anomaly, skew, term structure, and tail pricing.
147
-
148
- ```python
149
- carry = fa.strategy_vol_carry("SPY", target_short_delta=0.20) # Alpha+
150
- print(carry["decision"], carry["score"], carry["regime"])
151
- for s in carry["best_structures"]:
152
- print(s["structure"], s["expiry"], s.get("credit"))
153
- ```
154
-
155
- ### Earnings Analytics
156
-
157
- Earnings calendar, implied-move decomposition (earnings jump vs baseline diffusion), historical earnings surprises and realized moves, expected IV crush and its historical distribution, earnings VRP richness, dealer positioning into the event, strategy-suitability scores, and a cross-sectional earnings screener.
158
-
159
- ```python
160
- em = fa.earnings_expected_move("AAPL") # Growth+
161
- print(em["earnings_date"], em.get("implied_move_pct"))
162
- events = fa.earnings_screener(sort="vrp_richest", days=14) # Alpha+
163
- ```
164
-
165
- ### Multi-Leg Structures (pure math)
166
-
167
- Deterministic at-expiry P&L diagrams, breakevens, and aggregate Black-Scholes greeks for arbitrary multi-leg option structures — no market-data lookup, you supply the legs.
168
-
169
- ```python
170
- pnl = fa.structure_pnl( # Basic+
171
- legs=[
172
- {"action": "buy", "type": "call", "strike": 100, "premium": 3.20},
173
- {"action": "sell", "type": "call", "strike": 110, "premium": 1.10},
174
- ],
175
- )
176
- print(pnl["max_profit"], pnl["max_loss"], pnl["breakevens"])
177
- ```
178
-
179
- ### Zero-DTE Flow, Dispersion & Macro
180
-
181
- Intraday simulation-aware 0DTE flow (snapshot, series, dealer hedge-flow, per-strike heatmap and strike-flow), full-tape Net Dealer Premium, multi-resolution OHLCV+flow bars, implied-vs-realized correlation for dispersion / vol-arb, VIX-state over/under-vixing regime, liquidity scores, skew term structure, spot-vol correlation, expected move, VRP history, and the curated symbol universe.
182
-
183
- ```python
184
- snap = fa.flow_zero_dte_snapshot("SPY") # Growth+
185
- disp = fa.dispersion(index="SPX", symbols=["AAPL", "MSFT", "NVDA"]) # Alpha+
186
- vix = fa.vix_state() # Growth+
187
- ```
188
-
189
- ### Kelly Criterion Position Sizing
190
-
191
- Optimal position sizing using numerical integration over the full lognormal distribution — not the simplified gambling formula.
192
-
193
- ```python
194
- kelly = fa.kelly( # Growth+
195
- spot=580, strike=580, dte=30,
196
- sigma=0.18, premium=12.69, mu=0.12,
197
- )
198
- print(kelly["recommendation"])
199
- print(f"Half-Kelly: {kelly['sizing']['half_kelly_pct']}%")
200
- ```
201
-
202
- ### Market Data
203
-
204
- ```python
205
- quote = fa.stock_quote("AAPL") # Live stock quote
206
- opt = fa.option_quote("SPY", expiry="2026-03-21", # Option quote (Growth+)
207
- strike=660, type="C")
208
- summary = fa.stock_summary("SPY") # Comprehensive summary
209
- surface = fa.surface("SPY") # Vol surface (public)
210
- ```
211
-
212
- ### Historical Data (QuestDB)
213
-
214
- Minute-by-minute stock and option quotes from QuestDB — 3.5 billion rows across 141 tickers.
215
-
216
- ```python
217
- hist = fa.historical_stock_quote("SPY", date="2026-03-05", time="10:30")
218
- hist_opt = fa.historical_option_quote(
219
- "SPY", date="2026-03-05", expiry="2026-03-20", strike=580, type="C"
220
- )
221
- ```
222
-
223
- ### Reference Data and Account
224
-
225
- ```python
226
- tickers = fa.tickers() # All available stock tickers
227
- chain = fa.options("SPY") # Option chain metadata
228
- symbols = fa.symbols() # Symbols with live cached data
229
- account = fa.account() # Plan, usage, quota
230
- health = fa.health() # API health check (public)
231
- ```
232
-
233
- ## Error Handling
234
-
235
- ```python
236
- from flashalpha import (
237
- FlashAlpha,
238
- AuthenticationError,
239
- TierRestrictedError,
240
- NotFoundError,
241
- RateLimitError,
242
- )
243
-
244
- fa = FlashAlpha("YOUR_API_KEY")
245
-
246
- try:
247
- data = fa.exposure_summary("SPY")
248
- except AuthenticationError:
249
- print("Invalid API key")
250
- except TierRestrictedError as e:
251
- print(f"Need {e.required_plan} plan (you have {e.current_plan})")
252
- except NotFoundError:
253
- print("Symbol not found")
254
- except RateLimitError as e:
255
- print(f"Rate limited — retry after {e.retry_after}s")
256
- ```
257
-
258
- ## API Plans
259
-
260
- | Plan | Daily Requests | Access |
261
- |------|---------------|--------|
262
- | **Free** | 5 | Stock quotes, single-expiry GEX (equities), key levels, BSM greeks, IV, IV surface, stock summary, historical quotes, tickers, options meta |
263
- | **Basic** | 250 | + DEX/VEX/CHEX by strike, max pain, ETF & index symbols (SPX, VIX, RUT, etc.) |
264
- | **Growth** | 2,500 | + Exposure summary, narrative, 0DTE analytics, volatility analytics, option quotes, full-chain GEX, Kelly sizing |
265
- | **Alpha** | Unlimited | + Advanced volatility (SVI, variance surfaces, arbitrage detection, greeks surfaces, variance swap) |
266
-
267
- Get your API key at **[flashalpha.com](https://flashalpha.com)**
268
-
269
- ## All Methods
270
-
271
- | Method | Endpoint | Plan |
272
- |--------|----------|------|
273
- | `fa.gex(symbol)` | Gamma exposure by strike | Free+ |
274
- | `fa.dex(symbol)` | Delta exposure by strike | Basic+ |
275
- | `fa.vex(symbol)` | Vanna exposure by strike | Basic+ |
276
- | `fa.chex(symbol)` | Charm exposure by strike | Basic+ |
277
- | `fa.exposure_levels(symbol)` | Key levels (gamma flip, walls, max pain) | Free+ |
278
- | `fa.exposure_summary(symbol)` | Full exposure summary with hedging | Growth+ |
279
- | `fa.narrative(symbol)` | AI narrative analysis | Growth+ |
280
- | `fa.zero_dte(symbol)` | 0DTE analytics (regime, pin risk, decay) | Growth+ |
281
- | `fa.stock_quote(ticker)` | Live stock quote | Free+ |
282
- | `fa.option_quote(ticker)` | Option quotes with greeks | Growth+ |
283
- | `fa.stock_summary(symbol)` | Comprehensive stock summary | Public/Free+ |
284
- | `fa.surface(symbol)` | Volatility surface grid | Public |
285
- | `fa.historical_stock_quote(ticker)` | Historical stock quotes | Free+ |
286
- | `fa.historical_option_quote(ticker)` | Historical option quotes | Free+ |
287
- | `fa.greeks(...)` | BSM greeks (1st, 2nd, 3rd order) | Free+ |
288
- | `fa.iv(...)` | Implied volatility solver | Free+ |
289
- | `fa.kelly(...)` | Kelly criterion sizing | Growth+ |
290
- | `fa.max_pain(symbol)` | Max pain analysis with dealer alignment, pain curve, pin probability | Basic+ |
291
- | `fa.screener(...)` | **Live options screener** — filter/rank by GEX, VRP, IV, greeks, formulas | Growth+ |
292
- | `fa.volatility(symbol)` | Comprehensive volatility analytics | Growth+ |
293
- | `fa.adv_volatility(symbol)` | SVI, variance surface, arb detection | Alpha+ |
294
- | `fa.tickers()` | All available stock tickers | Free+ |
295
- | `fa.options(ticker)` | Option chain metadata | Free+ |
296
- | `fa.symbols()` | Symbols with live data | Free+ |
297
- | `fa.account()` | Account info and quota | Free+ |
298
- | `fa.health()` | Health check | Public |
299
- | `fa.surface_svi(symbol)` | Live SVI surface params per expiry slice | Alpha+ |
300
- | `fa.exposure_sheet(symbol)` | Unified per-strike GEX/DEX/VEX/CHEX/DAG + Line-in-the-Sand + peaks | Growth+ |
301
- | `fa.exposure_term_structure(symbol)` | Exposure aggregated by DTE bucket and expiry | Growth+ |
302
- | `fa.exposure_basket(symbols)` | Weighted cross-symbol exposure aggregate | Growth+ |
303
- | `fa.exposure_oi_diff(symbol)` | Day-over-day open-interest deltas, top-N | Growth+ |
304
- | `fa.liquidity(symbol)` | Per-expiry execution score and bid-ask spreads | Growth+ |
305
- | `fa.skew_term(symbol)` | 25-delta skew and risk-reversal term structure | Growth+ |
306
- | `fa.spot_vol_correlation(symbol)` | Spot-vol correlation (20d/60d) | Growth+ |
307
- | `fa.dispersion(index, symbols, ...)` | Implied-vs-realized correlation / dispersion vol-arb | Alpha+ |
308
- | `fa.expected_move(symbol)` | Straddle-implied expected move per expiry | Basic+ |
309
- | `fa.realized_volatility(symbol)` | Range-based realized vol estimators (10d/20d/30d) | Alpha+ |
310
- | `fa.volatility_forecast(symbol, dist=...)` | Conditional vol forecasts (EWMA / HAR-RV / GARCH) | Alpha+ |
311
- | `fa.vrp_history(symbol)` | Daily VRP time series for charting/backtesting | Alpha+ |
312
- | `fa.vix_state()` | Over/under-vixing regime (VIX vs SPX realized vol) | Growth+ |
313
- | `fa.universe(...)` | Curated tier-1/tier-2 symbol directory | Public |
314
- | `fa.screener_fields()` | List screener-referenceable fields and types | Free+ |
315
- | `fa.flow_dealer_premium(symbol)` | Full-tape Net Dealer Premium roll-up | Alpha+ |
316
- | `fa.flow_stock_bars(symbol, resolution=...)` | Multi-resolution OHLCV+flow bars | Alpha+ |
317
- | `fa.flow_zero_dte_snapshot(symbol)` | Live intraday 0DTE shape + flow direction | Growth+ |
318
- | `fa.flow_zero_dte_series(symbol)` | Intraday 0DTE metric time series | Growth+ |
319
- | `fa.flow_zero_dte_hedge_flow(symbol)` | Dealer hedge-flow time series (0DTE) | Growth+ |
320
- | `fa.flow_zero_dte_heatmap(symbol)` | Per-strike 0DTE intraday heatmap | Alpha+ |
321
- | `fa.flow_zero_dte_strike_flow(symbol)` | Per-strike signed aggressor 0DTE flow | Alpha+ |
322
- | `fa.flow_zero_dte_leaderboard()` | Cross-symbol 0DTE leaderboard | Alpha+ |
323
- | `fa.strategy_flow_anomaly(symbol)` | Strategy signal: directional flow imbalance | Growth+ |
324
- | `fa.strategy_expiry_positioning(symbol)` | Strategy signal: OPEX pin / iron fly | Basic+ |
325
- | `fa.strategy_zero_dte(symbol)` | Strategy signal: same-day 0DTE range compression | Growth+ (+0DTE) |
326
- | `fa.strategy_dealer_regime(symbol)` | Strategy signal: dealer gamma regime | Growth+ |
327
- | `fa.strategy_vol_carry(symbol)` | Strategy signal: VRP carry / short vol | Alpha+ |
328
- | `fa.strategy_yield_enhancement(symbol)` | Strategy signal: covered call / cash-secured put | Growth+ |
329
- | `fa.strategy_surface_anomaly(symbol)` | Strategy signal: rich/cheap wings vs SVI fit | Alpha+ |
330
- | `fa.strategy_skew(symbol)` | Strategy signal: skew richness | Growth+ |
331
- | `fa.strategy_term_structure(symbol)` | Strategy signal: IV term-structure slope | Growth+ |
332
- | `fa.strategy_tail_pricing(symbol)` | Strategy signal: tail (deep-wing) pricing | Growth+ |
333
- | `fa.earnings_calendar(...)` | Upcoming earnings calendar | Growth+ |
334
- | `fa.earnings_expected_move(symbol)` | Earnings implied-move decomposition | Growth+ |
335
- | `fa.earnings_history(symbol)` | Past earnings: surprises, moves, IV crush | Growth+ |
336
- | `fa.earnings_iv_crush(symbol)` | Expected IV crush + historical distribution | Growth+ |
337
- | `fa.earnings_vrp(symbol)` | Earnings VRP richness assessment | Alpha+ |
338
- | `fa.earnings_dealer_positioning(symbol)` | Dealer positioning into the earnings event | Alpha+ |
339
- | `fa.earnings_strategies(symbol)` | Earnings strategy-suitability scores | Alpha+ |
340
- | `fa.earnings_screener(...)` | Cross-sectional earnings screener | Alpha+ |
341
- | `fa.structure_pnl(legs, ...)` | Multi-leg at-expiry P&L, breakevens, max P/L | Basic+ |
342
- | `fa.structure_greeks(legs, spot=...)` | Aggregate multi-leg Black-Scholes greeks | Basic+ |
343
-
344
- ## Futures (CME equity-index)
345
-
346
- FlashAlpha serves the full options-analytics stack for **CME equity-index futures** — **`ES=F`** (E-mini S&P 500) and **`NQ=F`** (E-mini Nasdaq-100). Options-on-futures are priced with **Black-76** (forward-priced) using the correct CME contract multipliers. Everything that works for an equity works for futures: gamma exposure (GEX), DEX, VEX, CHEX, key levels, max pain, the IV surface, exposure summary, narrative, and live flow.
347
-
348
- ```python
349
- gex = fa.gex("ES=F") # Gamma exposure for the E-mini S&P 500 future
350
- print(f"Net GEX: ${gex['net_gex']:,.0f}")
351
- ```
352
-
353
- Use the `=F` suffix — bare `ES`/`NQ` are equities, not futures. In raw REST paths URL-encode the `=` as `%3D` (e.g. `GET /v1/exposure/gex/ES%3DF`); SDK methods take the plain string `"ES=F"`. Historical replay for futures is coming; live analytics are available now.
354
-
355
- ## Other SDKs
356
-
357
- | Language | Package | Repository |
358
- |----------|---------|------------|
359
- | JavaScript | `npm i flashalpha` | [flashalpha-js](https://github.com/FlashAlpha-lab/flashalpha-js) |
360
- | .NET | `dotnet add package FlashAlpha` | [flashalpha-dotnet](https://github.com/FlashAlpha-lab/flashalpha-dotnet) |
361
- | Java | Maven Central | [flashalpha-java](https://github.com/FlashAlpha-lab/flashalpha-java) |
362
- | Go | `go get github.com/FlashAlpha-lab/flashalpha-go` | [flashalpha-go](https://github.com/FlashAlpha-lab/flashalpha-go) |
363
- | MCP | Claude / LLM tool server | [flashalpha-mcp](https://github.com/FlashAlpha-lab/flashalpha-mcp) |
364
-
365
- ## Links
366
-
367
- - [FlashAlpha](https://flashalpha.com) — API keys, docs, pricing
368
- - [API Documentation](https://flashalpha.com/docs)
369
- - [Examples](https://github.com/FlashAlpha-lab/flashalpha-examples) — runnable tutorials
370
- - [GEX Explained](https://github.com/FlashAlpha-lab/gex-explained) — gamma exposure theory and code
371
- - [0DTE Options Analytics](https://github.com/FlashAlpha-lab/0dte-options-analytics) — 0DTE pin risk, expected move, dealer hedging
372
- - [Volatility Surface Python](https://github.com/FlashAlpha-lab/volatility-surface-python) — SVI calibration, variance swap, skew analysis
373
- - [Awesome Options Analytics](https://github.com/FlashAlpha-lab/awesome-options-analytics) — curated resource list
374
-
375
- ## License
376
-
377
- MIT
378
-
379
- ## What the paid tiers unlock
380
-
381
- The free tier covers single-expiry GEX on equities, key levels, the BSM Greeks/IV
382
- calculator and stock quotes. Paid tiers add:
383
-
384
- - **DEX, VEX (vanna) and CHEX (charm) exposure, plus max pain** — from the **Basic tier**
385
- ($79/mo), with ETF and index symbols.
386
- - **Full-chain GEX, 0DTE and flow analytics** — from the **Growth tier** ($299/mo).
387
- - **Point-in-time replay since 2018, SVI vol surfaces, VRP analytics, higher-order Greeks**,
388
- uncached and unlimited — the **Alpha tier** ($1,499/mo). FlashAlpha is one of the only
389
- public APIs publishing aggregate vanna and charm exposure across the full universe, with
390
- no look-ahead and no training-serving skew.
391
-
392
- Built for quants, prop desks, and vol funds. See the full picture and get a key:
393
- **[flashalpha.com/for-quant-teams](https://flashalpha.com/for-quant-teams?utm_source=github&utm_medium=readme&utm_campaign=repo-flashalpha-python)**
1
+ # FlashAlpha Python SDK
2
+
3
+ [![PyPI](https://img.shields.io/pypi/v/flashalpha)](https://pypi.org/project/flashalpha/)
4
+ [![Python](https://img.shields.io/pypi/pyversions/flashalpha)](https://pypi.org/project/flashalpha/)
5
+ [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
6
+ [![CI](https://github.com/FlashAlpha-lab/flashalpha-python/actions/workflows/ci.yml/badge.svg)](https://github.com/FlashAlpha-lab/flashalpha-python/actions/workflows/ci.yml)
7
+
8
+ Python client for the [FlashAlpha options analytics API](https://flashalpha.com). Access a **live options screener** (filter/rank symbols by gamma exposure, VRP, IV, greeks, harvest scores, and custom formulas), real-time gamma exposure (GEX), delta exposure (DEX), vanna exposure (VEX), charm exposure (CHEX), 0DTE analytics, Black-Scholes greeks, implied volatility, volatility surfaces, dealer positioning, Kelly criterion sizing, and more — all from Python.
9
+
10
+ > 🔑 **[Get a free API key at flashalpha.com →](https://flashalpha.com)** · 📚 [API documentation](https://flashalpha.com/docs) · 💹 [FlashAlpha options analytics API](https://flashalpha.com)
11
+
12
+ ```bash
13
+ pip install flashalpha
14
+ ```
15
+
16
+ ## Quick Start
17
+
18
+ ```python
19
+ from flashalpha import FlashAlpha
20
+
21
+ fa = FlashAlpha("YOUR_API_KEY") # Get a free key at flashalpha.com
22
+
23
+ # Gamma exposure by strike
24
+ gex = fa.gex("SPY")
25
+ print(f"Net GEX: ${gex['net_gex']:,.0f}")
26
+ print(f"Gamma flip: {gex['gamma_flip']}")
27
+
28
+ for strike in gex["strikes"][:5]:
29
+ print(f" {strike['strike']}: net ${strike['net_gex']:,.0f}")
30
+ ```
31
+
32
+ Get your free API key at [flashalpha.com](https://flashalpha.com) — no credit card required.
33
+
34
+ ## Features
35
+
36
+ ### Live Options Screener
37
+
38
+ Filter and rank symbols in real time across your universe by gamma exposure,
39
+ VRP, implied volatility, greeks, harvest scores, dealer flow risk, and custom
40
+ formulas. Data is live from an in-memory store refreshed every 5-10 seconds.
41
+
42
+ ```python
43
+ # Harvestable VRP setups with low dealer flow risk
44
+ result = fa.screener(
45
+ filters={
46
+ "op": "and",
47
+ "conditions": [
48
+ {"field": "regime", "operator": "eq", "value": "positive_gamma"},
49
+ {"field": "vrp_regime", "operator": "eq", "value": "harvestable"},
50
+ {"field": "dealer_flow_risk", "operator": "lte", "value": 40},
51
+ {"field": "harvest_score", "operator": "gte", "value": 65},
52
+ ],
53
+ },
54
+ sort=[{"field": "harvest_score", "direction": "desc"}],
55
+ select=["symbol", "price", "harvest_score", "dealer_flow_risk"],
56
+ )
57
+ for row in result["data"]:
58
+ print(f"{row['symbol']}: score={row['harvest_score']} risk={row['dealer_flow_risk']}")
59
+
60
+ # Custom formula — rank by IV premium over realized vol
61
+ result = fa.screener(
62
+ formulas=[{"alias": "iv_premium", "expression": "atm_iv - rv_20d"}],
63
+ sort=[{"formula": "iv_premium", "direction": "desc"}],
64
+ select=["symbol", "atm_iv", "rv_20d", "iv_premium"],
65
+ limit=20,
66
+ )
67
+ ```
68
+
69
+ Cascading filters on expiries, strikes, and contracts (e.g. `expiries.days_to_expiry`,
70
+ `strikes.call_oi`, `contracts.delta`) trim the tree at each level and return only the
71
+ matching subtree. See the [Screener spec](https://flashalpha.com/docs/lab-api-screener)
72
+ and [cookbook](https://flashalpha.com/docs/lab-api-screener-cookbook) for all fields,
73
+ operators, and recipes.
74
+
75
+ ### Options Exposure Analytics
76
+
77
+ Gamma exposure, delta exposure, vanna exposure, and charm exposure by strike. See where dealers are positioned and how they need to hedge.
78
+
79
+ ```python
80
+ gex = fa.gex("SPY") # Gamma exposure
81
+ dex = fa.dex("AAPL") # Delta exposure
82
+ vex = fa.vex("QQQ") # Vanna exposure
83
+ chex = fa.chex("NVDA") # Charm exposure
84
+
85
+ levels = fa.exposure_levels("SPY") # Key levels
86
+ print(f"Call wall: {levels['levels']['call_wall']}")
87
+ print(f"Put wall: {levels['levels']['put_wall']}")
88
+ print(f"Gamma flip: {levels['levels']['gamma_flip']}")
89
+
90
+ summary = fa.exposure_summary("SPY") # Full summary (Growth+)
91
+ narrative = fa.narrative("SPY") # AI narrative (Growth+)
92
+ print(narrative["narrative"]["outlook"])
93
+ ```
94
+
95
+ ### 0DTE Analytics
96
+
97
+ Real-time zero-days-to-expiration analysis: gamma regime, expected move, pin risk scoring, dealer hedging estimates, theta decay acceleration, and per-strike breakdown.
98
+
99
+ ```python
100
+ dte = fa.zero_dte("SPY") # Growth+
101
+ print(f"Pin score: {dte['pin_risk']['pin_score']}/100")
102
+ print(f"Expected move: ±{dte['expected_move']['remaining_1sd_pct']:.2f}%")
103
+ print(f"Theta/hr: ${dte['decay']['theta_per_hour_remaining']:,.0f}")
104
+ print(f"Gamma acceleration: {dte['decay']['gamma_acceleration']}x vs 7DTE")
105
+ ```
106
+
107
+ ### Black-Scholes Greeks and Implied Volatility
108
+
109
+ Full BSM greeks — first order (delta, gamma, theta, vega, rho), second order (vanna, charm, vomma), and third order (speed, zomma, color, ultima).
110
+
111
+ ```python
112
+ g = fa.greeks(spot=580, strike=580, dte=30, sigma=0.18, type="call")
113
+ print(f"Delta: {g['first_order']['delta']}")
114
+ print(f"Vanna: {g['second_order']['vanna']}")
115
+ print(f"Speed: {g['third_order']['speed']}")
116
+
117
+ iv = fa.iv(spot=580, strike=580, dte=30, price=12.69)
118
+ print(f"IV: {iv['implied_volatility_pct']}%")
119
+ ```
120
+
121
+ ### Volatility Analytics
122
+
123
+ Realized vol, IV-RV spreads, skew profiles, term structure, GEX by DTE, theta decay, put/call breakdowns, OI concentration, hedging scenarios, and liquidity analysis.
124
+
125
+ ```python
126
+ vol = fa.volatility("TSLA") # Growth+
127
+ print(f"ATM IV: {vol['atm_iv']}%")
128
+ print(f"RV 20d: {vol['realized_vol']['rv_20d']}%")
129
+ print(f"VRP: {vol['iv_rv_spreads']['assessment']}")
130
+ print(f"Skew 25d: {vol['skew_profiles'][0]['skew_25d']}")
131
+ ```
132
+
133
+ ### Advanced Volatility (SVI, Variance Surfaces, Arbitrage Detection)
134
+
135
+ Raw SVI parameters per expiry, total variance surface grids, butterfly and calendar arbitrage flags, higher-order greeks surfaces (vanna, charm, volga, speed), and variance swap fair values.
136
+
137
+ ```python
138
+ adv = fa.adv_volatility("SPY") # Alpha+
139
+ print(f"SVI params: {adv['svi_parameters'][0]}")
140
+ print(f"Arbitrage flags: {len(adv['arbitrage_flags'])}")
141
+ print(f"Var swap fair vol: {adv['variance_swap_fair_values'][0]['fair_vol']}%")
142
+ ```
143
+
144
+ ### Strategy Signals (decision envelope)
145
+
146
+ Ten decision-support endpoints that score a single trading idea 0-100, classify a regime, and return ranked tradeable structures (legs, credit/debit, breakevens) in one uniform `StrategyDecisionResponse`: flow anomaly, expiry positioning, 0DTE range compression, dealer gamma regime, vol-carry (VRP), yield enhancement (covered call / cash-secured put), surface anomaly, skew, term structure, and tail pricing.
147
+
148
+ ```python
149
+ carry = fa.strategy_vol_carry("SPY", target_short_delta=0.20) # Alpha+
150
+ print(carry["decision"], carry["score"], carry["regime"])
151
+ for s in carry["best_structures"]:
152
+ print(s["structure"], s["expiry"], s.get("credit"))
153
+ ```
154
+
155
+ ### Earnings Analytics
156
+
157
+ Earnings calendar, implied-move decomposition (earnings jump vs baseline diffusion), historical earnings surprises and realized moves, expected IV crush and its historical distribution, earnings VRP richness, dealer positioning into the event, strategy-suitability scores, and a cross-sectional earnings screener.
158
+
159
+ ```python
160
+ em = fa.earnings_expected_move("AAPL") # Growth+
161
+ print(em["earnings_date"], em.get("implied_move_pct"))
162
+ events = fa.earnings_screener(sort="vrp_richest", days=14) # Alpha+
163
+ ```
164
+
165
+ ### Multi-Leg Structures (pure math)
166
+
167
+ Deterministic at-expiry P&L diagrams, breakevens, and aggregate Black-Scholes greeks for arbitrary multi-leg option structures — no market-data lookup, you supply the legs.
168
+
169
+ ```python
170
+ pnl = fa.structure_pnl( # Basic+
171
+ legs=[
172
+ {"action": "buy", "type": "call", "strike": 100, "premium": 3.20},
173
+ {"action": "sell", "type": "call", "strike": 110, "premium": 1.10},
174
+ ],
175
+ )
176
+ print(pnl["max_profit"], pnl["max_loss"], pnl["breakevens"])
177
+ ```
178
+
179
+ ### Zero-DTE Flow, Dispersion & Macro
180
+
181
+ Intraday simulation-aware 0DTE flow (snapshot, series, dealer hedge-flow, per-strike heatmap and strike-flow), full-tape Net Dealer Premium, multi-resolution OHLCV+flow bars, implied-vs-realized correlation for dispersion / vol-arb, VIX-state over/under-vixing regime, liquidity scores, skew term structure, spot-vol correlation, expected move, VRP history, and the curated symbol universe.
182
+
183
+ ```python
184
+ snap = fa.flow_zero_dte_snapshot("SPY") # Growth+
185
+ disp = fa.dispersion(index="SPX", symbols=["AAPL", "MSFT", "NVDA"]) # Alpha+
186
+ vix = fa.vix_state() # Growth+
187
+ ```
188
+
189
+ ### Kelly Criterion Position Sizing
190
+
191
+ Optimal position sizing using numerical integration over the full lognormal distribution — not the simplified gambling formula.
192
+
193
+ ```python
194
+ kelly = fa.kelly( # Growth+
195
+ spot=580, strike=580, dte=30,
196
+ sigma=0.18, premium=12.69, mu=0.12,
197
+ )
198
+ print(kelly["recommendation"])
199
+ print(f"Half-Kelly: {kelly['sizing']['half_kelly_pct']}%")
200
+ ```
201
+
202
+ ### Market Data
203
+
204
+ ```python
205
+ quote = fa.stock_quote("AAPL") # Live stock quote
206
+ opt = fa.option_quote("SPY", expiry="2026-03-21", # Option quote (Growth+)
207
+ strike=660, type="C")
208
+ summary = fa.stock_summary("SPY") # Comprehensive summary
209
+ surface = fa.surface("SPY") # Vol surface (public)
210
+ ```
211
+
212
+ ### Historical Data (QuestDB)
213
+
214
+ Minute-by-minute stock and option quotes from QuestDB — 3.5 billion rows across 141 tickers.
215
+
216
+ ```python
217
+ hist = fa.historical_stock_quote("SPY", date="2026-03-05", time="10:30")
218
+ hist_opt = fa.historical_option_quote(
219
+ "SPY", date="2026-03-05", expiry="2026-03-20", strike=580, type="C"
220
+ )
221
+ ```
222
+
223
+ ### Reference Data and Account
224
+
225
+ ```python
226
+ tickers = fa.tickers() # All available stock tickers
227
+ chain = fa.options("SPY") # Option chain metadata
228
+ symbols = fa.symbols() # Symbols with live cached data
229
+ account = fa.account() # Plan, usage, quota
230
+ health = fa.health() # API health check (public)
231
+ ```
232
+
233
+ ## Error Handling
234
+
235
+ ```python
236
+ from flashalpha import (
237
+ FlashAlpha,
238
+ AuthenticationError,
239
+ TierRestrictedError,
240
+ NotFoundError,
241
+ RateLimitError,
242
+ )
243
+
244
+ fa = FlashAlpha("YOUR_API_KEY")
245
+
246
+ try:
247
+ data = fa.exposure_summary("SPY")
248
+ except AuthenticationError:
249
+ print("Invalid API key")
250
+ except TierRestrictedError as e:
251
+ print(f"Need {e.required_plan} plan (you have {e.current_plan})")
252
+ except NotFoundError:
253
+ print("Symbol not found")
254
+ except RateLimitError as e:
255
+ print(f"Rate limited — retry after {e.retry_after}s")
256
+ ```
257
+
258
+ ## API Plans
259
+
260
+ | Plan | Daily Requests | Access |
261
+ |------|---------------|--------|
262
+ | **Free** | 5 | Stock quotes, single-expiry GEX (equities), key levels, BSM greeks, IV, IV surface, stock summary, historical quotes, tickers, options meta |
263
+ | **Basic** | 250 | + DEX/VEX/CHEX by strike, max pain, ETF & index symbols (SPX, VIX, RUT, etc.) |
264
+ | **Growth** | 2,500 | + Exposure summary, narrative, 0DTE analytics, volatility analytics, option quotes, full-chain GEX, Kelly sizing |
265
+ | **Alpha** | Unlimited | + Advanced volatility (SVI, variance surfaces, arbitrage detection, greeks surfaces, variance swap) |
266
+
267
+ Get your API key at **[flashalpha.com](https://flashalpha.com)**
268
+
269
+ ## All Methods
270
+
271
+ | Method | Endpoint | Plan |
272
+ |--------|----------|------|
273
+ | `fa.gex(symbol)` | Gamma exposure by strike | Free+ |
274
+ | `fa.dex(symbol)` | Delta exposure by strike | Basic+ |
275
+ | `fa.vex(symbol)` | Vanna exposure by strike | Basic+ |
276
+ | `fa.chex(symbol)` | Charm exposure by strike | Basic+ |
277
+ | `fa.exposure_levels(symbol)` | Key levels (gamma flip, walls, max pain) | Free+ |
278
+ | `fa.exposure_summary(symbol)` | Full exposure summary with hedging | Growth+ |
279
+ | `fa.narrative(symbol)` | AI narrative analysis | Growth+ |
280
+ | `fa.zero_dte(symbol)` | 0DTE analytics (regime, pin risk, decay) | Growth+ |
281
+ | `fa.stock_quote(ticker)` | Live stock quote | Free+ |
282
+ | `fa.option_quote(ticker)` | Option quotes with greeks | Growth+ |
283
+ | `fa.stock_summary(symbol)` | Comprehensive stock summary | Public/Free+ |
284
+ | `fa.surface(symbol)` | Volatility surface grid | Public |
285
+ | `fa.historical_stock_quote(ticker)` | Historical stock quotes | Free+ |
286
+ | `fa.historical_option_quote(ticker)` | Historical option quotes | Free+ |
287
+ | `fa.greeks(...)` | BSM greeks (1st, 2nd, 3rd order) | Free+ |
288
+ | `fa.iv(...)` | Implied volatility solver | Free+ |
289
+ | `fa.kelly(...)` | Kelly criterion sizing | Growth+ |
290
+ | `fa.max_pain(symbol)` | Max pain analysis with dealer alignment, pain curve, pin probability | Basic+ |
291
+ | `fa.screener(...)` | **Live options screener** — filter/rank by GEX, VRP, IV, greeks, formulas | Growth+ |
292
+ | `fa.volatility(symbol)` | Comprehensive volatility analytics | Growth+ |
293
+ | `fa.adv_volatility(symbol)` | SVI, variance surface, arb detection | Alpha+ |
294
+ | `fa.tickers()` | All available stock tickers | Free+ |
295
+ | `fa.options(ticker)` | Option chain metadata | Free+ |
296
+ | `fa.symbols()` | Symbols with live data | Free+ |
297
+ | `fa.account()` | Account info and quota | Free+ |
298
+ | `fa.health()` | Health check | Public |
299
+ | `fa.surface_svi(symbol)` | Live SVI surface params per expiry slice | Alpha+ |
300
+ | `fa.exposure_sheet(symbol)` | Unified per-strike GEX/DEX/VEX/CHEX/DAG + Line-in-the-Sand + peaks | Growth+ |
301
+ | `fa.exposure_term_structure(symbol)` | Exposure aggregated by DTE bucket and expiry | Growth+ |
302
+ | `fa.exposure_basket(symbols)` | Weighted cross-symbol exposure aggregate | Growth+ |
303
+ | `fa.exposure_oi_diff(symbol)` | Day-over-day open-interest deltas, top-N | Growth+ |
304
+ | `fa.liquidity(symbol)` | Per-expiry execution score and bid-ask spreads | Growth+ |
305
+ | `fa.skew_term(symbol)` | 25-delta skew and risk-reversal term structure | Growth+ |
306
+ | `fa.spot_vol_correlation(symbol)` | Spot-vol correlation (20d/60d) | Growth+ |
307
+ | `fa.dispersion(index, symbols, ...)` | Implied-vs-realized correlation / dispersion vol-arb | Alpha+ |
308
+ | `fa.expected_move(symbol)` | Straddle-implied expected move per expiry | Basic+ |
309
+ | `fa.realized_volatility(symbol)` | Range-based realized vol estimators (10d/20d/30d) | Alpha+ |
310
+ | `fa.volatility_forecast(symbol, dist=...)` | Conditional vol forecasts (EWMA / HAR-RV / GARCH) | Alpha+ |
311
+ | `fa.vrp_history(symbol)` | Daily VRP time series for charting/backtesting | Alpha+ |
312
+ | `fa.vix_state()` | Over/under-vixing regime (VIX vs SPX realized vol) | Growth+ |
313
+ | `fa.universe(...)` | Curated tier-1/tier-2 symbol directory | Public |
314
+ | `fa.screener_fields()` | List screener-referenceable fields and types | Free+ |
315
+ | `fa.flow_dealer_premium(symbol)` | Full-tape Net Dealer Premium roll-up | Alpha+ |
316
+ | `fa.flow_stock_bars(symbol, resolution=...)` | Multi-resolution OHLCV+flow bars | Alpha+ |
317
+ | `fa.flow_zero_dte_snapshot(symbol)` | Live intraday 0DTE shape + flow direction | Growth+ |
318
+ | `fa.flow_zero_dte_series(symbol)` | Intraday 0DTE metric time series | Growth+ |
319
+ | `fa.flow_zero_dte_hedge_flow(symbol)` | Dealer hedge-flow time series (0DTE) | Growth+ |
320
+ | `fa.flow_zero_dte_heatmap(symbol)` | Per-strike 0DTE intraday heatmap | Alpha+ |
321
+ | `fa.flow_zero_dte_strike_flow(symbol)` | Per-strike signed aggressor 0DTE flow | Alpha+ |
322
+ | `fa.flow_zero_dte_leaderboard()` | Cross-symbol 0DTE leaderboard | Alpha+ |
323
+ | `fa.strategy_flow_anomaly(symbol)` | Strategy signal: directional flow imbalance | Growth+ |
324
+ | `fa.strategy_expiry_positioning(symbol)` | Strategy signal: OPEX pin / iron fly | Basic+ |
325
+ | `fa.strategy_zero_dte(symbol)` | Strategy signal: same-day 0DTE range compression | Growth+ (+0DTE) |
326
+ | `fa.strategy_dealer_regime(symbol)` | Strategy signal: dealer gamma regime | Growth+ |
327
+ | `fa.strategy_vol_carry(symbol)` | Strategy signal: VRP carry / short vol | Alpha+ |
328
+ | `fa.strategy_yield_enhancement(symbol)` | Strategy signal: covered call / cash-secured put | Growth+ |
329
+ | `fa.strategy_surface_anomaly(symbol)` | Strategy signal: rich/cheap wings vs SVI fit | Alpha+ |
330
+ | `fa.strategy_skew(symbol)` | Strategy signal: skew richness | Growth+ |
331
+ | `fa.strategy_term_structure(symbol)` | Strategy signal: IV term-structure slope | Growth+ |
332
+ | `fa.strategy_tail_pricing(symbol)` | Strategy signal: tail (deep-wing) pricing | Growth+ |
333
+ | `fa.earnings_calendar(...)` | Upcoming earnings calendar | Growth+ |
334
+ | `fa.earnings_expected_move(symbol)` | Earnings implied-move decomposition | Growth+ |
335
+ | `fa.earnings_history(symbol)` | Past earnings: surprises, moves, IV crush | Growth+ |
336
+ | `fa.earnings_iv_crush(symbol)` | Expected IV crush + historical distribution | Growth+ |
337
+ | `fa.earnings_vrp(symbol)` | Earnings VRP richness assessment | Alpha+ |
338
+ | `fa.earnings_dealer_positioning(symbol)` | Dealer positioning into the earnings event | Alpha+ |
339
+ | `fa.earnings_strategies(symbol)` | Earnings strategy-suitability scores | Alpha+ |
340
+ | `fa.earnings_screener(...)` | Cross-sectional earnings screener | Alpha+ |
341
+ | `fa.structure_pnl(legs, ...)` | Multi-leg at-expiry P&L, breakevens, max P/L | Basic+ |
342
+ | `fa.structure_greeks(legs, spot=...)` | Aggregate multi-leg Black-Scholes greeks | Basic+ |
343
+
344
+ ## Futures (CME)
345
+
346
+ FlashAlpha serves the full options-analytics stack for **CME futures** across six complexes - equity index (`ES=F`, `NQ=F`, `RTY=F`, `YM=F`, `MES=F`, `MNQ=F`), metals (`GC=F` gold, `SI=F` silver), energy (`CL=F` crude oil, `NG=F` natural gas), the Treasury curve (`ZT=F`, `ZF=F`, `ZN=F`, `TN=F`, `ZB=F`, `UB=F`), grains (`ZC=F` corn, `ZS=F` soybeans, `ZW=F` wheat) and crypto (`BTC=F` bitcoin). Options-on-futures are priced with **Black-76** (forward-priced) and each root carries its own CME contract multiplier, so notionals and dollar gamma are in real dollars. Note the quote conventions: Treasuries are quoted in points of par and grains in cents, so their multipliers are the contract size divided by 100. Everything that works for an equity works for futures: gamma exposure (GEX), DEX, VEX, CHEX, key levels, max pain, the IV surface, exposure summary, narrative, and live flow.
347
+
348
+ ```python
349
+ gex = fa.gex("ES=F") # Gamma exposure for the E-mini S&P 500 future
350
+ print(f"Net GEX: ${gex['net_gex']:,.0f}")
351
+ ```
352
+
353
+ Use the `=F` suffix - bare `ES`/`NQ` are equities, not futures. In raw REST paths URL-encode the `=` as `%3D` (e.g. `GET /v1/exposure/gex/GC%3DF`); SDK methods take the plain string `"GC=F"`. Futures symbols require the Growth plan or higher. Historical replay for futures is coming; live analytics are available now.
354
+
355
+ ## Other SDKs
356
+
357
+ | Language | Package | Repository |
358
+ |----------|---------|------------|
359
+ | JavaScript | `npm i flashalpha` | [flashalpha-js](https://github.com/FlashAlpha-lab/flashalpha-js) |
360
+ | .NET | `dotnet add package FlashAlpha` | [flashalpha-dotnet](https://github.com/FlashAlpha-lab/flashalpha-dotnet) |
361
+ | Java | Maven Central | [flashalpha-java](https://github.com/FlashAlpha-lab/flashalpha-java) |
362
+ | Go | `go get github.com/FlashAlpha-lab/flashalpha-go` | [flashalpha-go](https://github.com/FlashAlpha-lab/flashalpha-go) |
363
+ | MCP | Claude / LLM tool server | [flashalpha-mcp](https://github.com/FlashAlpha-lab/flashalpha-mcp) |
364
+
365
+ ## Links
366
+
367
+ - [FlashAlpha](https://flashalpha.com) — API keys, docs, pricing
368
+ - [API Documentation](https://flashalpha.com/docs)
369
+ - [Examples](https://github.com/FlashAlpha-lab/flashalpha-examples) — runnable tutorials
370
+ - [GEX Explained](https://github.com/FlashAlpha-lab/gex-explained) — gamma exposure theory and code
371
+ - [0DTE Options Analytics](https://github.com/FlashAlpha-lab/0dte-options-analytics) — 0DTE pin risk, expected move, dealer hedging
372
+ - [Volatility Surface Python](https://github.com/FlashAlpha-lab/volatility-surface-python) — SVI calibration, variance swap, skew analysis
373
+ - [Awesome Options Analytics](https://github.com/FlashAlpha-lab/awesome-options-analytics) — curated resource list
374
+
375
+ ## License
376
+
377
+ MIT
378
+
379
+ ## What the paid tiers unlock
380
+
381
+ The free tier covers single-expiry GEX on equities, key levels, the BSM Greeks/IV
382
+ calculator and stock quotes. Paid tiers add:
383
+
384
+ - **DEX, VEX (vanna) and CHEX (charm) exposure, plus max pain** — from the **Basic tier**
385
+ ($79/mo), with ETF and index symbols.
386
+ - **Full-chain GEX, 0DTE and flow analytics** — from the **Growth tier** ($299/mo).
387
+ - **Point-in-time replay since 2018, SVI vol surfaces, VRP analytics, higher-order Greeks**,
388
+ uncached and unlimited — the **Alpha tier** ($1,499/mo). FlashAlpha is one of the only
389
+ public APIs publishing aggregate vanna and charm exposure across the full universe, with
390
+ no look-ahead and no training-serving skew.
391
+
392
+ Built for quants, prop desks, and vol funds. See the full picture and get a key:
393
+ **[flashalpha.com/for-quant-teams](https://flashalpha.com/for-quant-teams?utm_source=github&utm_medium=readme&utm_campaign=repo-flashalpha-python)**
{flashalpha-1.2.2 → flashalpha-1.2.3}/pyproject.toml RENAMED
@@ -1,99 +1,99 @@
1
- [build-system]
2
- requires = ["hatchling"]
3
- build-backend = "hatchling.build"
4
-
5
- [project]
6
- name = "flashalpha"
7
- version = "1.2.2"
8
- description = "Python SDK for the FlashAlpha options analytics API — live options screener, gamma exposure (GEX), VRP, delta, vanna, charm, greeks, 0DTE analytics, volatility surfaces, and more."
9
- readme = "README.md"
10
- license = "MIT"
11
- requires-python = ">=3.10"
12
- authors = [{ name = "FlashAlpha", email = "tom@flashalpha.com" }]
13
- keywords = [
14
- "options",
15
- "options screener",
16
- "live options screener",
17
- "gamma exposure",
18
- "gex",
19
- "greeks",
20
- "options analytics",
21
- "options API",
22
- "delta exposure",
23
- "vanna",
24
- "charm",
25
- "implied volatility",
26
- "black-scholes",
27
- "trading",
28
- "finance",
29
- "quantitative finance",
30
- "0dte",
31
- "zero dte",
32
- "volatility surface",
33
- "options data",
34
- "dealer positioning",
35
- "kelly criterion",
36
- "vol surface",
37
- "SVI",
38
- "variance swap",
39
- "variance risk premium",
40
- "VRP",
41
- "harvest score",
42
- "short vol",
43
- "vol selling",
44
- "dealer flow",
45
- ]
46
- classifiers = [
47
- "Development Status :: 3 - Alpha",
48
- "Intended Audience :: Developers",
49
- "Intended Audience :: Financial and Insurance Industry",
50
- "License :: OSI Approved :: MIT License",
51
- "Programming Language :: Python :: 3",
52
- "Programming Language :: Python :: 3.10",
53
- "Programming Language :: Python :: 3.11",
54
- "Programming Language :: Python :: 3.12",
55
- "Programming Language :: Python :: 3.13",
56
- "Topic :: Office/Business :: Financial",
57
- "Topic :: Office/Business :: Financial :: Investment",
58
- "Topic :: Software Development :: Libraries :: Python Modules",
59
- ]
60
- dependencies = ["requests>=2.33.0"]
61
-
62
- [project.urls]
63
- Homepage = "https://flashalpha.com"
64
- Documentation = "https://flashalpha.com/docs"
65
- Repository = "https://github.com/FlashAlpha-lab/flashalpha-python"
66
- Issues = "https://github.com/FlashAlpha-lab/flashalpha-python/issues"
67
-
68
- [project.optional-dependencies]
69
- dev = ["pytest>=7.0", "pytest-cov", "responses>=0.23"]
70
-
71
- [tool.hatch.build.targets.wheel]
72
- packages = ["src/flashalpha"]
73
-
74
- [tool.hatch.build.targets.sdist]
75
- # Explicit allowlist — only ship source, README, LICENSE, pyproject. Anything
76
- # else in the working dir (e.g. .claude/, CLAUDE.md, .env*, dist/, tests/)
77
- # is excluded so the sdist stays minimal.
78
- support-legacy = false
79
- include = [
80
- "/src/flashalpha",
81
- "/README.md",
82
- "/LICENSE",
83
- "/pyproject.toml",
84
- ]
85
- exclude = [
86
- ".claude",
87
- "CLAUDE.md",
88
- ".env",
89
- ".env.*",
90
- ".gitignore",
91
- "**/.gitignore",
92
- ".vscode",
93
- ".idea",
94
- "*.local",
95
- ]
96
-
97
- [tool.pytest.ini_options]
98
- testpaths = ["tests"]
99
- markers = ["integration: hits the live FlashAlpha API (deselect with -m 'not integration')"]
1
+ [build-system]
2
+ requires = ["hatchling"]
3
+ build-backend = "hatchling.build"
4
+
5
+ [project]
6
+ name = "flashalpha"
7
+ version = "1.2.3"
8
+ description = "Python SDK for the FlashAlpha options analytics API — live options screener, gamma exposure (GEX), VRP, delta, vanna, charm, greeks, 0DTE analytics, volatility surfaces, and more."
9
+ readme = "README.md"
10
+ license = "MIT"
11
+ requires-python = ">=3.10"
12
+ authors = [{ name = "FlashAlpha", email = "tom@flashalpha.com" }]
13
+ keywords = [
14
+ "options",
15
+ "options screener",
16
+ "live options screener",
17
+ "gamma exposure",
18
+ "gex",
19
+ "greeks",
20
+ "options analytics",
21
+ "options API",
22
+ "delta exposure",
23
+ "vanna",
24
+ "charm",
25
+ "implied volatility",
26
+ "black-scholes",
27
+ "trading",
28
+ "finance",
29
+ "quantitative finance",
30
+ "0dte",
31
+ "zero dte",
32
+ "volatility surface",
33
+ "options data",
34
+ "dealer positioning",
35
+ "kelly criterion",
36
+ "vol surface",
37
+ "SVI",
38
+ "variance swap",
39
+ "variance risk premium",
40
+ "VRP",
41
+ "harvest score",
42
+ "short vol",
43
+ "vol selling",
44
+ "dealer flow",
45
+ ]
46
+ classifiers = [
47
+ "Development Status :: 3 - Alpha",
48
+ "Intended Audience :: Developers",
49
+ "Intended Audience :: Financial and Insurance Industry",
50
+ "License :: OSI Approved :: MIT License",
51
+ "Programming Language :: Python :: 3",
52
+ "Programming Language :: Python :: 3.10",
53
+ "Programming Language :: Python :: 3.11",
54
+ "Programming Language :: Python :: 3.12",
55
+ "Programming Language :: Python :: 3.13",
56
+ "Topic :: Office/Business :: Financial",
57
+ "Topic :: Office/Business :: Financial :: Investment",
58
+ "Topic :: Software Development :: Libraries :: Python Modules",
59
+ ]
60
+ dependencies = ["requests>=2.33.0"]
61
+
62
+ [project.urls]
63
+ Homepage = "https://flashalpha.com"
64
+ Documentation = "https://flashalpha.com/docs"
65
+ Repository = "https://github.com/FlashAlpha-lab/flashalpha-python"
66
+ Issues = "https://github.com/FlashAlpha-lab/flashalpha-python/issues"
67
+
68
+ [project.optional-dependencies]
69
+ dev = ["pytest>=7.0", "pytest-cov", "responses>=0.23"]
70
+
71
+ [tool.hatch.build.targets.wheel]
72
+ packages = ["src/flashalpha"]
73
+
74
+ [tool.hatch.build.targets.sdist]
75
+ # Explicit allowlist — only ship source, README, LICENSE, pyproject. Anything
76
+ # else in the working dir (e.g. .claude/, CLAUDE.md, .env*, dist/, tests/)
77
+ # is excluded so the sdist stays minimal.
78
+ support-legacy = false
79
+ include = [
80
+ "/src/flashalpha",
81
+ "/README.md",
82
+ "/LICENSE",
83
+ "/pyproject.toml",
84
+ ]
85
+ exclude = [
86
+ ".claude",
87
+ "CLAUDE.md",
88
+ ".env",
89
+ ".env.*",
90
+ ".gitignore",
91
+ "**/.gitignore",
92
+ ".vscode",
93
+ ".idea",
94
+ "*.local",
95
+ ]
96
+
97
+ [tool.pytest.ini_options]
98
+ testpaths = ["tests"]
99
+ markers = ["integration: hits the live FlashAlpha API (deselect with -m 'not integration')"]
{flashalpha-1.2.2 → flashalpha-1.2.3}/src/flashalpha/__init__.py RENAMED
@@ -276,7 +276,7 @@ from .types import (
276
276
  VrpHistoryResponse,
277
277
  )
278
278
 
279
- __version__ = "1.1.0"
279
+ __version__ = "1.2.3"
280
280
  __all__ = [
281
281
  "FlashAlpha",
282
282
  "FlashAlphaError",
{flashalpha-1.2.2 → flashalpha-1.2.3}/.gitignore RENAMED
File without changes
{flashalpha-1.2.2 → flashalpha-1.2.3}/LICENSE RENAMED
File without changes