flashalpha 1.2.3__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.
@@ -211,11 +211,11 @@ cython_debug/
211
211
  marimo/_static/
212
212
  marimo/_lsp/
213
213
  __marimo__/
214
-
215
- # Sandbox / agent / harness caches (cross-ecosystem — defensive)
216
- .dotnet/
217
- .gocache/
218
- .gopath/
219
- .m2/
220
- .review-artifacts/
221
- .agent-tools/
214
+
215
+ # Sandbox / agent / harness caches (cross-ecosystem — defensive)
216
+ .dotnet/
217
+ .gocache/
218
+ .gopath/
219
+ .m2/
220
+ .review-artifacts/
221
+ .agent-tools/
@@ -1,21 +1,21 @@
1
- MIT License
2
-
3
- Copyright (c) 2026 FlashAlpha
4
-
5
- Permission is hereby granted, free of charge, to any person obtaining a copy
6
- of this software and associated documentation files (the "Software"), to deal
7
- in the Software without restriction, including without limitation the rights
8
- to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
- copies of the Software, and to permit persons to whom the Software is
10
- furnished to do so, subject to the following conditions:
11
-
12
- The above copyright notice and this permission notice shall be included in all
13
- copies or substantial portions of the Software.
14
-
15
- THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
- IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
- FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
- AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
- LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
- OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
- SOFTWARE.
1
+ MIT License
2
+
3
+ Copyright (c) 2026 FlashAlpha
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -1,7 +1,7 @@
1
1
  Metadata-Version: 2.5
2
2
  Name: flashalpha
3
- Version: 1.2.3
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
@@ -55,7 +55,9 @@ fa = FlashAlpha("YOUR_API_KEY") # Get a free key at flashalpha.com
55
55
  # Gamma exposure by strike
56
56
  gex = fa.gex("SPY")
57
57
  print(f"Net GEX: ${gex['net_gex']:,.0f}")
58
- print(f"Gamma flip: {gex['gamma_flip']}")
58
+ # gamma_flip is None unless gamma_flip_status == "available" -- never format it
59
+ # as a number without checking first.
60
+ print(f"Gamma flip: {gex['gamma_flip']} ({gex['gamma_flip_status']})")
59
61
 
60
62
  for strike in gex["strikes"][:5]:
61
63
  print(f" {strike['strike']}: net ${strike['net_gex']:,.0f}")
@@ -63,6 +65,112 @@ for strike in gex["strikes"][:5]:
63
65
 
64
66
  Get your free API key at [flashalpha.com](https://flashalpha.com) — no credit card required.
65
67
 
68
+ > **`gamma_flip` is nullable.** A dealer gamma flip is only published when the
69
+ > level is well-determined, which is a minority of chains. When it is withheld,
70
+ > `gamma_flip` is `null`, `regime` is `"unknown"`, and `gamma_flip_status` carries
71
+ > a reason code (`no_boundary`, `insufficient_local_coverage`,
72
+ > `insufficient_quote_quality`, `sensitive_root`, `uncertain_root_path`,
73
+ > `stored_sign_mismatch`, `search_budget`, `quality_budget`). Only
74
+ > `gamma_flip_status == "available"` guarantees a number; treat any other value -
75
+ > including codes added in future - as "no level published".
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
+
111
+ ## Data provenance: `data_as_of`
112
+
113
+ Every successful JSON-object response carries `data_as_of`, reporting when each upstream
114
+ feed last delivered to the node that answered, plus `endpoint_version` identifying the
115
+ deployment that produced it. That is every method on this client except the handful that
116
+ return a bare JSON array - see the note at the end of this section.
117
+
118
+ ```python
119
+ gex = fa.gex("SPY")
120
+
121
+ print(gex["data_as_of"]["equity_options_feed"]) # 2026-08-25T18:48:58.204Z
122
+ print(gex["data_as_of"]["oi_feed"]) # 2026-08-24T20:00:00.000Z (prior session)
123
+ print(gex["data_as_of"]["node"]) # fa2
124
+ print(gex["endpoint_version"]) # 2026.08.25
125
+
126
+ # Typed: DataAsOf is exported for annotation and editor completion.
127
+ from flashalpha import DataAsOf
128
+ stamps: DataAsOf = gex["data_as_of"]
129
+ ```
130
+
131
+ | Field | Feed | Expected cadence |
132
+ |---|---|---|
133
+ | `node` | Which node answered | Nodes hydrate independently |
134
+ | `equity_feed` | Equity and ETF spot quotes | seconds, during market hours |
135
+ | `equity_options_feed` | Equity and ETF option quotes | seconds, during market hours |
136
+ | `index_feed` | Index spot (SPX, RUT, VIX and the other index roots) | seconds, during market hours |
137
+ | `index_options_feed` | Index option quotes | seconds, during market hours |
138
+ | `futures_feed` | Futures prices | seconds, during the futures session |
139
+ | `futures_options_feed` | Futures option quotes | seconds, during the futures session |
140
+ | `flow_feed` | Classified options and stock trade tape | seconds, during market hours |
141
+ | `oi_feed` | Settled open interest | daily, dated to the prior 16:00 ET close |
142
+ | `macro_feed` | VIX, VVIX, SKEW, MOVE, SPX, Fear & Greed | minutes; reports its OLDEST component |
143
+
144
+ ### How to read it
145
+
146
+ - **Check the feeds your call depends on.** A GEX call on an equity is answered from
147
+ `equity_feed`, `equity_options_feed` and `oi_feed`. `futures_feed` being `null` in that
148
+ response says nothing about the answer.
149
+ - **Compare against the cadence, not the clock.** `oi_feed` at the previous session's
150
+ close is correct: settled open interest is published once per session, so on a Monday
151
+ the newest figure that exists is Friday's. An options feed an hour behind during the
152
+ regular session is not correct.
153
+ - **`null` means "not seen on this node", not "broken".** A node that has never been
154
+ asked for a futures symbol has never opened that feed.
155
+ - **Spot and options are separate on purpose.** They arrive over different pipes and can
156
+ fail independently.
157
+ - **It evidences feed activity, not per-contract freshness.** An illiquid strike may not
158
+ have quoted for hours while its feed is healthy.
159
+ - **`data_as_of` is not `as_of`.** `as_of` is response-generation time or the newest
160
+ contract in the payload, depending on the endpoint. `data_as_of` describes the feeds
161
+ behind it.
162
+
163
+ ### Bare-array endpoints
164
+
165
+ A few endpoints return a bare JSON array, which has nowhere to put an envelope in the
166
+ body. The API sends the same information in the `X-Data-As-Of` and `X-Endpoint-Version`
167
+ response headers instead - but this client returns the parsed body only and does not
168
+ surface response headers, so the envelope is **not reachable through those methods**.
169
+ Call the HTTP endpoint directly if you need provenance for one of them.
170
+
171
+ Full reference: <https://flashalpha.com/docs/lab-api-overview#response-envelope> and the
172
+ methodology whitepaper at <https://flashalpha.com/methodology#freshness-reporting>.
173
+
66
174
  ## Features
67
175
 
68
176
  ### Live Options Screener
@@ -117,7 +225,8 @@ chex = fa.chex("NVDA") # Charm exposure
117
225
  levels = fa.exposure_levels("SPY") # Key levels
118
226
  print(f"Call wall: {levels['levels']['call_wall']}")
119
227
  print(f"Put wall: {levels['levels']['put_wall']}")
120
- print(f"Gamma flip: {levels['levels']['gamma_flip']}")
228
+ print(f"Gamma flip: {levels['levels']['gamma_flip']} "
229
+ f"({levels['levels']['gamma_flip_status']})")
121
230
 
122
231
  summary = fa.exposure_summary("SPY") # Full summary (Growth+)
123
232
  narrative = fa.narrative("SPY") # AI narrative (Growth+)
@@ -362,6 +471,7 @@ Get your API key at **[flashalpha.com](https://flashalpha.com)**
362
471
  | `fa.strategy_skew(symbol)` | Strategy signal: skew richness | Growth+ |
363
472
  | `fa.strategy_term_structure(symbol)` | Strategy signal: IV term-structure slope | Growth+ |
364
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+ |
365
475
  | `fa.earnings_calendar(...)` | Upcoming earnings calendar | Growth+ |
366
476
  | `fa.earnings_expected_move(symbol)` | Earnings implied-move decomposition | Growth+ |
367
477
  | `fa.earnings_history(symbol)` | Past earnings: surprises, moves, IV crush | Growth+ |
@@ -416,7 +526,7 @@ calculator and stock quotes. Paid tiers add:
416
526
  - **DEX, VEX (vanna) and CHEX (charm) exposure, plus max pain** — from the **Basic tier**
417
527
  ($79/mo), with ETF and index symbols.
418
528
  - **Full-chain GEX, 0DTE and flow analytics** — from the **Growth tier** ($299/mo).
419
- - **Point-in-time replay since 2018, SVI vol surfaces, VRP analytics, higher-order Greeks**,
529
+ - **Point-in-time replay since 2017, SVI vol surfaces, VRP analytics, higher-order Greeks**,
420
530
  uncached and unlimited — the **Alpha tier** ($1,499/mo). FlashAlpha is one of the only
421
531
  public APIs publishing aggregate vanna and charm exposure across the full universe, with
422
532
  no look-ahead and no training-serving skew.
@@ -23,7 +23,9 @@ fa = FlashAlpha("YOUR_API_KEY") # Get a free key at flashalpha.com
23
23
  # Gamma exposure by strike
24
24
  gex = fa.gex("SPY")
25
25
  print(f"Net GEX: ${gex['net_gex']:,.0f}")
26
- print(f"Gamma flip: {gex['gamma_flip']}")
26
+ # gamma_flip is None unless gamma_flip_status == "available" -- never format it
27
+ # as a number without checking first.
28
+ print(f"Gamma flip: {gex['gamma_flip']} ({gex['gamma_flip_status']})")
27
29
 
28
30
  for strike in gex["strikes"][:5]:
29
31
  print(f" {strike['strike']}: net ${strike['net_gex']:,.0f}")
@@ -31,6 +33,112 @@ for strike in gex["strikes"][:5]:
31
33
 
32
34
  Get your free API key at [flashalpha.com](https://flashalpha.com) — no credit card required.
33
35
 
36
+ > **`gamma_flip` is nullable.** A dealer gamma flip is only published when the
37
+ > level is well-determined, which is a minority of chains. When it is withheld,
38
+ > `gamma_flip` is `null`, `regime` is `"unknown"`, and `gamma_flip_status` carries
39
+ > a reason code (`no_boundary`, `insufficient_local_coverage`,
40
+ > `insufficient_quote_quality`, `sensitive_root`, `uncertain_root_path`,
41
+ > `stored_sign_mismatch`, `search_budget`, `quality_budget`). Only
42
+ > `gamma_flip_status == "available"` guarantees a number; treat any other value -
43
+ > including codes added in future - as "no level published".
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
+
79
+ ## Data provenance: `data_as_of`
80
+
81
+ Every successful JSON-object response carries `data_as_of`, reporting when each upstream
82
+ feed last delivered to the node that answered, plus `endpoint_version` identifying the
83
+ deployment that produced it. That is every method on this client except the handful that
84
+ return a bare JSON array - see the note at the end of this section.
85
+
86
+ ```python
87
+ gex = fa.gex("SPY")
88
+
89
+ print(gex["data_as_of"]["equity_options_feed"]) # 2026-08-25T18:48:58.204Z
90
+ print(gex["data_as_of"]["oi_feed"]) # 2026-08-24T20:00:00.000Z (prior session)
91
+ print(gex["data_as_of"]["node"]) # fa2
92
+ print(gex["endpoint_version"]) # 2026.08.25
93
+
94
+ # Typed: DataAsOf is exported for annotation and editor completion.
95
+ from flashalpha import DataAsOf
96
+ stamps: DataAsOf = gex["data_as_of"]
97
+ ```
98
+
99
+ | Field | Feed | Expected cadence |
100
+ |---|---|---|
101
+ | `node` | Which node answered | Nodes hydrate independently |
102
+ | `equity_feed` | Equity and ETF spot quotes | seconds, during market hours |
103
+ | `equity_options_feed` | Equity and ETF option quotes | seconds, during market hours |
104
+ | `index_feed` | Index spot (SPX, RUT, VIX and the other index roots) | seconds, during market hours |
105
+ | `index_options_feed` | Index option quotes | seconds, during market hours |
106
+ | `futures_feed` | Futures prices | seconds, during the futures session |
107
+ | `futures_options_feed` | Futures option quotes | seconds, during the futures session |
108
+ | `flow_feed` | Classified options and stock trade tape | seconds, during market hours |
109
+ | `oi_feed` | Settled open interest | daily, dated to the prior 16:00 ET close |
110
+ | `macro_feed` | VIX, VVIX, SKEW, MOVE, SPX, Fear & Greed | minutes; reports its OLDEST component |
111
+
112
+ ### How to read it
113
+
114
+ - **Check the feeds your call depends on.** A GEX call on an equity is answered from
115
+ `equity_feed`, `equity_options_feed` and `oi_feed`. `futures_feed` being `null` in that
116
+ response says nothing about the answer.
117
+ - **Compare against the cadence, not the clock.** `oi_feed` at the previous session's
118
+ close is correct: settled open interest is published once per session, so on a Monday
119
+ the newest figure that exists is Friday's. An options feed an hour behind during the
120
+ regular session is not correct.
121
+ - **`null` means "not seen on this node", not "broken".** A node that has never been
122
+ asked for a futures symbol has never opened that feed.
123
+ - **Spot and options are separate on purpose.** They arrive over different pipes and can
124
+ fail independently.
125
+ - **It evidences feed activity, not per-contract freshness.** An illiquid strike may not
126
+ have quoted for hours while its feed is healthy.
127
+ - **`data_as_of` is not `as_of`.** `as_of` is response-generation time or the newest
128
+ contract in the payload, depending on the endpoint. `data_as_of` describes the feeds
129
+ behind it.
130
+
131
+ ### Bare-array endpoints
132
+
133
+ A few endpoints return a bare JSON array, which has nowhere to put an envelope in the
134
+ body. The API sends the same information in the `X-Data-As-Of` and `X-Endpoint-Version`
135
+ response headers instead - but this client returns the parsed body only and does not
136
+ surface response headers, so the envelope is **not reachable through those methods**.
137
+ Call the HTTP endpoint directly if you need provenance for one of them.
138
+
139
+ Full reference: <https://flashalpha.com/docs/lab-api-overview#response-envelope> and the
140
+ methodology whitepaper at <https://flashalpha.com/methodology#freshness-reporting>.
141
+
34
142
  ## Features
35
143
 
36
144
  ### Live Options Screener
@@ -85,7 +193,8 @@ chex = fa.chex("NVDA") # Charm exposure
85
193
  levels = fa.exposure_levels("SPY") # Key levels
86
194
  print(f"Call wall: {levels['levels']['call_wall']}")
87
195
  print(f"Put wall: {levels['levels']['put_wall']}")
88
- print(f"Gamma flip: {levels['levels']['gamma_flip']}")
196
+ print(f"Gamma flip: {levels['levels']['gamma_flip']} "
197
+ f"({levels['levels']['gamma_flip_status']})")
89
198
 
90
199
  summary = fa.exposure_summary("SPY") # Full summary (Growth+)
91
200
  narrative = fa.narrative("SPY") # AI narrative (Growth+)
@@ -330,6 +439,7 @@ Get your API key at **[flashalpha.com](https://flashalpha.com)**
330
439
  | `fa.strategy_skew(symbol)` | Strategy signal: skew richness | Growth+ |
331
440
  | `fa.strategy_term_structure(symbol)` | Strategy signal: IV term-structure slope | Growth+ |
332
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+ |
333
443
  | `fa.earnings_calendar(...)` | Upcoming earnings calendar | Growth+ |
334
444
  | `fa.earnings_expected_move(symbol)` | Earnings implied-move decomposition | Growth+ |
335
445
  | `fa.earnings_history(symbol)` | Past earnings: surprises, moves, IV crush | Growth+ |
@@ -384,7 +494,7 @@ calculator and stock quotes. Paid tiers add:
384
494
  - **DEX, VEX (vanna) and CHEX (charm) exposure, plus max pain** — from the **Basic tier**
385
495
  ($79/mo), with ETF and index symbols.
386
496
  - **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**,
497
+ - **Point-in-time replay since 2017, SVI vol surfaces, VRP analytics, higher-order Greeks**,
388
498
  uncached and unlimited — the **Alpha tier** ($1,499/mo). FlashAlpha is one of the only
389
499
  public APIs publishing aggregate vanna and charm exposure across the full universe, with
390
500
  no look-ahead and no training-serving skew.
@@ -4,8 +4,8 @@ build-backend = "hatchling.build"
4
4
 
5
5
  [project]
6
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."
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",
@@ -10,6 +10,7 @@ from .exceptions import (
10
10
  TierRestrictedError,
11
11
  )
12
12
  from .types import (
13
+ DataAsOf,
13
14
  ExposureSummaryExposures,
14
15
  ExposureSummaryHedgingEstimate,
15
16
  ExposureSummaryHedgingMove,
@@ -184,6 +185,10 @@ from .types import (
184
185
  StrategyStructure,
185
186
  StrategyRiskFlag,
186
187
  StrategyDataQuality,
188
+ SellWindowCandidate,
189
+ SellWindowLeg,
190
+ SellWindowResponse,
191
+ SellWindowWindow,
187
192
  StrategyDecisionResponse,
188
193
  # ── Earnings ──
189
194
  EarningsCalendarEvent,
@@ -276,8 +281,9 @@ from .types import (
276
281
  VrpHistoryResponse,
277
282
  )
278
283
 
279
- __version__ = "1.2.3"
284
+ __version__ = "1.4.0"
280
285
  __all__ = [
286
+ "DataAsOf",
281
287
  "FlashAlpha",
282
288
  "FlashAlphaError",
283
289
  "AuthenticationError",
@@ -464,6 +470,10 @@ __all__ = [
464
470
  "StrategyStructure",
465
471
  "StrategyRiskFlag",
466
472
  "StrategyDataQuality",
473
+ "SellWindowCandidate",
474
+ "SellWindowLeg",
475
+ "SellWindowResponse",
476
+ "SellWindowWindow",
467
477
  "StrategyDecisionResponse",
468
478
  # ── Earnings ──
469
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(
@@ -1,39 +1,39 @@
1
- """FlashAlpha API exceptions."""
2
-
3
-
4
- class FlashAlphaError(Exception):
5
- """Base exception for FlashAlpha SDK."""
6
-
7
- def __init__(self, message: str, status_code: int | None = None, response: dict | None = None):
8
- super().__init__(message)
9
- self.status_code = status_code
10
- self.response = response
11
-
12
-
13
- class AuthenticationError(FlashAlphaError):
14
- """Raised when the API key is invalid or missing (401)."""
15
-
16
-
17
- class TierRestrictedError(FlashAlphaError):
18
- """Raised when the endpoint requires a higher plan (403)."""
19
-
20
- def __init__(self, message: str, current_plan: str | None = None, required_plan: str | None = None, **kwargs):
21
- super().__init__(message, **kwargs)
22
- self.current_plan = current_plan
23
- self.required_plan = required_plan
24
-
25
-
26
- class NotFoundError(FlashAlphaError):
27
- """Raised when the requested resource is not found (404)."""
28
-
29
-
30
- class RateLimitError(FlashAlphaError):
31
- """Raised when the rate limit is exceeded (429)."""
32
-
33
- def __init__(self, message: str, retry_after: int | None = None, **kwargs):
34
- super().__init__(message, **kwargs)
35
- self.retry_after = retry_after
36
-
37
-
38
- class ServerError(FlashAlphaError):
39
- """Raised on 5xx server errors."""
1
+ """FlashAlpha API exceptions."""
2
+
3
+
4
+ class FlashAlphaError(Exception):
5
+ """Base exception for FlashAlpha SDK."""
6
+
7
+ def __init__(self, message: str, status_code: int | None = None, response: dict | None = None):
8
+ super().__init__(message)
9
+ self.status_code = status_code
10
+ self.response = response
11
+
12
+
13
+ class AuthenticationError(FlashAlphaError):
14
+ """Raised when the API key is invalid or missing (401)."""
15
+
16
+
17
+ class TierRestrictedError(FlashAlphaError):
18
+ """Raised when the endpoint requires a higher plan (403)."""
19
+
20
+ def __init__(self, message: str, current_plan: str | None = None, required_plan: str | None = None, **kwargs):
21
+ super().__init__(message, **kwargs)
22
+ self.current_plan = current_plan
23
+ self.required_plan = required_plan
24
+
25
+
26
+ class NotFoundError(FlashAlphaError):
27
+ """Raised when the requested resource is not found (404)."""
28
+
29
+
30
+ class RateLimitError(FlashAlphaError):
31
+ """Raised when the rate limit is exceeded (429)."""
32
+
33
+ def __init__(self, message: str, retry_after: int | None = None, **kwargs):
34
+ super().__init__(message, **kwargs)
35
+ self.retry_after = retry_after
36
+
37
+
38
+ class ServerError(FlashAlphaError):
39
+ """Raised on 5xx server errors."""