flashalpha 1.3.0__tar.gz → 1.4.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.4.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
@@ -437,6 +471,7 @@ Get your API key at **[flashalpha.com](https://flashalpha.com)**
437
471
  | `fa.strategy_skew(symbol)` | Strategy signal: skew richness | Growth+ |
438
472
  | `fa.strategy_term_structure(symbol)` | Strategy signal: IV term-structure slope | Growth+ |
439
473
  | `fa.strategy_tail_pricing(symbol)` | Strategy signal: tail (deep-wing) pricing | Growth+ |
474
+ | `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
475
  | `fa.earnings_calendar(...)` | Upcoming earnings calendar | Growth+ |
441
476
  | `fa.earnings_expected_move(symbol)` | Earnings implied-move decomposition | Growth+ |
442
477
  | `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
@@ -405,6 +439,7 @@ Get your API key at **[flashalpha.com](https://flashalpha.com)**
405
439
  | `fa.strategy_skew(symbol)` | Strategy signal: skew richness | Growth+ |
406
440
  | `fa.strategy_term_structure(symbol)` | Strategy signal: IV term-structure slope | Growth+ |
407
441
  | `fa.strategy_tail_pricing(symbol)` | Strategy signal: tail (deep-wing) pricing | Growth+ |
442
+ | `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
443
  | `fa.earnings_calendar(...)` | Upcoming earnings calendar | Growth+ |
409
444
  | `fa.earnings_expected_move(symbol)` | Earnings implied-move decomposition | Growth+ |
410
445
  | `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.4.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,
@@ -277,7 +281,7 @@ from .types import (
277
281
  VrpHistoryResponse,
278
282
  )
279
283
 
280
- __version__ = "1.2.3"
284
+ __version__ = "1.4.0"
281
285
  __all__ = [
282
286
  "DataAsOf",
283
287
  "FlashAlpha",
@@ -466,6 +470,10 @@ __all__ = [
466
470
  "StrategyStructure",
467
471
  "StrategyRiskFlag",
468
472
  "StrategyDataQuality",
473
+ "SellWindowCandidate",
474
+ "SellWindowLeg",
475
+ "SellWindowResponse",
476
+ "SellWindowWindow",
469
477
  "StrategyDecisionResponse",
470
478
  # ── Earnings ──
471
479
  "EarningsCalendarEvent",
@@ -83,6 +83,7 @@ if TYPE_CHECKING:
83
83
  RealizedVolatilityResponse,
84
84
  ScreenerFieldsResponse,
85
85
  ScreenerResponse,
86
+ SellWindowResponse,
86
87
  SkewTermResponse,
87
88
  SpotVolCorrelationResponse,
88
89
  StockQuoteResponse,
@@ -1169,6 +1170,26 @@ class FlashAlpha:
1169
1170
  """Scores tail (deep-wing) pricing richness. Requires Growth+."""
1170
1171
  return self._strategy("tail-pricing", symbol, expiry=expiry)
1171
1172
 
1173
+ # ── sell-window (own response shape) ────────────────────────────
1174
+
1175
+ def sell_window(self, symbol: str) -> SellWindowResponse:
1176
+ """Should you sell options today? One answer per session for SPY, QQQ and IWM.
1177
+
1178
+ Built from more than 5 million backtests. For four listed expiries (same day,
1179
+ then the expiries closest to one week, two weeks and one month out) each
1180
+ window says ``sell``, ``skip`` or ``unavailable``. On a sell it lists the
1181
+ trades to place, with strikes, quotes and the exit rule. On a skip there is
1182
+ nothing to do. Treat ``unavailable`` like a skip.
1183
+
1184
+ The answer is set from the previous session's close and stays fixed for the
1185
+ session. Any symbol other than SPY, QQQ or IWM returns every window as
1186
+ ``unavailable``. Requires Basic+ through November 2026, Growth+ from
1187
+ December 1, 2026. Backtest any session with ``flashalpha-historical`` (Alpha+).
1188
+
1189
+ Docs: https://flashalpha.com/docs/lab-api-strategies-sell-window
1190
+ """
1191
+ return self._get(f"/v1/strategies/sell-window/{_seg(symbol)}")
1192
+
1172
1193
  # ── Earnings Analytics ──────────────────────────────────────────
1173
1194
 
1174
1195
  def earnings_calendar(
@@ -5509,3 +5509,75 @@ 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
File without changes
File without changes