flashalpha 1.2.2__tar.gz → 1.3.0__tar.gz

{flashalpha-1.2.2 → flashalpha-1.3.0}/.gitignore

@@ -211,11 +211,11 @@ cython_debug/
 marimo/_static/
 marimo/_lsp/
 __marimo__/
-
-# Sandbox / agent / harness caches (cross-ecosystem — defensive)
-.dotnet/
-.gocache/
-.gopath/
-.m2/
-.review-artifacts/
-.agent-tools/
+
+# Sandbox / agent / harness caches (cross-ecosystem — defensive)
+.dotnet/
+.gocache/
+.gopath/
+.m2/
+.review-artifacts/
+.agent-tools/

{flashalpha-1.2.2 → flashalpha-1.3.0}/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2026 FlashAlpha
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+MIT License
+
+Copyright (c) 2026 FlashAlpha
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

{flashalpha-1.2.2 → flashalpha-1.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: flashalpha
-Version: 1.2.2
+Version: 1.3.0
 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.
 Project-URL: Homepage, https://flashalpha.com
 Project-URL: Documentation, https://flashalpha.com/docs
@@ -55,7 +55,9 @@ fa = FlashAlpha("YOUR_API_KEY")  # Get a free key at flashalpha.com
 # Gamma exposure by strike
 gex = fa.gex("SPY")
 print(f"Net GEX: ${gex['net_gex']:,.0f}")
-print(f"Gamma flip: {gex['gamma_flip']}")
+# gamma_flip is None unless gamma_flip_status == "available" -- never format it
+# as a number without checking first.
+print(f"Gamma flip: {gex['gamma_flip']} ({gex['gamma_flip_status']})")
 
 for strike in gex["strikes"][:5]:
     print(f"  {strike['strike']}: net ${strike['net_gex']:,.0f}")
@@ -63,6 +65,78 @@ for strike in gex["strikes"][:5]:
 
 Get your free API key at [flashalpha.com](https://flashalpha.com) — no credit card required.
 
+> **`gamma_flip` is nullable.** A dealer gamma flip is only published when the
+> level is well-determined, which is a minority of chains. When it is withheld,
+> `gamma_flip` is `null`, `regime` is `"unknown"`, and `gamma_flip_status` carries
+> a reason code (`no_boundary`, `insufficient_local_coverage`,
+> `insufficient_quote_quality`, `sensitive_root`, `uncertain_root_path`,
+> `stored_sign_mismatch`, `search_budget`, `quality_budget`). Only
+> `gamma_flip_status == "available"` guarantees a number; treat any other value -
+> including codes added in future - as "no level published".
+
+## Data provenance: `data_as_of`
+
+Every successful JSON-object response carries `data_as_of`, reporting when each upstream
+feed last delivered to the node that answered, plus `endpoint_version` identifying the
+deployment that produced it. That is every method on this client except the handful that
+return a bare JSON array - see the note at the end of this section.
+
+```python
+gex = fa.gex("SPY")
+
+print(gex["data_as_of"]["equity_options_feed"])  # 2026-08-25T18:48:58.204Z
+print(gex["data_as_of"]["oi_feed"])              # 2026-08-24T20:00:00.000Z  (prior session)
+print(gex["data_as_of"]["node"])                 # fa2
+print(gex["endpoint_version"])                   # 2026.08.25
+
+# Typed: DataAsOf is exported for annotation and editor completion.
+from flashalpha import DataAsOf
+stamps: DataAsOf = gex["data_as_of"]
+```
+
+| Field | Feed | Expected cadence |
+|---|---|---|
+| `node` | Which node answered | Nodes hydrate independently |
+| `equity_feed` | Equity and ETF spot quotes | seconds, during market hours |
+| `equity_options_feed` | Equity and ETF option quotes | seconds, during market hours |
+| `index_feed` | Index spot (SPX, RUT, VIX and the other index roots) | seconds, during market hours |
+| `index_options_feed` | Index option quotes | seconds, during market hours |
+| `futures_feed` | Futures prices | seconds, during the futures session |
+| `futures_options_feed` | Futures option quotes | seconds, during the futures session |
+| `flow_feed` | Classified options and stock trade tape | seconds, during market hours |
+| `oi_feed` | Settled open interest | daily, dated to the prior 16:00 ET close |
+| `macro_feed` | VIX, VVIX, SKEW, MOVE, SPX, Fear & Greed | minutes; reports its OLDEST component |
+
+### How to read it
+
+- **Check the feeds your call depends on.** A GEX call on an equity is answered from
+  `equity_feed`, `equity_options_feed` and `oi_feed`. `futures_feed` being `null` in that
+  response says nothing about the answer.
+- **Compare against the cadence, not the clock.** `oi_feed` at the previous session's
+  close is correct: settled open interest is published once per session, so on a Monday
+  the newest figure that exists is Friday's. An options feed an hour behind during the
+  regular session is not correct.
+- **`null` means "not seen on this node", not "broken".** A node that has never been
+  asked for a futures symbol has never opened that feed.
+- **Spot and options are separate on purpose.** They arrive over different pipes and can
+  fail independently.
+- **It evidences feed activity, not per-contract freshness.** An illiquid strike may not
+  have quoted for hours while its feed is healthy.
+- **`data_as_of` is not `as_of`.** `as_of` is response-generation time or the newest
+  contract in the payload, depending on the endpoint. `data_as_of` describes the feeds
+  behind it.
+
+### Bare-array endpoints
+
+A few endpoints return a bare JSON array, which has nowhere to put an envelope in the
+body. The API sends the same information in the `X-Data-As-Of` and `X-Endpoint-Version`
+response headers instead - but this client returns the parsed body only and does not
+surface response headers, so the envelope is **not reachable through those methods**.
+Call the HTTP endpoint directly if you need provenance for one of them.
+
+Full reference: <https://flashalpha.com/docs/lab-api-overview#response-envelope> and the
+methodology whitepaper at <https://flashalpha.com/methodology#freshness-reporting>.
+
 ## Features
 
 ### Live Options Screener
@@ -117,7 +191,8 @@ chex = fa.chex("NVDA")                                     # Charm exposure
 levels = fa.exposure_levels("SPY")                          # Key levels
 print(f"Call wall: {levels['levels']['call_wall']}")
 print(f"Put wall: {levels['levels']['put_wall']}")
-print(f"Gamma flip: {levels['levels']['gamma_flip']}")
+print(f"Gamma flip: {levels['levels']['gamma_flip']} "
+      f"({levels['levels']['gamma_flip_status']})")
 
 summary = fa.exposure_summary("SPY")                        # Full summary (Growth+)
 narrative = fa.narrative("SPY")                              # AI narrative (Growth+)
@@ -373,16 +448,16 @@ Get your API key at **[flashalpha.com](https://flashalpha.com)**
 | `fa.structure_pnl(legs, ...)` | Multi-leg at-expiry P&L, breakevens, max P/L | Basic+ |
 | `fa.structure_greeks(legs, spot=...)` | Aggregate multi-leg Black-Scholes greeks | Basic+ |
 
-## Futures (CME equity-index)
+## Futures (CME)
 
-FlashAlpha serves the full options-analytics stack for **CME equity-index futures** — **`ES=F`** (E-mini S&P 500) and **`NQ=F`** (E-mini Nasdaq-100). Options-on-futures are priced with **Black-76** (forward-priced) using the correct CME contract multipliers. Everything that works for an equity works for futures: gamma exposure (GEX), DEX, VEX, CHEX, key levels, max pain, the IV surface, exposure summary, narrative, and live flow.
+FlashAlpha serves the full options-analytics stack for **CME futures** across six complexes - equity index (`ES=F`, `NQ=F`, `RTY=F`, `YM=F`, `MES=F`, `MNQ=F`), metals (`GC=F` gold, `SI=F` silver), energy (`CL=F` crude oil, `NG=F` natural gas), the Treasury curve (`ZT=F`, `ZF=F`, `ZN=F`, `TN=F`, `ZB=F`, `UB=F`), grains (`ZC=F` corn, `ZS=F` soybeans, `ZW=F` wheat) and crypto (`BTC=F` bitcoin). Options-on-futures are priced with **Black-76** (forward-priced) and each root carries its own CME contract multiplier, so notionals and dollar gamma are in real dollars. Note the quote conventions: Treasuries are quoted in points of par and grains in cents, so their multipliers are the contract size divided by 100. Everything that works for an equity works for futures: gamma exposure (GEX), DEX, VEX, CHEX, key levels, max pain, the IV surface, exposure summary, narrative, and live flow.
 
 ```python
 gex = fa.gex("ES=F")                                        # Gamma exposure for the E-mini S&P 500 future
 print(f"Net GEX: ${gex['net_gex']:,.0f}")
 ```
 
-Use the `=F` suffix — bare `ES`/`NQ` are equities, not futures. In raw REST paths URL-encode the `=` as `%3D` (e.g. `GET /v1/exposure/gex/ES%3DF`); SDK methods take the plain string `"ES=F"`. Historical replay for futures is coming; live analytics are available now.
+Use the `=F` suffix - bare `ES`/`NQ` are equities, not futures. In raw REST paths URL-encode the `=` as `%3D` (e.g. `GET /v1/exposure/gex/GC%3DF`); SDK methods take the plain string `"GC=F"`. Futures symbols require the Growth plan or higher. Historical replay for futures is coming; live analytics are available now.
 
 ## Other SDKs
 
@@ -416,7 +491,7 @@ calculator and stock quotes. Paid tiers add:
 - **DEX, VEX (vanna) and CHEX (charm) exposure, plus max pain** — from the **Basic tier**
   ($79/mo), with ETF and index symbols.
 - **Full-chain GEX, 0DTE and flow analytics** — from the **Growth tier** ($299/mo).
-- **Point-in-time replay since 2018, SVI vol surfaces, VRP analytics, higher-order Greeks**,
+- **Point-in-time replay since 2017, SVI vol surfaces, VRP analytics, higher-order Greeks**,
   uncached and unlimited — the **Alpha tier** ($1,499/mo). FlashAlpha is one of the only
   public APIs publishing aggregate vanna and charm exposure across the full universe, with
   no look-ahead and no training-serving skew.