From 4dc2909d4ed0cc924ab6956a2b6ddc6ab14bd917 Mon Sep 17 00:00:00 2001 From: Tomasz Dobrowolski Date: Sat, 7 Nov 2026 14:15:32 +0200 Subject: [PATCH 1/3] docs: remove the paid plans' cache window The 15-second and about-1-second cache windows are being scrapped. Only the Free plan's 15-minute window stays in the docs. Co-Authored-By: Claude Opus 5.5 --- docs/api.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/api.md b/docs/api.md index faaed15..c1fc8cb 100644 --- a/docs/api.md +++ b/docs/api.md @@ -37,7 +37,7 @@ curl -H "X-Api-Key: YOUR_API_KEY" https://lab.flashalpha.com/v1/exposure/gex/SPY **3. Explore the response** — you'll get gamma exposure by strike with OI, volume, and day-over-day changes. -That's it. Every US equity and ETF symbol is supported. Data is fetched on-demand with a 15-second cache. +That's it. Every US equity and ETF symbol is supported. Data is fetched on-demand. Free responses may be cached for up to 15 minutes. --- @@ -3794,7 +3794,7 @@ curl -H "X-Api-Key: YOUR_API_KEY" https://lab.flashalpha.com/v1/symbols { "symbols": ["SPY", "QQQ"], "count": 2, - "note": "Any US equity or ETF symbol is supported. All data is fetched on-demand with a 15-second cache.", + "note": "Any US equity or ETF symbol is supported. All data is fetched on-demand. Free responses may be cached for up to 15 minutes.", "last_updated": "2026-02-28T16:30:45Z" } ``` @@ -5900,4 +5900,4 @@ All endpoints return consistent error responses. - Implied volatility is smoothed via **SVI** (Stochastic Volatility Inspired) parameterization - Dealer position is the **opposite** of net exposure (dealers are counterparty) - OI changes are **day-over-day** deltas (when prior-day snapshot is available) -- Any US equity or ETF symbol is supported — data is fetched on-demand and cached for 15 seconds +- Any US equity or ETF symbol is supported — data is fetched on-demand, and Free responses may be cached for up to 15 minutes From f66449050ad218b1f0ce363b8701d2942dfd0eb6 Mon Sep 17 00:00:00 2001 From: Tomasz Dobrowolski Date: Sat, 7 Nov 2026 14:50:01 +0200 Subject: [PATCH 2/3] docs: drop "uncached" from the Alpha pitch Co-Authored-By: Claude Opus 5.5 --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 9c354f1..4bf5bf0 100644 --- a/README.md +++ b/README.md @@ -495,7 +495,7 @@ calculator and stock quotes. Paid tiers add: ($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 2017, SVI vol surfaces, VRP analytics, higher-order Greeks**, - uncached and unlimited — the **Alpha tier** ($1,499/mo). FlashAlpha is one of the only + 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. From 33a84b3454d4910946fbf5f9101be55e15e57b19 Mon Sep 17 00:00:00 2001 From: Tomasz Dobrowolski Date: Mon, 9 Nov 2026 10:42:18 +0200 Subject: [PATCH 3/3] docs: remove cache mentions The owner decided on 2026-11-09 that customer copy should not mention caching. Paid plans are live, a Free API key gets delayed data, and the stock summary without an API key is the previous trading session's snapshot. The cross-symbol flow scans now say they refresh about every 30 seconds. - docs/api.md: drops the Free 15-minute window and the cached surface, summary, flow-scan and /v1/symbols wording. The /v1/symbols note example matches the API's new text. - README.md, AGENTS.md, llms.txt: the anonymous summary is the previous trading session's snapshot, and fa.symbols() lists symbols with live data. - src/flashalpha/types.py: docstrings and comments say the same, and the flow leaderboards and outliers refresh about every 30 seconds. Co-Authored-By: Claude Opus 5.5 --- AGENTS.md | 2 +- README.md | 2 +- docs/api.md | 28 ++++++++++++++-------------- llms.txt | 4 ++-- src/flashalpha/types.py | 19 ++++++++++++------- 5 files changed, 30 insertions(+), 25 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index b96e8dd..2f8f1a5 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -200,7 +200,7 @@ summary: StockSummaryResponse = client.stock_summary("SPY") ## Auth and tiers - API keys: https://flashalpha.com (sign up, then dashboard). -- Free tier: `stock_summary` returns a previous-day cached snapshot +- Free tier: `stock_summary` returns the previous trading session's snapshot without a key — useful for demos, docs, and LLM tool-call examples without burning a key. - Tier-restricted endpoints raise `TierRestrictedError` (HTTP 403). diff --git a/README.md b/README.md index 4bf5bf0..4d860d9 100644 --- a/README.md +++ b/README.md @@ -334,7 +334,7 @@ hist_opt = fa.historical_option_quote( ```python tickers = fa.tickers() # All available stock tickers chain = fa.options("SPY") # Option chain metadata -symbols = fa.symbols() # Symbols with live cached data +symbols = fa.symbols() # Symbols with live data account = fa.account() # Plan, usage, quota health = fa.health() # API health check (public) ``` diff --git a/docs/api.md b/docs/api.md index c1fc8cb..b57f984 100644 --- a/docs/api.md +++ b/docs/api.md @@ -37,7 +37,7 @@ curl -H "X-Api-Key: YOUR_API_KEY" https://lab.flashalpha.com/v1/exposure/gex/SPY **3. Explore the response** — you'll get gamma exposure by strike with OI, volume, and day-over-day changes. -That's it. Every US equity and ETF symbol is supported. Data is fetched on-demand. Free responses may be cached for up to 15 minutes. +That's it. Every US equity and ETF symbol is supported. Data is fetched on-demand. Paid plans serve live data. A Free API key gets delayed data. --- @@ -65,7 +65,7 @@ https://lab.flashalpha.com/v1/symbols?apiKey=YOUR_API_KEY - [`GET /optionquote/{ticker}`](#get-optionquoteticker) — Option quotes with greeks `Growth+` - [`GET /v1/surface/{symbol}`](#get-v1surfacesymbol) — Vol surface grid `Public` - [`GET /v1/surface/svi/{symbol}`](#get-v1surfacesvisymbol) — Live SVI parameters per expiry `Alpha+` -- [`GET /v1/stock/{symbol}/summary`](#get-v1stocksymbolsummary) — Comprehensive stock summary `Public` (cached) / `Free+` (live) +- [`GET /v1/stock/{symbol}/summary`](#get-v1stocksymbolsummary) — Comprehensive stock summary `Public` (previous session's snapshot) / `Free+` (live) ### Exposure Analytics @@ -217,7 +217,7 @@ Every authenticated response includes rate limit headers: | Plan | Daily Requests | Access | |------|---------------|--------| -| Free | 5 | Stock quotes, gamma exposure by strike (GEX, levels), BSM greeks, IV solver, tickers, options meta, symbols, surface, stock summary (cached for unauthenticated, live for authenticated) | +| Free | 5 | Stock quotes, gamma exposure by strike (GEX, levels), BSM greeks, IV solver, tickers, options meta, symbols, surface, stock summary (previous session's snapshot for unauthenticated, live for authenticated) | | Basic | 250 | Everything in Free + delta/vanna/charm exposure (DEX/VEX/CHEX) + index symbols + max pain analysis | | Growth | 2,500 | + Exposure summary, narrative, history, 0DTE analytics, volatility analytics, option quotes, full-chain GEX (no expiry filter), Kelly sizing, **flow analytics** (`/v1/flow/levels`, `/pin-risk`, `/summary`, `/gex`, `/dex`, `/dealer-risk`) | | Alpha | Unlimited | + Advanced volatility (SVI, variance surfaces, arbitrage detection, greeks surfaces, var swap), VRP analytics (risk premium, z-score, percentile, directional VRP, term structure, GEX/vanna-conditioned regime, strategy suitability scores, dealer flow risk, macro context), SVI-smoothed IV on option quotes, **raw OI simulator state** (`/v1/flow/oi`), **flow bundle** (`/v1/flow/live`), **unusual-flow signal feed** (`/v1/flow/signals`), and raw option/stock flow data (`/v1/flow/options/*`, `/v1/flow/stocks/*`) | @@ -336,9 +336,9 @@ curl -H "X-Api-Key: YOUR_API_KEY" \ ## `GET /v1/surface/{symbol}` -Returns the cached volatility surface grid for a symbol. **Public endpoint — no authentication required.** +Returns the pre-computed volatility surface grid for a symbol. **Public endpoint — no authentication required.** -The surface is pre-computed from SVI fits and cached in the database. Updated periodically during market hours. +The surface is pre-computed from SVI fits and updated periodically during market hours. ### Parameters @@ -354,7 +354,7 @@ curl https://lab.flashalpha.com/v1/surface/SPY ### Response `200` -Returns the cached JSON response containing the vol surface grid data. +Returns the JSON response containing the vol surface grid data. ### Errors @@ -370,7 +370,7 @@ Returns a comprehensive stock summary: price, ATM IV, historical volatility, vol **Dual access:** - **Authenticated** — returns live, real-time data computed on the spot -- **Unauthenticated (no API key)** — returns the previous day's cached snapshot from the database (populated daily at market open) +- **Unauthenticated (no API key)** — returns the previous trading session's snapshot ### Parameters @@ -520,11 +520,11 @@ curl "https://lab.flashalpha.com/v1/stock/SPY/summary" | Status | Description | |--------|-------------| -| `404` | No data for symbol (authenticated) or no cached snapshot (unauthenticated) | +| `404` | No data for symbol (authenticated) or no snapshot available (unauthenticated) | ### Notes -- Unauthenticated responses are cached daily at 9:31 AM ET and reflect the previous trading day's data +- Unauthenticated responses show the previous trading session's snapshot - Macro fields (`vix`, `vvix`, etc.) may be `null` if the external data source is unavailable - `exposure` is `null` if no options/greeks data is loaded for the symbol - HV is computed from Yahoo Finance historical closes using annualized log-return standard deviation (√252) @@ -1948,7 +1948,7 @@ Every simulation-aware flow analytics response uses the same per-contract OI sta ### Expiry filter -Every `/v1/flow/*` endpoint accepts an optional `?expiry=YYYY-MM-DD` query parameter that filters the chain to a single expiry before running the math. Omit the parameter to aggregate across all expiries (the default). Invalid formats return `400 Bad Request` with `{"error":"invalid_expiry"}`; an expiry with no contracts in the cached chain returns `404 Not Found`. +Every `/v1/flow/*` endpoint accepts an optional `?expiry=YYYY-MM-DD` query parameter that filters the chain to a single expiry before running the math. Omit the parameter to aggregate across all expiries (the default). Invalid formats return `400 Bad Request` with `{"error":"invalid_expiry"}`; an expiry with no contracts in the chain returns `404 Not Found`. ```bash curl -H "X-Api-Key: YOUR_API_KEY" \ @@ -2874,7 +2874,7 @@ curl -H "X-Api-Key: YOUR_API_KEY" \ ## Raw Flow Data -These Alpha-only endpoints proxy intraday trade-flow JSON from the ingest service. Unlike the analytics endpoints above, these are pass-through responses and use `camelCase` field names. Cross-symbol scans are cached for 30 seconds. +These Alpha-only endpoints proxy intraday trade-flow JSON from the ingest service. Unlike the analytics endpoints above, these are pass-through responses and use `camelCase` field names. Cross-symbol scans refresh about every 30 seconds. Common errors: @@ -3780,7 +3780,7 @@ curl -H "X-Api-Key: YOUR_API_KEY" https://lab.flashalpha.com/v1/options/SPY ## `GET /v1/symbols` -Returns the list of symbols that have been queried and have live data cached. +Returns the list of symbols that have been queried and currently have live data. ### Example @@ -3794,7 +3794,7 @@ curl -H "X-Api-Key: YOUR_API_KEY" https://lab.flashalpha.com/v1/symbols { "symbols": ["SPY", "QQQ"], "count": 2, - "note": "Any US equity or ETF symbol is supported. All data is fetched on-demand. Free responses may be cached for up to 15 minutes.", + "note": "Paid plans serve live data. Endpoint access, fields and quotas depend on your plan; upstream data age and public snapshot policies still apply.", "last_updated": "2026-02-28T16:30:45Z" } ``` @@ -5900,4 +5900,4 @@ All endpoints return consistent error responses. - Implied volatility is smoothed via **SVI** (Stochastic Volatility Inspired) parameterization - Dealer position is the **opposite** of net exposure (dealers are counterparty) - OI changes are **day-over-day** deltas (when prior-day snapshot is available) -- Any US equity or ETF symbol is supported — data is fetched on-demand, and Free responses may be cached for up to 15 minutes +- Any US equity or ETF symbol is supported. Data is fetched on-demand, paid plans serve live data, and a Free API key gets delayed data diff --git a/llms.txt b/llms.txt index d5851c9..04ee837 100644 --- a/llms.txt +++ b/llms.txt @@ -77,7 +77,7 @@ narrative = client.exposure_narrative("SPY") full dealer exposure (Greeks, walls, gamma flip, max pain, hedging estimate, 0DTE attribution, top strikes), and macro context (VIX, VVIX, SKEW, SPX, MOVE, term structure, fear/greed). Dual-mode auth: - authenticated = live; unauthenticated = previous-day cached snapshot. + authenticated = live; unauthenticated = previous trading session's snapshot. - `GET /v1/exposure/summary/{symbol}` — net dealer Greeks (gamma/delta/vanna/charm), gamma flip, ±1% hedging estimate, verbal regime narratives, 0DTE attribution. @@ -243,7 +243,7 @@ number; treat any other value as no level published. ## Tier breakdown - **Free**: dual-mode preview tier — `stock_summary` returns a - previous-day cached snapshot without an API key. + previous trading session's snapshot without an API key. - **Basic**: live `exposure_summary`, `exposure_levels`, `zero_dte`, `maxpain`, `pricing/greeks`. - **Alpha**: adds `vrp` and full historical replay of the above. diff --git a/src/flashalpha/types.py b/src/flashalpha/types.py index 39e5351..a77a858 100644 --- a/src/flashalpha/types.py +++ b/src/flashalpha/types.py @@ -977,7 +977,8 @@ class MaxPainResponse(TypedDict, total=False): # # Dual-mode auth: # - Authenticated (with API key): live, current-minute snapshot. -# - Unauthenticated: previous-day cached snapshot (free preview tier). +# - Unauthenticated: previous trading session's snapshot (free preview +# tier). # # Hedging-estimate sign convention DIFFERS from /v1/exposure/zero-dte: # - On stock_summary, ``hedging_estimate.spot_*_1pct.dealer_shares`` is a @@ -1083,7 +1084,7 @@ class StockSummaryOptionsFlow(TypedDict, total=False): # Total put open interest across the chain. total_put_oi: Optional[int] # Total call volume traded so far in the session (live) or for the - # cached day (unauthenticated). + # snapshot's session (unauthenticated). total_call_volume: Optional[int] # Total put volume traded so far in the session. total_put_volume: Optional[int] @@ -1363,7 +1364,7 @@ class StockSummaryResponse(TypedDict, total=False): - **Authenticated** (with API key): live, current-minute snapshot. Pricing reflects the most recent quote tick; all derived numbers are computed against that spot. - - **Unauthenticated**: previous-day cached snapshot, served as a + - **Unauthenticated**: previous trading session's snapshot, served as a free preview tier — the response shape is identical but ``as_of`` is the prior trading day's close. Useful for demos / docs / LLM tool-call examples without burning a key. @@ -3584,7 +3585,8 @@ class FlowOptionLeaderboardResponse(TypedDict, total=False): """Cross-symbol option-flow leaderboard from ``GET /v1/flow/options/leaderboard``. - Top ``n`` net-dollar buyers and sellers over the window. Cached ~30s. + Top ``n`` net-dollar buyers and sellers over the window. Refreshes + about every 30s. Requires the Alpha plan. """ @@ -3643,7 +3645,8 @@ class FlowOutlierRow(TypedDict, total=False): class FlowOptionOutliersResponse(TypedDict, total=False): """Cross-symbol option-flow outliers from - ``GET /v1/flow/options/outliers``. Cached ~30s. Requires Alpha. + ``GET /v1/flow/options/outliers``. Refreshes about every 30s. + Requires Alpha. """ # When the snapshot was generated (ISO-8601 UTC). @@ -3691,7 +3694,8 @@ class FlowStockLeaderRow(TypedDict, total=False): class FlowStockLeaderboardResponse(TypedDict, total=False): """Cross-symbol stock-flow leaderboard from - ``GET /v1/flow/stocks/leaderboard``. Cached ~30s. Requires Alpha. + ``GET /v1/flow/stocks/leaderboard``. Refreshes about every 30s. + Requires Alpha. """ # When the snapshot was generated (ISO-8601 UTC). @@ -3712,7 +3716,8 @@ class FlowStockLeaderboardResponse(TypedDict, total=False): class FlowStockOutliersResponse(TypedDict, total=False): """Cross-symbol stock-flow outliers from - ``GET /v1/flow/stocks/outliers``. Cached ~30s. Requires Alpha. + ``GET /v1/flow/stocks/outliers``. Refreshes about every 30s. + Requires Alpha. """ # When the snapshot was generated (ISO-8601 UTC).