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.
- {flashalpha-1.3.0 → flashalpha-1.5.0}/PKG-INFO +67 -3
- {flashalpha-1.3.0 → flashalpha-1.5.0}/README.md +64 -0
- {flashalpha-1.3.0 → flashalpha-1.5.0}/pyproject.toml +7 -2
- {flashalpha-1.3.0 → flashalpha-1.5.0}/src/flashalpha/__init__.py +29 -1
- {flashalpha-1.3.0 → flashalpha-1.5.0}/src/flashalpha/client.py +71 -0
- {flashalpha-1.3.0 → flashalpha-1.5.0}/src/flashalpha/types.py +239 -0
- {flashalpha-1.3.0 → flashalpha-1.5.0}/.gitignore +0 -0
- {flashalpha-1.3.0 → flashalpha-1.5.0}/LICENSE +0 -0
- {flashalpha-1.3.0 → flashalpha-1.5.0}/src/flashalpha/exceptions.py +0 -0
|
@@ -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.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.
|
|
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.
|
|
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
|
|
File without changes
|