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.
- {flashalpha-1.2.3 → flashalpha-1.4.0}/.gitignore +8 -8
- {flashalpha-1.2.3 → flashalpha-1.4.0}/LICENSE +21 -21
- {flashalpha-1.2.3 → flashalpha-1.4.0}/PKG-INFO +116 -6
- {flashalpha-1.2.3 → flashalpha-1.4.0}/README.md +113 -3
- {flashalpha-1.2.3 → flashalpha-1.4.0}/pyproject.toml +7 -2
- {flashalpha-1.2.3 → flashalpha-1.4.0}/src/flashalpha/__init__.py +11 -1
- {flashalpha-1.2.3 → flashalpha-1.4.0}/src/flashalpha/client.py +21 -0
- {flashalpha-1.2.3 → flashalpha-1.4.0}/src/flashalpha/exceptions.py +39 -39
- {flashalpha-1.2.3 → flashalpha-1.4.0}/src/flashalpha/types.py +499 -2
|
@@ -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.
|
|
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
|
-
|
|
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
|
|
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
|
-
|
|
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
|
|
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.
|
|
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.
|
|
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."""
|