flashalpha 1.3.0__tar.gz → 1.4.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- {flashalpha-1.3.0 → flashalpha-1.4.0}/PKG-INFO +38 -3
- {flashalpha-1.3.0 → flashalpha-1.4.0}/README.md +35 -0
- {flashalpha-1.3.0 → flashalpha-1.4.0}/pyproject.toml +7 -2
- {flashalpha-1.3.0 → flashalpha-1.4.0}/src/flashalpha/__init__.py +9 -1
- {flashalpha-1.3.0 → flashalpha-1.4.0}/src/flashalpha/client.py +21 -0
- {flashalpha-1.3.0 → flashalpha-1.4.0}/src/flashalpha/types.py +72 -0
- {flashalpha-1.3.0 → flashalpha-1.4.0}/.gitignore +0 -0
- {flashalpha-1.3.0 → flashalpha-1.4.0}/LICENSE +0 -0
- {flashalpha-1.3.0 → flashalpha-1.4.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.4.0
|
|
4
|
+
Summary: Python SDK for the FlashAlpha options analytics API — live options screener, gamma exposure (GEX), VRP, delta, vanna, charm, greeks, 0DTE analytics, volatility surfaces, the sell-window sell-or-skip call for option sellers, and more.
|
|
5
5
|
Project-URL: Homepage, https://flashalpha.com
|
|
6
6
|
Project-URL: Documentation, https://flashalpha.com/docs
|
|
7
7
|
Project-URL: Repository, https://github.com/FlashAlpha-lab/flashalpha-python
|
|
@@ -9,7 +9,7 @@ Project-URL: Issues, https://github.com/FlashAlpha-lab/flashalpha-python/issues
|
|
|
9
9
|
Author-email: FlashAlpha <tom@flashalpha.com>
|
|
10
10
|
License-Expression: MIT
|
|
11
11
|
License-File: LICENSE
|
|
12
|
-
Keywords: 0dte,SVI,VRP,black-scholes,charm,dealer flow,dealer positioning,delta exposure,finance,gamma exposure,gex,greeks,harvest score,implied volatility,kelly criterion,live options screener,options,options API,options analytics,options data,options screener,quantitative finance,short vol,trading,vanna,variance risk premium,variance swap,vol selling,vol surface,volatility surface,zero dte
|
|
12
|
+
Keywords: 0dte,SVI,VRP,black-scholes,charm,dealer flow,dealer positioning,delta exposure,finance,gamma exposure,gex,greeks,harvest score,implied volatility,kelly criterion,live options screener,option selling,options,options API,options analytics,options data,options screener,premium selling,quantitative finance,sell-window,short premium,short vol,trading,vanna,variance risk premium,variance swap,vol selling,vol surface,volatility surface,when to sell options,zero dte
|
|
13
13
|
Classifier: Development Status :: 3 - Alpha
|
|
14
14
|
Classifier: Intended Audience :: Developers
|
|
15
15
|
Classifier: Intended Audience :: Financial and Insurance Industry
|
|
@@ -74,6 +74,40 @@ Get your free API key at [flashalpha.com](https://flashalpha.com) — no credit
|
|
|
74
74
|
> `gamma_flip_status == "available"` guarantees a number; treat any other value -
|
|
75
75
|
> including codes added in future - as "no level published".
|
|
76
76
|
|
|
77
|
+
## sell-window: should you sell options today?
|
|
78
|
+
|
|
79
|
+
Option sellers get wiped out on a few bad days. sell-window tells you which days to stay out, and on the days it says sell, it hands you the trades: which expiry, which strikes and how to exit. Every session, for SPY, QQQ and IWM. More than 5 million backtests led to this one endpoint.
|
|
80
|
+
|
|
81
|
+
```python
|
|
82
|
+
from flashalpha import FlashAlpha
|
|
83
|
+
|
|
84
|
+
fa = FlashAlpha("YOUR_API_KEY")
|
|
85
|
+
answer = fa.sell_window("SPY")
|
|
86
|
+
|
|
87
|
+
for window in answer["windows"]:
|
|
88
|
+
print(window.get("expiry"), window["action"]) # sell, skip or unavailable
|
|
89
|
+
for trade in window.get("candidates", []):
|
|
90
|
+
print(" ", trade["structure"], trade.get("mid_credit"), trade["exit"])
|
|
91
|
+
```
|
|
92
|
+
|
|
93
|
+
Each of the four windows (the same-day expiry, then the expiries closest to one week, two weeks and one month out) says `sell`, `skip` or `unavailable`. On a sell it lists the trades, with strikes, quotes and the exit rule. On a skip there is nothing to do.
|
|
94
|
+
|
|
95
|
+
| Backtest, 2018 to 2026 | Following sell-window | Selling the same trades every day |
|
|
96
|
+
|---|---|---|
|
|
97
|
+
| Max drawdown at the same trade size | $255k | $959k |
|
|
98
|
+
| Worst month at the same trade size | -$171k | -$307k |
|
|
99
|
+
| Sharpe ratio | 0.76 | 0.61 |
|
|
100
|
+
| Total P&L at the same max drawdown | $3.55M | $2.32M |
|
|
101
|
+
| Worst day at the same max drawdown | -$258k | -$385k |
|
|
102
|
+
|
|
103
|
+
Cut the risk or earn more. Keep your trade size and the deepest drawdown falls 73%. Or size up about 3.8 times, until the deepest drawdown matches, and you earn 53% more. These are two separate choices, not one result.
|
|
104
|
+
|
|
105
|
+
**Plans:** Live answers need Basic or higher through November 2026, and Growth or higher from December 1, 2026. Backtesting any past session needs Alpha or higher. Backtest with [flashalpha-historical-python](https://github.com/FlashAlpha-lab/flashalpha-historical-python).
|
|
106
|
+
|
|
107
|
+
**Read more:** [API docs](https://flashalpha.com/docs/lab-api-strategies-sell-window?utm_source=github&utm_medium=readme&utm_campaign=repo-flashalpha-python&utm_content=sell-window) | [trading guide](https://flashalpha.com/articles/complete-guide-trading-sell-window-spy-qqq-iwm?utm_source=github&utm_medium=readme&utm_campaign=repo-flashalpha-python&utm_content=sell-window) | [every backtested trade](https://flashalpha.com/articles/sell-window-backtest-every-trade-2018-2026?utm_source=github&utm_medium=readme&utm_campaign=repo-flashalpha-python&utm_content=sell-window) | [sell-window in depth](https://github.com/FlashAlpha-lab/flashalpha-python/blob/main/docs/sell-window.md) | [plans](https://flashalpha.com/pricing?utm_source=github&utm_medium=readme&utm_campaign=repo-flashalpha-python&utm_content=sell-window) | [live forward test on Discord](https://discord.gg/UtH22J8df2)
|
|
108
|
+
|
|
109
|
+
*Backtest on SPY, QQQ and IWM, January 2018 to October 2026, at halfway fills and $1 per contract. At one contract set per signal, following it made $945,541 on 20,883 trades; selling every day made $2,321,150 on 56,975. At 3.76 times the contracts, both fell $958,924 at their deepest, and the worst month was -$642,135 against -$307,241. Past results do not guarantee future returns, and short options can lose more than the premium collected. The skip call applies to new trades, so it cannot protect open positions from a sudden shock. This is data, not investment advice.*
|
|
110
|
+
|
|
77
111
|
## Data provenance: `data_as_of`
|
|
78
112
|
|
|
79
113
|
Every successful JSON-object response carries `data_as_of`, reporting when each upstream
|
|
@@ -437,6 +471,7 @@ Get your API key at **[flashalpha.com](https://flashalpha.com)**
|
|
|
437
471
|
| `fa.strategy_skew(symbol)` | Strategy signal: skew richness | Growth+ |
|
|
438
472
|
| `fa.strategy_term_structure(symbol)` | Strategy signal: IV term-structure slope | Growth+ |
|
|
439
473
|
| `fa.strategy_tail_pricing(symbol)` | Strategy signal: tail (deep-wing) pricing | Growth+ |
|
|
474
|
+
| `fa.sell_window(symbol)` | sell-window: should you sell options today? Sell or skip per expiry, with the trades to place (SPY, QQQ, IWM) | Basic+ through Nov 2026, then Growth+ |
|
|
440
475
|
| `fa.earnings_calendar(...)` | Upcoming earnings calendar | Growth+ |
|
|
441
476
|
| `fa.earnings_expected_move(symbol)` | Earnings implied-move decomposition | Growth+ |
|
|
442
477
|
| `fa.earnings_history(symbol)` | Past earnings: surprises, moves, IV crush | Growth+ |
|
|
@@ -42,6 +42,40 @@ Get your free API key at [flashalpha.com](https://flashalpha.com) — no credit
|
|
|
42
42
|
> `gamma_flip_status == "available"` guarantees a number; treat any other value -
|
|
43
43
|
> including codes added in future - as "no level published".
|
|
44
44
|
|
|
45
|
+
## sell-window: should you sell options today?
|
|
46
|
+
|
|
47
|
+
Option sellers get wiped out on a few bad days. sell-window tells you which days to stay out, and on the days it says sell, it hands you the trades: which expiry, which strikes and how to exit. Every session, for SPY, QQQ and IWM. More than 5 million backtests led to this one endpoint.
|
|
48
|
+
|
|
49
|
+
```python
|
|
50
|
+
from flashalpha import FlashAlpha
|
|
51
|
+
|
|
52
|
+
fa = FlashAlpha("YOUR_API_KEY")
|
|
53
|
+
answer = fa.sell_window("SPY")
|
|
54
|
+
|
|
55
|
+
for window in answer["windows"]:
|
|
56
|
+
print(window.get("expiry"), window["action"]) # sell, skip or unavailable
|
|
57
|
+
for trade in window.get("candidates", []):
|
|
58
|
+
print(" ", trade["structure"], trade.get("mid_credit"), trade["exit"])
|
|
59
|
+
```
|
|
60
|
+
|
|
61
|
+
Each of the four windows (the same-day expiry, then the expiries closest to one week, two weeks and one month out) says `sell`, `skip` or `unavailable`. On a sell it lists the trades, with strikes, quotes and the exit rule. On a skip there is nothing to do.
|
|
62
|
+
|
|
63
|
+
| Backtest, 2018 to 2026 | Following sell-window | Selling the same trades every day |
|
|
64
|
+
|---|---|---|
|
|
65
|
+
| Max drawdown at the same trade size | $255k | $959k |
|
|
66
|
+
| Worst month at the same trade size | -$171k | -$307k |
|
|
67
|
+
| Sharpe ratio | 0.76 | 0.61 |
|
|
68
|
+
| Total P&L at the same max drawdown | $3.55M | $2.32M |
|
|
69
|
+
| Worst day at the same max drawdown | -$258k | -$385k |
|
|
70
|
+
|
|
71
|
+
Cut the risk or earn more. Keep your trade size and the deepest drawdown falls 73%. Or size up about 3.8 times, until the deepest drawdown matches, and you earn 53% more. These are two separate choices, not one result.
|
|
72
|
+
|
|
73
|
+
**Plans:** Live answers need Basic or higher through November 2026, and Growth or higher from December 1, 2026. Backtesting any past session needs Alpha or higher. Backtest with [flashalpha-historical-python](https://github.com/FlashAlpha-lab/flashalpha-historical-python).
|
|
74
|
+
|
|
75
|
+
**Read more:** [API docs](https://flashalpha.com/docs/lab-api-strategies-sell-window?utm_source=github&utm_medium=readme&utm_campaign=repo-flashalpha-python&utm_content=sell-window) | [trading guide](https://flashalpha.com/articles/complete-guide-trading-sell-window-spy-qqq-iwm?utm_source=github&utm_medium=readme&utm_campaign=repo-flashalpha-python&utm_content=sell-window) | [every backtested trade](https://flashalpha.com/articles/sell-window-backtest-every-trade-2018-2026?utm_source=github&utm_medium=readme&utm_campaign=repo-flashalpha-python&utm_content=sell-window) | [sell-window in depth](https://github.com/FlashAlpha-lab/flashalpha-python/blob/main/docs/sell-window.md) | [plans](https://flashalpha.com/pricing?utm_source=github&utm_medium=readme&utm_campaign=repo-flashalpha-python&utm_content=sell-window) | [live forward test on Discord](https://discord.gg/UtH22J8df2)
|
|
76
|
+
|
|
77
|
+
*Backtest on SPY, QQQ and IWM, January 2018 to October 2026, at halfway fills and $1 per contract. At one contract set per signal, following it made $945,541 on 20,883 trades; selling every day made $2,321,150 on 56,975. At 3.76 times the contracts, both fell $958,924 at their deepest, and the worst month was -$642,135 against -$307,241. Past results do not guarantee future returns, and short options can lose more than the premium collected. The skip call applies to new trades, so it cannot protect open positions from a sudden shock. This is data, not investment advice.*
|
|
78
|
+
|
|
45
79
|
## Data provenance: `data_as_of`
|
|
46
80
|
|
|
47
81
|
Every successful JSON-object response carries `data_as_of`, reporting when each upstream
|
|
@@ -405,6 +439,7 @@ Get your API key at **[flashalpha.com](https://flashalpha.com)**
|
|
|
405
439
|
| `fa.strategy_skew(symbol)` | Strategy signal: skew richness | Growth+ |
|
|
406
440
|
| `fa.strategy_term_structure(symbol)` | Strategy signal: IV term-structure slope | Growth+ |
|
|
407
441
|
| `fa.strategy_tail_pricing(symbol)` | Strategy signal: tail (deep-wing) pricing | Growth+ |
|
|
442
|
+
| `fa.sell_window(symbol)` | sell-window: should you sell options today? Sell or skip per expiry, with the trades to place (SPY, QQQ, IWM) | Basic+ through Nov 2026, then Growth+ |
|
|
408
443
|
| `fa.earnings_calendar(...)` | Upcoming earnings calendar | Growth+ |
|
|
409
444
|
| `fa.earnings_expected_move(symbol)` | Earnings implied-move decomposition | Growth+ |
|
|
410
445
|
| `fa.earnings_history(symbol)` | Past earnings: surprises, moves, IV crush | Growth+ |
|
|
@@ -4,8 +4,8 @@ build-backend = "hatchling.build"
|
|
|
4
4
|
|
|
5
5
|
[project]
|
|
6
6
|
name = "flashalpha"
|
|
7
|
-
version = "1.
|
|
8
|
-
description = "Python SDK for the FlashAlpha options analytics API — live options screener, gamma exposure (GEX), VRP, delta, vanna, charm, greeks, 0DTE analytics, volatility surfaces, and more."
|
|
7
|
+
version = "1.4.0"
|
|
8
|
+
description = "Python SDK for the FlashAlpha options analytics API — live options screener, gamma exposure (GEX), VRP, delta, vanna, charm, greeks, 0DTE analytics, volatility surfaces, the sell-window sell-or-skip call for option sellers, and more."
|
|
9
9
|
readme = "README.md"
|
|
10
10
|
license = "MIT"
|
|
11
11
|
requires-python = ">=3.10"
|
|
@@ -42,6 +42,11 @@ keywords = [
|
|
|
42
42
|
"short vol",
|
|
43
43
|
"vol selling",
|
|
44
44
|
"dealer flow",
|
|
45
|
+
"sell-window",
|
|
46
|
+
"option selling",
|
|
47
|
+
"short premium",
|
|
48
|
+
"premium selling",
|
|
49
|
+
"when to sell options",
|
|
45
50
|
]
|
|
46
51
|
classifiers = [
|
|
47
52
|
"Development Status :: 3 - Alpha",
|
|
@@ -185,6 +185,10 @@ from .types import (
|
|
|
185
185
|
StrategyStructure,
|
|
186
186
|
StrategyRiskFlag,
|
|
187
187
|
StrategyDataQuality,
|
|
188
|
+
SellWindowCandidate,
|
|
189
|
+
SellWindowLeg,
|
|
190
|
+
SellWindowResponse,
|
|
191
|
+
SellWindowWindow,
|
|
188
192
|
StrategyDecisionResponse,
|
|
189
193
|
# ── Earnings ──
|
|
190
194
|
EarningsCalendarEvent,
|
|
@@ -277,7 +281,7 @@ from .types import (
|
|
|
277
281
|
VrpHistoryResponse,
|
|
278
282
|
)
|
|
279
283
|
|
|
280
|
-
__version__ = "1.
|
|
284
|
+
__version__ = "1.4.0"
|
|
281
285
|
__all__ = [
|
|
282
286
|
"DataAsOf",
|
|
283
287
|
"FlashAlpha",
|
|
@@ -466,6 +470,10 @@ __all__ = [
|
|
|
466
470
|
"StrategyStructure",
|
|
467
471
|
"StrategyRiskFlag",
|
|
468
472
|
"StrategyDataQuality",
|
|
473
|
+
"SellWindowCandidate",
|
|
474
|
+
"SellWindowLeg",
|
|
475
|
+
"SellWindowResponse",
|
|
476
|
+
"SellWindowWindow",
|
|
469
477
|
"StrategyDecisionResponse",
|
|
470
478
|
# ── Earnings ──
|
|
471
479
|
"EarningsCalendarEvent",
|
|
@@ -83,6 +83,7 @@ if TYPE_CHECKING:
|
|
|
83
83
|
RealizedVolatilityResponse,
|
|
84
84
|
ScreenerFieldsResponse,
|
|
85
85
|
ScreenerResponse,
|
|
86
|
+
SellWindowResponse,
|
|
86
87
|
SkewTermResponse,
|
|
87
88
|
SpotVolCorrelationResponse,
|
|
88
89
|
StockQuoteResponse,
|
|
@@ -1169,6 +1170,26 @@ class FlashAlpha:
|
|
|
1169
1170
|
"""Scores tail (deep-wing) pricing richness. Requires Growth+."""
|
|
1170
1171
|
return self._strategy("tail-pricing", symbol, expiry=expiry)
|
|
1171
1172
|
|
|
1173
|
+
# ── sell-window (own response shape) ────────────────────────────
|
|
1174
|
+
|
|
1175
|
+
def sell_window(self, symbol: str) -> SellWindowResponse:
|
|
1176
|
+
"""Should you sell options today? One answer per session for SPY, QQQ and IWM.
|
|
1177
|
+
|
|
1178
|
+
Built from more than 5 million backtests. For four listed expiries (same day,
|
|
1179
|
+
then the expiries closest to one week, two weeks and one month out) each
|
|
1180
|
+
window says ``sell``, ``skip`` or ``unavailable``. On a sell it lists the
|
|
1181
|
+
trades to place, with strikes, quotes and the exit rule. On a skip there is
|
|
1182
|
+
nothing to do. Treat ``unavailable`` like a skip.
|
|
1183
|
+
|
|
1184
|
+
The answer is set from the previous session's close and stays fixed for the
|
|
1185
|
+
session. Any symbol other than SPY, QQQ or IWM returns every window as
|
|
1186
|
+
``unavailable``. Requires Basic+ through November 2026, Growth+ from
|
|
1187
|
+
December 1, 2026. Backtest any session with ``flashalpha-historical`` (Alpha+).
|
|
1188
|
+
|
|
1189
|
+
Docs: https://flashalpha.com/docs/lab-api-strategies-sell-window
|
|
1190
|
+
"""
|
|
1191
|
+
return self._get(f"/v1/strategies/sell-window/{_seg(symbol)}")
|
|
1192
|
+
|
|
1172
1193
|
# ── Earnings Analytics ──────────────────────────────────────────
|
|
1173
1194
|
|
|
1174
1195
|
def earnings_calendar(
|
|
@@ -5509,3 +5509,75 @@ class ScreenerFieldsResponse(TypedDict, total=False):
|
|
|
5509
5509
|
# Response envelope, present on every successful response.
|
|
5510
5510
|
endpoint_version: str
|
|
5511
5511
|
data_as_of: DataAsOf
|
|
5512
|
+
|
|
5513
|
+
# ── sell-window ─────────────────────────────────────────────────────
|
|
5514
|
+
#
|
|
5515
|
+
# Own response shape: not the StrategyDecisionResponse envelope.
|
|
5516
|
+
|
|
5517
|
+
|
|
5518
|
+
class SellWindowLeg(TypedDict, total=False):
|
|
5519
|
+
"""One contract of a sell-window trade."""
|
|
5520
|
+
|
|
5521
|
+
side: Literal["sell", "buy"]
|
|
5522
|
+
# Contracts per unit of the trade: 2 for the sold body of put_bwb, otherwise 1.
|
|
5523
|
+
quantity: int
|
|
5524
|
+
type: Literal["call", "put"]
|
|
5525
|
+
strike: float
|
|
5526
|
+
# The contract's own delta when the answer was served (negative for puts).
|
|
5527
|
+
delta: float
|
|
5528
|
+
bid: float
|
|
5529
|
+
ask: float
|
|
5530
|
+
|
|
5531
|
+
|
|
5532
|
+
class SellWindowCandidate(TypedDict, total=False):
|
|
5533
|
+
"""One trade to consider on a sell window."""
|
|
5534
|
+
|
|
5535
|
+
structure: Literal[
|
|
5536
|
+
"short_put",
|
|
5537
|
+
"short_call",
|
|
5538
|
+
"short_strangle",
|
|
5539
|
+
"short_straddle",
|
|
5540
|
+
"tail_hedged_put",
|
|
5541
|
+
"put_credit_spread",
|
|
5542
|
+
"put_bwb",
|
|
5543
|
+
]
|
|
5544
|
+
# expiry: hold to expiration. tp50: close at half of the credit, else hold.
|
|
5545
|
+
exit: Literal["expiry", "tp50"]
|
|
5546
|
+
# Absent when no option chain could be loaded for the answer.
|
|
5547
|
+
legs: List[SellWindowLeg]
|
|
5548
|
+
# Net credit per share at mid. Multiply by 100 for one unit in dollars.
|
|
5549
|
+
mid_credit: float
|
|
5550
|
+
|
|
5551
|
+
|
|
5552
|
+
class SellWindowWindow(TypedDict, total=False):
|
|
5553
|
+
"""One of the four windows, named by its listed expiry."""
|
|
5554
|
+
|
|
5555
|
+
# Absent when no listed expiry falls in the window's range.
|
|
5556
|
+
expiry: str
|
|
5557
|
+
days_to_expiry: int
|
|
5558
|
+
action: Literal["sell", "skip", "unavailable"]
|
|
5559
|
+
# Present only when action is "sell". Can be empty: a trade whose legs
|
|
5560
|
+
# cannot all be found in the chain is left out.
|
|
5561
|
+
candidates: List[SellWindowCandidate]
|
|
5562
|
+
|
|
5563
|
+
|
|
5564
|
+
class SellWindowResponse(TypedDict, total=False):
|
|
5565
|
+
"""sell-window answer from ``GET /v1/strategies/sell-window/{symbol}``.
|
|
5566
|
+
|
|
5567
|
+
``spot``, ``quoted_at`` and ``legs_indicative`` are present when a window sells
|
|
5568
|
+
and an option chain could be loaded.
|
|
5569
|
+
When ``legs_indicative`` is true the quotes are from before that session's
|
|
5570
|
+
09:35 ET entry: call again at or after 09:35 ET for the strikes to trade.
|
|
5571
|
+
"""
|
|
5572
|
+
|
|
5573
|
+
symbol: str
|
|
5574
|
+
# yyyy-MM-dd. The trading session the answer applies to.
|
|
5575
|
+
session: str
|
|
5576
|
+
spot: float
|
|
5577
|
+
quoted_at: str
|
|
5578
|
+
legs_indicative: bool
|
|
5579
|
+
# Always four entries: same day, then about one week, two weeks, one month.
|
|
5580
|
+
windows: List[SellWindowWindow]
|
|
5581
|
+
# Response envelope, present on every successful response.
|
|
5582
|
+
endpoint_version: str
|
|
5583
|
+
data_as_of: DataAsOf
|
|
File without changes
|
|
File without changes
|
|
File without changes
|