flashalpha 1.3.0__tar.gz → 1.5.0__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.
@@ -1,7 +1,7 @@
1
1
  Metadata-Version: 2.5
2
2
  Name: flashalpha
3
- Version: 1.3.0
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.
3
+ Version: 1.5.0
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, the sell-window sell-or-skip call for option sellers, and more.
5
5
  Project-URL: Homepage, https://flashalpha.com
6
6
  Project-URL: Documentation, https://flashalpha.com/docs
7
7
  Project-URL: Repository, https://github.com/FlashAlpha-lab/flashalpha-python
@@ -9,7 +9,7 @@ Project-URL: Issues, https://github.com/FlashAlpha-lab/flashalpha-python/issues
9
9
  Author-email: FlashAlpha <tom@flashalpha.com>
10
10
  License-Expression: MIT
11
11
  License-File: LICENSE
12
- Keywords: 0dte,SVI,VRP,black-scholes,charm,dealer flow,dealer positioning,delta exposure,finance,gamma exposure,gex,greeks,harvest score,implied volatility,kelly criterion,live options screener,options,options API,options analytics,options data,options screener,quantitative finance,short vol,trading,vanna,variance risk premium,variance swap,vol selling,vol surface,volatility surface,zero dte
12
+ Keywords: 0dte,SVI,VRP,black-scholes,charm,dealer flow,dealer positioning,delta exposure,finance,gamma exposure,gex,greeks,harvest score,implied volatility,kelly criterion,live options screener,option selling,options,options API,options analytics,options data,options screener,premium selling,quantitative finance,sell-window,short premium,short vol,trading,vanna,variance risk premium,variance swap,vol selling,vol surface,volatility surface,when to sell options,zero dte
13
13
  Classifier: Development Status :: 3 - Alpha
14
14
  Classifier: Intended Audience :: Developers
15
15
  Classifier: Intended Audience :: Financial and Insurance Industry
@@ -74,6 +74,40 @@ Get your free API key at [flashalpha.com](https://flashalpha.com) — no credit
74
74
  > `gamma_flip_status == "available"` guarantees a number; treat any other value -
75
75
  > including codes added in future - as "no level published".
76
76
 
77
+ ## sell-window: should you sell options today?
78
+
79
+ Option sellers get wiped out on a few bad days. sell-window tells you which days to stay out, and on the days it says sell, it hands you the trades: which expiry, which strikes and how to exit. Every session, for SPY, QQQ and IWM. More than 5 million backtests led to this one endpoint.
80
+
81
+ ```python
82
+ from flashalpha import FlashAlpha
83
+
84
+ fa = FlashAlpha("YOUR_API_KEY")
85
+ answer = fa.sell_window("SPY")
86
+
87
+ for window in answer["windows"]:
88
+ print(window.get("expiry"), window["action"]) # sell, skip or unavailable
89
+ for trade in window.get("candidates", []):
90
+ print(" ", trade["structure"], trade.get("mid_credit"), trade["exit"])
91
+ ```
92
+
93
+ Each of the four windows (the same-day expiry, then the expiries closest to one week, two weeks and one month out) says `sell`, `skip` or `unavailable`. On a sell it lists the trades, with strikes, quotes and the exit rule. On a skip there is nothing to do.
94
+
95
+ | Backtest, 2018 to 2026 | Following sell-window | Selling the same trades every day |
96
+ |---|---|---|
97
+ | Max drawdown at the same trade size | $255k | $959k |
98
+ | Worst month at the same trade size | -$171k | -$307k |
99
+ | Sharpe ratio | 0.76 | 0.61 |
100
+ | Total P&L at the same max drawdown | $3.55M | $2.32M |
101
+ | Worst day at the same max drawdown | -$258k | -$385k |
102
+
103
+ Cut the risk or earn more. Keep your trade size and the deepest drawdown falls 73%. Or size up about 3.8 times, until the deepest drawdown matches, and you earn 53% more. These are two separate choices, not one result.
104
+
105
+ **Plans:** Live answers need Basic or higher through November 2026, and Growth or higher from December 1, 2026. Backtesting any past session needs Alpha or higher. Backtest with [flashalpha-historical-python](https://github.com/FlashAlpha-lab/flashalpha-historical-python).
106
+
107
+ **Read more:** [API docs](https://flashalpha.com/docs/lab-api-strategies-sell-window?utm_source=github&utm_medium=readme&utm_campaign=repo-flashalpha-python&utm_content=sell-window) | [trading guide](https://flashalpha.com/articles/complete-guide-trading-sell-window-spy-qqq-iwm?utm_source=github&utm_medium=readme&utm_campaign=repo-flashalpha-python&utm_content=sell-window) | [every backtested trade](https://flashalpha.com/articles/sell-window-backtest-every-trade-2018-2026?utm_source=github&utm_medium=readme&utm_campaign=repo-flashalpha-python&utm_content=sell-window) | [sell-window in depth](https://github.com/FlashAlpha-lab/flashalpha-python/blob/main/docs/sell-window.md) | [plans](https://flashalpha.com/pricing?utm_source=github&utm_medium=readme&utm_campaign=repo-flashalpha-python&utm_content=sell-window) | [live forward test on Discord](https://discord.gg/UtH22J8df2)
108
+
109
+ *Backtest on SPY, QQQ and IWM, January 2018 to October 2026, at halfway fills and $1 per contract. At one contract set per signal, following it made $945,541 on 20,883 trades; selling every day made $2,321,150 on 56,975. At 3.76 times the contracts, both fell $958,924 at their deepest, and the worst month was -$642,135 against -$307,241. Past results do not guarantee future returns, and short options can lose more than the premium collected. The skip call applies to new trades, so it cannot protect open positions from a sudden shock. This is data, not investment advice.*
110
+
77
111
  ## Data provenance: `data_as_of`
78
112
 
79
113
  Every successful JSON-object response carries `data_as_of`, reporting when each upstream
@@ -199,6 +233,33 @@ narrative = fa.narrative("SPY") # AI narrative (Gro
199
233
  print(narrative["narrative"]["outlook"])
200
234
  ```
201
235
 
236
+ ### Expiry impact and strike dependency (SPY, QQQ)
237
+
238
+ Two Growth+ views of how much of the current gamma concentration rests on one expiry.
239
+
240
+ - **Expiry impact** compares the current SPY or QQQ gamma distribution with the same
241
+ captured inputs after excluding one expiry. Spot, Greeks and open interest are held
242
+ fixed, so it measures how much of today's concentration depends on one maturity. It is
243
+ not a forecast of post-expiry prices, dealer hedging or the next session's chain.
244
+ - **Strike dependency** attributes the gamma at one exact observed strike to its
245
+ expiries, and names the dominant expiry. It reports concentration at that strike, not
246
+ a support/resistance probability.
247
+
248
+ ```python
249
+ from flashalpha import ExpiryImpactResponse, StrikeDependencyResponse
250
+
251
+ impact: ExpiryImpactResponse = fa.expiry_impact("SPY", limit=5)
252
+ print(impact["selected_expiry"], impact["impact"]["removed_gross_share_pct"])
253
+ print(impact["impact"]["net_sign_changed"])
254
+
255
+ dependency: StrikeDependencyResponse = fa.strike_dependency("SPY", strike=670)
256
+ print(dependency["dominant_expiry"], dependency["dominant_expiry_share_pct"])
257
+ ```
258
+
259
+ `data_status` is `partial` in normal operation (the open-interest vintage is unknown),
260
+ `stale` when an input predates the market-session freshness cutoff, and `unavailable`
261
+ when no contract qualifies. `reasons` carries machine codes.
262
+
202
263
  ### 0DTE Analytics
203
264
 
204
265
  Real-time zero-days-to-expiration analysis: gamma regime, expected move, pin risk scoring, dealer hedging estimates, theta decay acceleration, and per-strike breakdown.
@@ -408,6 +469,8 @@ Get your API key at **[flashalpha.com](https://flashalpha.com)**
408
469
  | `fa.exposure_term_structure(symbol)` | Exposure aggregated by DTE bucket and expiry | Growth+ |
409
470
  | `fa.exposure_basket(symbols)` | Weighted cross-symbol exposure aggregate | Growth+ |
410
471
  | `fa.exposure_oi_diff(symbol)` | Day-over-day open-interest deltas, top-N | Growth+ |
472
+ | `fa.expiry_impact(symbol, expiry=, limit=)` | Gamma concentration with one expiry excluded (SPY/QQQ) | Growth+ |
473
+ | `fa.strike_dependency(symbol, strike=)` | One exact strike's gamma attributed to its expiries (SPY/QQQ) | Growth+ |
411
474
  | `fa.liquidity(symbol)` | Per-expiry execution score and bid-ask spreads | Growth+ |
412
475
  | `fa.skew_term(symbol)` | 25-delta skew and risk-reversal term structure | Growth+ |
413
476
  | `fa.spot_vol_correlation(symbol)` | Spot-vol correlation (20d/60d) | Growth+ |
@@ -437,6 +500,7 @@ Get your API key at **[flashalpha.com](https://flashalpha.com)**
437
500
  | `fa.strategy_skew(symbol)` | Strategy signal: skew richness | Growth+ |
438
501
  | `fa.strategy_term_structure(symbol)` | Strategy signal: IV term-structure slope | Growth+ |
439
502
  | `fa.strategy_tail_pricing(symbol)` | Strategy signal: tail (deep-wing) pricing | Growth+ |
503
+ | `fa.sell_window(symbol)` | sell-window: should you sell options today? Sell or skip per expiry, with the trades to place (SPY, QQQ, IWM) | Basic+ through Nov 2026, then Growth+ |
440
504
  | `fa.earnings_calendar(...)` | Upcoming earnings calendar | Growth+ |
441
505
  | `fa.earnings_expected_move(symbol)` | Earnings implied-move decomposition | Growth+ |
442
506
  | `fa.earnings_history(symbol)` | Past earnings: surprises, moves, IV crush | Growth+ |
@@ -42,6 +42,40 @@ Get your free API key at [flashalpha.com](https://flashalpha.com) — no credit
42
42
  > `gamma_flip_status == "available"` guarantees a number; treat any other value -
43
43
  > including codes added in future - as "no level published".
44
44
 
45
+ ## sell-window: should you sell options today?
46
+
47
+ Option sellers get wiped out on a few bad days. sell-window tells you which days to stay out, and on the days it says sell, it hands you the trades: which expiry, which strikes and how to exit. Every session, for SPY, QQQ and IWM. More than 5 million backtests led to this one endpoint.
48
+
49
+ ```python
50
+ from flashalpha import FlashAlpha
51
+
52
+ fa = FlashAlpha("YOUR_API_KEY")
53
+ answer = fa.sell_window("SPY")
54
+
55
+ for window in answer["windows"]:
56
+ print(window.get("expiry"), window["action"]) # sell, skip or unavailable
57
+ for trade in window.get("candidates", []):
58
+ print(" ", trade["structure"], trade.get("mid_credit"), trade["exit"])
59
+ ```
60
+
61
+ Each of the four windows (the same-day expiry, then the expiries closest to one week, two weeks and one month out) says `sell`, `skip` or `unavailable`. On a sell it lists the trades, with strikes, quotes and the exit rule. On a skip there is nothing to do.
62
+
63
+ | Backtest, 2018 to 2026 | Following sell-window | Selling the same trades every day |
64
+ |---|---|---|
65
+ | Max drawdown at the same trade size | $255k | $959k |
66
+ | Worst month at the same trade size | -$171k | -$307k |
67
+ | Sharpe ratio | 0.76 | 0.61 |
68
+ | Total P&L at the same max drawdown | $3.55M | $2.32M |
69
+ | Worst day at the same max drawdown | -$258k | -$385k |
70
+
71
+ Cut the risk or earn more. Keep your trade size and the deepest drawdown falls 73%. Or size up about 3.8 times, until the deepest drawdown matches, and you earn 53% more. These are two separate choices, not one result.
72
+
73
+ **Plans:** Live answers need Basic or higher through November 2026, and Growth or higher from December 1, 2026. Backtesting any past session needs Alpha or higher. Backtest with [flashalpha-historical-python](https://github.com/FlashAlpha-lab/flashalpha-historical-python).
74
+
75
+ **Read more:** [API docs](https://flashalpha.com/docs/lab-api-strategies-sell-window?utm_source=github&utm_medium=readme&utm_campaign=repo-flashalpha-python&utm_content=sell-window) | [trading guide](https://flashalpha.com/articles/complete-guide-trading-sell-window-spy-qqq-iwm?utm_source=github&utm_medium=readme&utm_campaign=repo-flashalpha-python&utm_content=sell-window) | [every backtested trade](https://flashalpha.com/articles/sell-window-backtest-every-trade-2018-2026?utm_source=github&utm_medium=readme&utm_campaign=repo-flashalpha-python&utm_content=sell-window) | [sell-window in depth](https://github.com/FlashAlpha-lab/flashalpha-python/blob/main/docs/sell-window.md) | [plans](https://flashalpha.com/pricing?utm_source=github&utm_medium=readme&utm_campaign=repo-flashalpha-python&utm_content=sell-window) | [live forward test on Discord](https://discord.gg/UtH22J8df2)
76
+
77
+ *Backtest on SPY, QQQ and IWM, January 2018 to October 2026, at halfway fills and $1 per contract. At one contract set per signal, following it made $945,541 on 20,883 trades; selling every day made $2,321,150 on 56,975. At 3.76 times the contracts, both fell $958,924 at their deepest, and the worst month was -$642,135 against -$307,241. Past results do not guarantee future returns, and short options can lose more than the premium collected. The skip call applies to new trades, so it cannot protect open positions from a sudden shock. This is data, not investment advice.*
78
+
45
79
  ## Data provenance: `data_as_of`
46
80
 
47
81
  Every successful JSON-object response carries `data_as_of`, reporting when each upstream
@@ -167,6 +201,33 @@ narrative = fa.narrative("SPY") # AI narrative (Gro
167
201
  print(narrative["narrative"]["outlook"])
168
202
  ```
169
203
 
204
+ ### Expiry impact and strike dependency (SPY, QQQ)
205
+
206
+ Two Growth+ views of how much of the current gamma concentration rests on one expiry.
207
+
208
+ - **Expiry impact** compares the current SPY or QQQ gamma distribution with the same
209
+ captured inputs after excluding one expiry. Spot, Greeks and open interest are held
210
+ fixed, so it measures how much of today's concentration depends on one maturity. It is
211
+ not a forecast of post-expiry prices, dealer hedging or the next session's chain.
212
+ - **Strike dependency** attributes the gamma at one exact observed strike to its
213
+ expiries, and names the dominant expiry. It reports concentration at that strike, not
214
+ a support/resistance probability.
215
+
216
+ ```python
217
+ from flashalpha import ExpiryImpactResponse, StrikeDependencyResponse
218
+
219
+ impact: ExpiryImpactResponse = fa.expiry_impact("SPY", limit=5)
220
+ print(impact["selected_expiry"], impact["impact"]["removed_gross_share_pct"])
221
+ print(impact["impact"]["net_sign_changed"])
222
+
223
+ dependency: StrikeDependencyResponse = fa.strike_dependency("SPY", strike=670)
224
+ print(dependency["dominant_expiry"], dependency["dominant_expiry_share_pct"])
225
+ ```
226
+
227
+ `data_status` is `partial` in normal operation (the open-interest vintage is unknown),
228
+ `stale` when an input predates the market-session freshness cutoff, and `unavailable`
229
+ when no contract qualifies. `reasons` carries machine codes.
230
+
170
231
  ### 0DTE Analytics
171
232
 
172
233
  Real-time zero-days-to-expiration analysis: gamma regime, expected move, pin risk scoring, dealer hedging estimates, theta decay acceleration, and per-strike breakdown.
@@ -376,6 +437,8 @@ Get your API key at **[flashalpha.com](https://flashalpha.com)**
376
437
  | `fa.exposure_term_structure(symbol)` | Exposure aggregated by DTE bucket and expiry | Growth+ |
377
438
  | `fa.exposure_basket(symbols)` | Weighted cross-symbol exposure aggregate | Growth+ |
378
439
  | `fa.exposure_oi_diff(symbol)` | Day-over-day open-interest deltas, top-N | Growth+ |
440
+ | `fa.expiry_impact(symbol, expiry=, limit=)` | Gamma concentration with one expiry excluded (SPY/QQQ) | Growth+ |
441
+ | `fa.strike_dependency(symbol, strike=)` | One exact strike's gamma attributed to its expiries (SPY/QQQ) | Growth+ |
379
442
  | `fa.liquidity(symbol)` | Per-expiry execution score and bid-ask spreads | Growth+ |
380
443
  | `fa.skew_term(symbol)` | 25-delta skew and risk-reversal term structure | Growth+ |
381
444
  | `fa.spot_vol_correlation(symbol)` | Spot-vol correlation (20d/60d) | Growth+ |
@@ -405,6 +468,7 @@ Get your API key at **[flashalpha.com](https://flashalpha.com)**
405
468
  | `fa.strategy_skew(symbol)` | Strategy signal: skew richness | Growth+ |
406
469
  | `fa.strategy_term_structure(symbol)` | Strategy signal: IV term-structure slope | Growth+ |
407
470
  | `fa.strategy_tail_pricing(symbol)` | Strategy signal: tail (deep-wing) pricing | Growth+ |
471
+ | `fa.sell_window(symbol)` | sell-window: should you sell options today? Sell or skip per expiry, with the trades to place (SPY, QQQ, IWM) | Basic+ through Nov 2026, then Growth+ |
408
472
  | `fa.earnings_calendar(...)` | Upcoming earnings calendar | Growth+ |
409
473
  | `fa.earnings_expected_move(symbol)` | Earnings implied-move decomposition | Growth+ |
410
474
  | `fa.earnings_history(symbol)` | Past earnings: surprises, moves, IV crush | Growth+ |
@@ -4,8 +4,8 @@ build-backend = "hatchling.build"
4
4
 
5
5
  [project]
6
6
  name = "flashalpha"
7
- version = "1.3.0"
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."
7
+ version = "1.5.0"
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, the sell-window sell-or-skip call for option sellers, and more."
9
9
  readme = "README.md"
10
10
  license = "MIT"
11
11
  requires-python = ">=3.10"
@@ -42,6 +42,11 @@ keywords = [
42
42
  "short vol",
43
43
  "vol selling",
44
44
  "dealer flow",
45
+ "sell-window",
46
+ "option selling",
47
+ "short premium",
48
+ "premium selling",
49
+ "when to sell options",
45
50
  ]
46
51
  classifiers = [
47
52
  "Development Status :: 3 - Alpha",
@@ -185,6 +185,10 @@ from .types import (
185
185
  StrategyStructure,
186
186
  StrategyRiskFlag,
187
187
  StrategyDataQuality,
188
+ SellWindowCandidate,
189
+ SellWindowLeg,
190
+ SellWindowResponse,
191
+ SellWindowWindow,
188
192
  StrategyDecisionResponse,
189
193
  # ── Earnings ──
190
194
  EarningsCalendarEvent,
@@ -234,6 +238,16 @@ from .types import (
234
238
  ExposureBasketResponse,
235
239
  ExposureOiDiffRow,
236
240
  ExposureOiDiffResponse,
241
+ # ── Expiry impact / strike dependency ──
242
+ GammaContextReason,
243
+ GammaContextMetadata,
244
+ GammaTotals,
245
+ GammaExpiryRow,
246
+ GammaStrikeImpact,
247
+ GammaRemovalImpact,
248
+ GammaContextFact,
249
+ ExpiryImpactResponse,
250
+ StrikeDependencyResponse,
237
251
  # ── Volatility / Liquidity (additional) ──
238
252
  LiquidityExpiry,
239
253
  LiquidityResponse,
@@ -277,7 +291,7 @@ from .types import (
277
291
  VrpHistoryResponse,
278
292
  )
279
293
 
280
- __version__ = "1.2.3"
294
+ __version__ = "1.5.0"
281
295
  __all__ = [
282
296
  "DataAsOf",
283
297
  "FlashAlpha",
@@ -466,6 +480,10 @@ __all__ = [
466
480
  "StrategyStructure",
467
481
  "StrategyRiskFlag",
468
482
  "StrategyDataQuality",
483
+ "SellWindowCandidate",
484
+ "SellWindowLeg",
485
+ "SellWindowResponse",
486
+ "SellWindowWindow",
469
487
  "StrategyDecisionResponse",
470
488
  # ── Earnings ──
471
489
  "EarningsCalendarEvent",
@@ -515,6 +533,16 @@ __all__ = [
515
533
  "ExposureBasketResponse",
516
534
  "ExposureOiDiffRow",
517
535
  "ExposureOiDiffResponse",
536
+ # ── Expiry impact / strike dependency ──
537
+ "GammaContextReason",
538
+ "GammaContextMetadata",
539
+ "GammaTotals",
540
+ "GammaExpiryRow",
541
+ "GammaStrikeImpact",
542
+ "GammaRemovalImpact",
543
+ "GammaContextFact",
544
+ "ExpiryImpactResponse",
545
+ "StrikeDependencyResponse",
518
546
  # ── Volatility / Liquidity (additional) ──
519
547
  "LiquidityExpiry",
520
548
  "LiquidityResponse",
@@ -2,6 +2,7 @@
2
2
 
3
3
  from __future__ import annotations
4
4
 
5
+ from decimal import Decimal
5
6
  from typing import TYPE_CHECKING, Any
6
7
  from urllib.parse import quote
7
8
 
@@ -32,6 +33,7 @@ if TYPE_CHECKING:
32
33
  EarningsStrategiesResponse,
33
34
  EarningsVrpResponse,
34
35
  ExpectedMoveResponse,
36
+ ExpiryImpactResponse,
35
37
  ExposureBasketResponse,
36
38
  ExposureLevelsResponse,
37
39
  ExposureOiDiffResponse,
@@ -83,11 +85,13 @@ if TYPE_CHECKING:
83
85
  RealizedVolatilityResponse,
84
86
  ScreenerFieldsResponse,
85
87
  ScreenerResponse,
88
+ SellWindowResponse,
86
89
  SkewTermResponse,
87
90
  SpotVolCorrelationResponse,
88
91
  StockQuoteResponse,
89
92
  StockSummaryResponse,
90
93
  StrategyDecisionResponse,
94
+ StrikeDependencyResponse,
91
95
  StructureGreeksResponse,
92
96
  StructurePnlResponse,
93
97
  SurfaceResponse,
@@ -112,6 +116,14 @@ def _seg(s: str) -> str:
112
116
  return quote(s, safe="")
113
117
 
114
118
 
119
+ def _format_number(value: float | Decimal | str) -> str:
120
+ """Exact, locale-independent decimal text for a query value: 672.5 -> "672.5".
121
+
122
+ Never scientific notation (``str(1e-07)`` is ``"1e-07"``) and never rounded.
123
+ """
124
+ return format(Decimal(str(value)), "f")
125
+
126
+
115
127
  class FlashAlpha:
116
128
  """Thin wrapper around the FlashAlpha REST API.
117
129
 
@@ -361,6 +373,45 @@ class FlashAlpha:
361
373
  params["topN"] = top_n
362
374
  return self._get(f"/v1/exposure/oi-diff/{_seg(symbol)}", params or None)
363
375
 
376
+ def expiry_impact(
377
+ self, symbol: str, *, expiry: str | None = None, limit: int | None = None
378
+ ) -> ExpiryImpactResponse:
379
+ """Compares the current SPY or QQQ gamma distribution with the same captured
380
+ inputs after excluding one expiry. Requires Growth or higher.
381
+
382
+ Spot, Greeks and open interest are held fixed, so this measures how much
383
+ of today's concentration depends on one maturity. It is not a forecast of
384
+ post-expiry prices, dealer hedging or the next session's chain.
385
+
386
+ ``expiry`` (yyyy-MM-dd, optional) defaults to the nearest active eligible
387
+ expiry and must be one of ``available_expiries``. ``limit`` (1-20, default
388
+ 5) sets the rows in ``impact.largest_gross_reductions`` and
389
+ ``impact.strongest_remaining_concentrations``; totals and ``strikes``
390
+ always use the full eligible chain. Other symbols return 422
391
+ ``unsupported_symbol``.
392
+ """
393
+ params: dict[str, Any] = {}
394
+ if expiry:
395
+ params["expiry"] = expiry
396
+ if limit is not None:
397
+ params["limit"] = limit
398
+ return self._get(f"/v1/exposure/expiry-impact/{_seg(symbol)}", params or None)
399
+
400
+ def strike_dependency(self, symbol: str, *, strike: float | Decimal) -> StrikeDependencyResponse:
401
+ """Attributes the gamma at one exact observed SPY or QQQ strike to its
402
+ expiries: does the level depend on a single maturity? Requires Growth or
403
+ higher.
404
+
405
+ It reports concentration at that strike, not a support/resistance
406
+ probability. ``strike`` is required and must be an exact listed strike;
407
+ the request is never snapped to a nearby strike (404 ``strike_not_found``).
408
+ Other symbols return 422 ``unsupported_symbol``.
409
+ """
410
+ return self._get(
411
+ f"/v1/exposure/strike-dependency/{_seg(symbol)}",
412
+ {"strike": _format_number(strike)},
413
+ )
414
+
364
415
  # ── Volatility / Liquidity (additional) ─────────────────────────
365
416
 
366
417
  def liquidity(self, symbol: str) -> LiquidityResponse:
@@ -1169,6 +1220,26 @@ class FlashAlpha:
1169
1220
  """Scores tail (deep-wing) pricing richness. Requires Growth+."""
1170
1221
  return self._strategy("tail-pricing", symbol, expiry=expiry)
1171
1222
 
1223
+ # ── sell-window (own response shape) ────────────────────────────
1224
+
1225
+ def sell_window(self, symbol: str) -> SellWindowResponse:
1226
+ """Should you sell options today? One answer per session for SPY, QQQ and IWM.
1227
+
1228
+ Built from more than 5 million backtests. For four listed expiries (same day,
1229
+ then the expiries closest to one week, two weeks and one month out) each
1230
+ window says ``sell``, ``skip`` or ``unavailable``. On a sell it lists the
1231
+ trades to place, with strikes, quotes and the exit rule. On a skip there is
1232
+ nothing to do. Treat ``unavailable`` like a skip.
1233
+
1234
+ The answer is set from the previous session's close and stays fixed for the
1235
+ session. Any symbol other than SPY, QQQ or IWM returns every window as
1236
+ ``unavailable``. Requires Basic+ through November 2026, Growth+ from
1237
+ December 1, 2026. Backtest any session with ``flashalpha-historical`` (Alpha+).
1238
+
1239
+ Docs: https://flashalpha.com/docs/lab-api-strategies-sell-window
1240
+ """
1241
+ return self._get(f"/v1/strategies/sell-window/{_seg(symbol)}")
1242
+
1172
1243
  # ── Earnings Analytics ──────────────────────────────────────────
1173
1244
 
1174
1245
  def earnings_calendar(
@@ -5509,3 +5509,242 @@ class ScreenerFieldsResponse(TypedDict, total=False):
5509
5509
  # Response envelope, present on every successful response.
5510
5510
  endpoint_version: str
5511
5511
  data_as_of: DataAsOf
5512
+
5513
+ # ── sell-window ─────────────────────────────────────────────────────
5514
+ #
5515
+ # Own response shape: not the StrategyDecisionResponse envelope.
5516
+
5517
+
5518
+ class SellWindowLeg(TypedDict, total=False):
5519
+ """One contract of a sell-window trade."""
5520
+
5521
+ side: Literal["sell", "buy"]
5522
+ # Contracts per unit of the trade: 2 for the sold body of put_bwb, otherwise 1.
5523
+ quantity: int
5524
+ type: Literal["call", "put"]
5525
+ strike: float
5526
+ # The contract's own delta when the answer was served (negative for puts).
5527
+ delta: float
5528
+ bid: float
5529
+ ask: float
5530
+
5531
+
5532
+ class SellWindowCandidate(TypedDict, total=False):
5533
+ """One trade to consider on a sell window."""
5534
+
5535
+ structure: Literal[
5536
+ "short_put",
5537
+ "short_call",
5538
+ "short_strangle",
5539
+ "short_straddle",
5540
+ "tail_hedged_put",
5541
+ "put_credit_spread",
5542
+ "put_bwb",
5543
+ ]
5544
+ # expiry: hold to expiration. tp50: close at half of the credit, else hold.
5545
+ exit: Literal["expiry", "tp50"]
5546
+ # Absent when no option chain could be loaded for the answer.
5547
+ legs: List[SellWindowLeg]
5548
+ # Net credit per share at mid. Multiply by 100 for one unit in dollars.
5549
+ mid_credit: float
5550
+
5551
+
5552
+ class SellWindowWindow(TypedDict, total=False):
5553
+ """One of the four windows, named by its listed expiry."""
5554
+
5555
+ # Absent when no listed expiry falls in the window's range.
5556
+ expiry: str
5557
+ days_to_expiry: int
5558
+ action: Literal["sell", "skip", "unavailable"]
5559
+ # Present only when action is "sell". Can be empty: a trade whose legs
5560
+ # cannot all be found in the chain is left out.
5561
+ candidates: List[SellWindowCandidate]
5562
+
5563
+
5564
+ class SellWindowResponse(TypedDict, total=False):
5565
+ """sell-window answer from ``GET /v1/strategies/sell-window/{symbol}``.
5566
+
5567
+ ``spot``, ``quoted_at`` and ``legs_indicative`` are present when a window sells
5568
+ and an option chain could be loaded.
5569
+ When ``legs_indicative`` is true the quotes are from before that session's
5570
+ 09:35 ET entry: call again at or after 09:35 ET for the strikes to trade.
5571
+ """
5572
+
5573
+ symbol: str
5574
+ # yyyy-MM-dd. The trading session the answer applies to.
5575
+ session: str
5576
+ spot: float
5577
+ quoted_at: str
5578
+ legs_indicative: bool
5579
+ # Always four entries: same day, then about one week, two weeks, one month.
5580
+ windows: List[SellWindowWindow]
5581
+ # Response envelope, present on every successful response.
5582
+ endpoint_version: str
5583
+ data_as_of: DataAsOf
5584
+
5585
+
5586
+ # ── Expiry impact / strike dependency (SPY, QQQ) ────────────────────
5587
+ #
5588
+ # Typed models for ``GET /v1/exposure/expiry-impact/{symbol}`` and
5589
+ # ``GET /v1/exposure/strike-dependency/{symbol}`` (Growth+). Both responses
5590
+ # carry the same metadata fields (``GammaContextMetadata``). Every ``*_usd``
5591
+ # value is GEX in USD per 1% move; ``*_pct`` values are 0-100. Timestamps are
5592
+ # ISO-8601 UTC strings and expiries are ``yyyy-MM-dd`` strings.
5593
+
5594
+
5595
+ class GammaContextReason(TypedDict, total=False):
5596
+ """One machine-coded reason behind ``data_status``."""
5597
+
5598
+ code: str
5599
+ message: str
5600
+ # Excluded-contract count for exclusion reasons, otherwise None.
5601
+ contract_count: Optional[int]
5602
+
5603
+
5604
+ class GammaContextMetadata(TypedDict, total=False):
5605
+ """Metadata shared by the expiry impact and strike dependency responses."""
5606
+
5607
+ symbol: str
5608
+ underlying_price: float
5609
+ # SHA-256 fingerprint of the captured inputs; identical inputs give identical IDs.
5610
+ snapshot_id: str
5611
+ generated_at: str
5612
+ quote_at: Optional[str]
5613
+ greeks_oldest_at: Optional[str]
5614
+ greeks_newest_at: Optional[str]
5615
+ calculation_version: str
5616
+ # ``captured_cached_gamma_current_spot`` (SPY) or ``qqq_common_anchor_repriced`` (QQQ).
5617
+ pricing_basis: str
5618
+ # ``partial`` in normal operation (open-interest vintage is unknown), ``stale``
5619
+ # when an input predates the market-session freshness cutoff, ``unavailable``
5620
+ # when no contract qualifies.
5621
+ data_status: str
5622
+ reasons: List[GammaContextReason]
5623
+ oi_as_of: Optional[str]
5624
+ oi_vintage_status: str
5625
+ eligible_contract_count: int
5626
+ rejected_contract_count: int
5627
+ observed_min_strike: Optional[float]
5628
+ observed_max_strike: Optional[float]
5629
+ gex_unit: str
5630
+ sign_convention: str
5631
+ analysis_type: str
5632
+
5633
+
5634
+ class GammaTotals(TypedDict, total=False):
5635
+ """Gross, net, call and put GEX (USD per 1% move) and the contract count."""
5636
+
5637
+ gross_gex_usd: float
5638
+ net_gex_usd: float
5639
+ call_gex_usd: float
5640
+ put_gex_usd: float
5641
+ contract_count: int
5642
+ # Present on ``excluding_expiry`` only: ``available``, ``zero_gross_exposure``
5643
+ # or ``no_remaining_contracts``.
5644
+ status: str
5645
+
5646
+
5647
+ class GammaExpiryRow(GammaTotals, total=False):
5648
+ """One expiry's share of the gamma at a strike (``by_expiry`` row)."""
5649
+
5650
+ expiry: str
5651
+ valuation_cutoff_at: str
5652
+ last_trading_at: str
5653
+ last_trading_status: str
5654
+ settlement_at: Optional[str]
5655
+ settlement_status: str
5656
+ calendar_days_to_expiry: int
5657
+ gross_share_pct: Optional[float]
5658
+ # Omitted when null.
5659
+ share_of_strike_gross_pct: float
5660
+
5661
+
5662
+ class GammaStrikeImpact(TypedDict, total=False):
5663
+ """One strike's current, excluded and remaining gross/net GEX."""
5664
+
5665
+ strike: float
5666
+ distance_from_spot_pct: float
5667
+ current_gross_gex_usd: float
5668
+ current_net_gex_usd: float
5669
+ excluded_gross_gex_usd: float
5670
+ excluded_net_gex_usd: float
5671
+ remaining_gross_gex_usd: float
5672
+ remaining_net_gex_usd: float
5673
+ excluded_share_at_strike_pct: Optional[float]
5674
+
5675
+
5676
+ class GammaRemovalImpact(TypedDict, total=False):
5677
+ """What changes when the selected expiry is excluded."""
5678
+
5679
+ # ``100 × excluded gross / current gross``. Null when current gross is zero.
5680
+ removed_gross_share_pct: Optional[float]
5681
+ retained_gross_share_pct: Optional[float]
5682
+ # ``remaining net − current net`` (minus the excluded net).
5683
+ net_gex_change_usd: float
5684
+ net_sign_before: str
5685
+ net_sign_after: str
5686
+ net_sign_changed: Optional[bool]
5687
+ # Top ``limit`` strikes by gross removed.
5688
+ largest_gross_reductions: List[GammaStrikeImpact]
5689
+ # Top ``limit`` strikes by gross remaining.
5690
+ strongest_remaining_concentrations: List[GammaStrikeImpact]
5691
+
5692
+
5693
+ class GammaContextFact(TypedDict, total=False):
5694
+ """A plain-language statement with its supporting values."""
5695
+
5696
+ code: str
5697
+ text: str
5698
+ # Keys vary by ``code``.
5699
+ supporting_values: Dict[str, Any]
5700
+
5701
+
5702
+ class ExpiryImpactResponse(GammaContextMetadata, total=False):
5703
+ """Expiry impact from ``GET /v1/exposure/expiry-impact/{symbol}`` (Growth+).
5704
+
5705
+ Compares the current SPY or QQQ gamma distribution with the same captured
5706
+ inputs after excluding one expiry. Spot, Greeks and open interest are held
5707
+ fixed, so this measures how much of today's concentration depends on one
5708
+ maturity. It is not a forecast of post-expiry prices, dealer hedging or the
5709
+ next session's chain.
5710
+ """
5711
+
5712
+ selected_expiry: str
5713
+ selection_source: str
5714
+ available_expiries: List[str]
5715
+ # The whole eligible chain.
5716
+ current: GammaTotals
5717
+ # The selected expiry.
5718
+ excluded_expiry: GammaTotals
5719
+ # The chain without the selected expiry.
5720
+ excluding_expiry: GammaTotals
5721
+ impact: GammaRemovalImpact
5722
+ # Every eligible strike, whatever ``limit`` is.
5723
+ strikes: List[GammaStrikeImpact]
5724
+ facts: List[GammaContextFact]
5725
+ # Response envelope, present on every successful response.
5726
+ endpoint_version: str
5727
+ data_as_of: DataAsOf
5728
+
5729
+
5730
+ class StrikeDependencyResponse(GammaContextMetadata, total=False):
5731
+ """Strike dependency from ``GET /v1/exposure/strike-dependency/{symbol}`` (Growth+).
5732
+
5733
+ Attributes the gamma at one exact observed SPY or QQQ strike to its expiries:
5734
+ does the level depend on a single maturity? It reports concentration at that
5735
+ strike, not a support/resistance probability.
5736
+ """
5737
+
5738
+ strike: float
5739
+ distance_from_spot_pct: float
5740
+ gross_gex_usd: float
5741
+ net_gex_usd: float
5742
+ call_gex_usd: float
5743
+ put_gex_usd: float
5744
+ contract_count: int
5745
+ by_expiry: List[GammaExpiryRow]
5746
+ dominant_expiry: Optional[str]
5747
+ dominant_expiry_share_pct: Optional[float]
5748
+ # Response envelope, present on every successful response.
5749
+ endpoint_version: str
5750
+ data_as_of: DataAsOf
File without changes
File without changes