flashalpha 1.4.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.
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.5
2
2
  Name: flashalpha
3
- Version: 1.4.0
3
+ Version: 1.5.0
4
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
@@ -233,6 +233,33 @@ narrative = fa.narrative("SPY") # AI narrative (Gro
233
233
  print(narrative["narrative"]["outlook"])
234
234
  ```
235
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
+
236
263
  ### 0DTE Analytics
237
264
 
238
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.
@@ -442,6 +469,8 @@ Get your API key at **[flashalpha.com](https://flashalpha.com)**
442
469
  | `fa.exposure_term_structure(symbol)` | Exposure aggregated by DTE bucket and expiry | Growth+ |
443
470
  | `fa.exposure_basket(symbols)` | Weighted cross-symbol exposure aggregate | Growth+ |
444
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+ |
445
474
  | `fa.liquidity(symbol)` | Per-expiry execution score and bid-ask spreads | Growth+ |
446
475
  | `fa.skew_term(symbol)` | 25-delta skew and risk-reversal term structure | Growth+ |
447
476
  | `fa.spot_vol_correlation(symbol)` | Spot-vol correlation (20d/60d) | Growth+ |
@@ -201,6 +201,33 @@ narrative = fa.narrative("SPY") # AI narrative (Gro
201
201
  print(narrative["narrative"]["outlook"])
202
202
  ```
203
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
+
204
231
  ### 0DTE Analytics
205
232
 
206
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.
@@ -410,6 +437,8 @@ Get your API key at **[flashalpha.com](https://flashalpha.com)**
410
437
  | `fa.exposure_term_structure(symbol)` | Exposure aggregated by DTE bucket and expiry | Growth+ |
411
438
  | `fa.exposure_basket(symbols)` | Weighted cross-symbol exposure aggregate | Growth+ |
412
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+ |
413
442
  | `fa.liquidity(symbol)` | Per-expiry execution score and bid-ask spreads | Growth+ |
414
443
  | `fa.skew_term(symbol)` | 25-delta skew and risk-reversal term structure | Growth+ |
415
444
  | `fa.spot_vol_correlation(symbol)` | Spot-vol correlation (20d/60d) | Growth+ |
@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
4
4
 
5
5
  [project]
6
6
  name = "flashalpha"
7
- version = "1.4.0"
7
+ version = "1.5.0"
8
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"
@@ -238,6 +238,16 @@ from .types import (
238
238
  ExposureBasketResponse,
239
239
  ExposureOiDiffRow,
240
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,
241
251
  # ── Volatility / Liquidity (additional) ──
242
252
  LiquidityExpiry,
243
253
  LiquidityResponse,
@@ -281,7 +291,7 @@ from .types import (
281
291
  VrpHistoryResponse,
282
292
  )
283
293
 
284
- __version__ = "1.4.0"
294
+ __version__ = "1.5.0"
285
295
  __all__ = [
286
296
  "DataAsOf",
287
297
  "FlashAlpha",
@@ -523,6 +533,16 @@ __all__ = [
523
533
  "ExposureBasketResponse",
524
534
  "ExposureOiDiffRow",
525
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",
526
546
  # ── Volatility / Liquidity (additional) ──
527
547
  "LiquidityExpiry",
528
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,
@@ -89,6 +91,7 @@ if TYPE_CHECKING:
89
91
  StockQuoteResponse,
90
92
  StockSummaryResponse,
91
93
  StrategyDecisionResponse,
94
+ StrikeDependencyResponse,
92
95
  StructureGreeksResponse,
93
96
  StructurePnlResponse,
94
97
  SurfaceResponse,
@@ -113,6 +116,14 @@ def _seg(s: str) -> str:
113
116
  return quote(s, safe="")
114
117
 
115
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
+
116
127
  class FlashAlpha:
117
128
  """Thin wrapper around the FlashAlpha REST API.
118
129
 
@@ -362,6 +373,45 @@ class FlashAlpha:
362
373
  params["topN"] = top_n
363
374
  return self._get(f"/v1/exposure/oi-diff/{_seg(symbol)}", params or None)
364
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
+
365
415
  # ── Volatility / Liquidity (additional) ─────────────────────────
366
416
 
367
417
  def liquidity(self, symbol: str) -> LiquidityResponse:
@@ -5581,3 +5581,170 @@ class SellWindowResponse(TypedDict, total=False):
5581
5581
  # Response envelope, present on every successful response.
5582
5582
  endpoint_version: str
5583
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