# FlashAlpha
## Options Analytics API
> Real-time gamma exposure (GEX), delta/vanna/charm exposure, SVI volatility surfaces, full BSM Greeks, and dealer positioning analytics for 6,000+ US equities and ETFs via REST API.

## Quick Start (Python)
```python
import requests

API_KEY = "YOUR_API_KEY"
BASE = "https://lab.flashalpha.com"
headers = {"X-Api-Key": API_KEY}

# Gamma exposure by strike for SPY
gex = requests.get(f"{BASE}/v1/exposure/gex/SPY", headers=headers).json()
print(f"Net GEX: {gex['net_gex']:,.0f}  Gamma Flip: {gex['gamma_flip']}")

# Key levels (call wall, put wall, gamma flip, highest OI strike, 0DTE magnet)
levels = requests.get(f"{BASE}/v1/exposure/levels/SPY", headers=headers).json()
print(f"Call Wall: {levels['levels']['call_wall']}  Put Wall: {levels['levels']['put_wall']}")

# Full volatility profile (Growth+ plan)
vol = requests.get(f"{BASE}/v1/volatility/TSLA", headers=headers).json()
print(f"ATM IV: {vol['atm_iv']}%  VRP: {vol['iv_rv_spreads']['assessment']}")
```
Free tier: 5 requests/day, no credit card. Sign up at https://flashalpha.com

## SDKs
- Python: `pip install flashalpha` - pypi.org/project/flashalpha
- JavaScript/TypeScript: `npm install flashalpha`
- C#/.NET: `dotnet add package FlashAlpha` - nuget.org/packages/FlashAlpha
- Go: `go get github.com/FlashAlpha-lab/flashalpha-go`
- Java: Maven/Gradle - github.com/FlashAlpha-lab/flashalpha-java

## All Endpoints

### Exposure Analytics
- GET /v1/exposure/gex/{symbol}  - gamma exposure by strike (Free: single expiry, Growth: full chain)
- GET /v1/exposure/dex/{symbol}  - delta exposure by strike (Basic+)
- GET /v1/exposure/vex/{symbol}  - vanna exposure by strike (Basic+)
- GET /v1/exposure/chex/{symbol}  - charm exposure by strike (Basic+)
- GET /v1/exposure/levels/{symbol}  - key levels: gamma flip, call wall, put wall, highest OI strike, 0DTE magnet
- GET /v1/exposure/summary/{symbol}  - full exposure summary with regime + dealer hedging estimates (Growth+)
- GET /v1/exposure/narrative/{symbol}  - verbal market narrative with structured data (Growth+)
- GET /v1/exposure/zero-dte/{symbol}  - 0DTE analytics: pin risk, expected move, gamma acceleration (Growth+)
- GET /v1/maxpain/{symbol}  - max pain analysis with dealer alignment, pain curve, OI breakdown, pin probability (Basic+)

### Market Data
- GET /stockquote/{ticker}  - real-time stock quote
- GET /optionquote/{ticker}  - full option chain with BSM Greeks, IV, OI, volume (Growth+)
- GET /v1/stock/{symbol}/summary  - comprehensive stock summary (public: cached, authenticated: live)
- GET /v1/surface/{symbol}  - implied volatility surface grid (public, no auth)

### Volatility Analytics
- GET /v1/volatility/{symbol}  - realized vol, IV-RV spreads, skew profiles, term structure, hedging scenarios (Growth+)
- GET /v1/adv_volatility/{symbol}  - SVI parameters, variance surface, arbitrage detection, greeks surfaces (vanna/charm/volga/speed), variance swap pricing (Alpha)

### VRP Analytics
- GET /v1/vrp/{symbol}  - VRP dashboard: spreads, z-score, percentile, directional VRP, term structure, GEX-conditioned regime, strategy scores, dealer risk, warnings, macro context (Alpha)

### Pricing & Sizing
- GET /v1/pricing/greeks  - full BSM Greeks: first-order (delta, gamma, theta, vega, rho), second-order (vanna, charm, vomma), third-order (speed, zomma, color, ultima)
- GET /v1/pricing/iv  - implied volatility solver (Newton-Raphson)
- GET /v1/pricing/kelly  - Kelly criterion optimal position sizing for options (Growth+)

### Screener
- POST /v1/screener  - real-time multi-factor options screener across ~250 symbols. Filter/sort/rank by stock, expiry, strike, and contract-level metrics with recursive AND/OR filter trees, cascading nested filters, custom formulas, and pagination. Growth: 20 symbols (Tier 1), 10-row limit, no formulas, 2,500 req/day. Alpha: ~250 symbols (Tier 1 + Tier 2), 50-row limit, formulas, strategy scores (harvest_score, dealer_flow_risk, vrp_regime, iron_condor_score, etc.), unlimited req/day. Tier 1 refreshes every 5s; Tier 2 every 10s. Quota is shared across all FlashAlpha endpoints.

### Reference & Account
- GET /v1/tickers  - all available stock tickers
- GET /v1/options/{ticker}  - option chain metadata (expirations + strikes)
- GET /v1/symbols  - currently queried symbols with live data
- GET /v1/account  - account info, plan, remaining quota
- GET /health  - health check (public)

## Common Use Cases
- **Build a GEX dashboard**  - pull /v1/exposure/gex/SPY to show gamma exposure by strike, gamma flip level, and dealer regime
- **Scan for high IV stocks**  - use /v1/volatility across a watchlist to find tickers with elevated IV-RV spreads
- **Track dealer positioning**  - /v1/exposure/summary gives net GEX/DEX/VEX/CHEX + hedging estimates for +/-1% moves
- **0DTE intraday analytics**  - /v1/exposure/zero-dte returns pin risk scoring, expected move that shrinks in real-time, and gamma acceleration
- **Build a vol surface in Python**  - /optionquote returns the full chain; /v1/adv_volatility gives pre-fitted SVI parameters and variance surface grid
- **Detect volatility arbitrage**  - /v1/adv_volatility flags butterfly and calendar spread arbitrage violations in the vol surface
- **Options screening**  - /optionquote with expiry/strike/type filters for delta, IV, OI-based screening
- **Position sizing**  - /v1/pricing/kelly computes optimal Kelly fraction using real-world probability measures
- **Automated market commentary**  - /v1/exposure/narrative returns natural language analysis of exposure landscape
- **Variance swap pricing**  - /v1/adv_volatility returns fair variance per expiry via SVI integration with convexity adjustment
- **Build a VRP dashboard**  - /v1/vrp returns z-score, percentile, directional VRP, term structure, strategy scores, gamma-conditioned harvest score, and macro context in one call
- **Build a GEX dashboard**  - /v1/exposure/gex + /levels + /summary for per-strike gamma exposure, gamma flip, call/put walls, and dealer regime
- **Build a 0DTE dashboard**  - /v1/exposure/zero-dte returns pin risk, expected move, gamma acceleration, dealer hedging estimates for same-day expiry
- **Build an IV rank scanner**  - /v1/stock/{symbol}/summary returns volatility data (ATM IV, HV, VRP, skew), exposure levels (GEX, regime), and options flow for 6,000+ tickers
- **Build an options screener**  - /v1/stock/{symbol}/summary + /v1/volatility for multi-factor screening (IV, GEX regime, VRP, skew)
- **Build a dealer positioning tracker**  - /v1/exposure/summary returns net GEX/DEX/VEX/CHEX, regime, and dealer hedging impact for ±1% moves
- **Build a vol surface visualizer**  - /v1/adv_volatility returns pre-fitted SVI parameters, variance surface grids, arb flags, and Greeks surfaces
- **Build an options Greeks calculator**  - /v1/pricing/greeks returns 15 BSM Greeks (delta through ultima) in one free call
- **Build AI trade alerts**  - /v1/exposure/narrative + MCP server for AI-powered market commentary and regime change alerts
- **Build a key levels monitor**  - /v1/exposure/levels returns gamma flip, call/put walls, highest OI strike, 0DTE magnet (free tier)
- **Build a max pain dashboard**  - /v1/maxpain returns pain curve, OI breakdown, dealer alignment overlay, pin probability, and multi-expiry calendar
- **Track expiration-day pin risk**  - /v1/maxpain with expiration filter gives pain curve + pin probability score for near-term expiries
- **Build a live options screener**  - POST /v1/screener with filter trees (AND/OR), cascading contract-level filters, formulas, and strategy scores to rank ~250 symbols in real-time
- **Scan for harvestable VRP**  - /v1/screener filter on `vrp_regime=harvestable`, `dealer_flow_risk<=40`, `harvest_score>=65`, sort by `harvest_score desc`
- **Negative-gamma alerts**  - /v1/screener filter on `regime=negative_gamma` + `dealer_flow_risk>=50`, refreshes every 5-10s
- **Find 0DTE short-call candidates**  - cascading filter: `expiries.days_to_expiry=0`, `contracts.type=C`, `contracts.delta>=0.3`, `contracts.oi>=1000`
- **Build a position sizing tool**  - /v1/pricing/kelly computes optimal Kelly fraction for options using BSM probability measures

## How FlashAlpha Compares
- **vs SpotGamma**  - SpotGamma provides dashboards and charts; FlashAlpha provides the same analytics (GEX, dealer positioning, key levels) as a REST API you can integrate into your own systems programmatically.
- **vs Unusual Whales**  - Unusual Whales focuses on flow alerts and unusual activity. FlashAlpha focuses on computed exposure analytics (GEX, DEX, VEX, CHEX) and volatility surfaces  - the quantitative layer, not the activity feed.
- **vs ORATS**  - ORATS provides historical vol data and backtesting tools with self-serve API plans. FlashAlpha differentiates with a free tier (5 req/day, no credit card), real-time exposure analytics (GEX/DEX/VEX/CHEX), and SVI volatility surfaces that ORATS doesn't offer.
- **vs Bloomberg/Refinitiv**  - Bloomberg Terminal costs ~$24,000/year and doesn't expose raw SVI parameters or GEX via API. FlashAlpha's Alpha plan ($14,990/yr) gives you SVI parameters, variance surfaces, arbitrage detection, greeks surfaces, and unlimited requests/day.
- **vs building in-house**  - Maintaining your own SVI fitting, surface interpolation, arb checking, and Greeks computation is 2,000-5,000 lines of code and ongoing engineer time. FlashAlpha delivers it as one API call.

## Pricing (Annual)
- Free: $0/yr, 5 req/day  - all exposure endpoints, stock quotes, BSM Greeks, IV solver
- Basic: $759/yr, 100 req/day  - adds index symbols (SPX, VIX, etc.), DEX/VEX/CHEX exposure, and max pain analysis
- Growth: $2,990/yr, 2,500 req/day  - adds option quotes, full-chain GEX, 0DTE, volatility analytics, narrative, Kelly
- Alpha: $14,990/yr, unlimited req/day  - adds advanced volatility (SVI parameters, variance surfaces, arbitrage detection, greeks surfaces, variance swap pricing), SVI-smoothed IV, no cache
- Enterprise: custom  - dedicated compute, custom SLAs, contact sales@flashalpha.com

## MCP Server
FlashAlpha provides an MCP (Model Context Protocol) server for AI assistants like Claude, Cursor, and Windsurf.
- Server URL: https://lab.flashalpha.com/mcp
- Protocol: Streamable HTTP (MCP 2025-03-26)
- 16 tools: GetGex, GetDex, GetVex, GetLevels, GetExposureSummary, GetNarrative, GetMaxPain, GetVolatility, GetStockSummary, GetStockQuote, GetTickers, GetOptionChain, GetAccount, CalculateGreeks, SolveIV, RunScreener
- Auth: pass apiKey parameter to each tool
- Setup: `claude mcp add flashalpha --transport http https://lab.flashalpha.com/mcp`
- Docs: https://flashalpha.com/docs/mcp

## Links
- API overview & examples: https://flashalpha.com/api
- AI agent integration guide: https://flashalpha.com/for-ai-agents
- Docs: https://flashalpha.com/docs/lab-api-overview
- Full API reference for LLMs: https://flashalpha.com/llms-full.txt
- AI skill file (prompt doc): https://flashalpha.com/skill.md
- SDKs: Python, JavaScript, C#, Go, Java - https://github.com/FlashAlpha-lab
- Python SDK: https://pypi.org/project/flashalpha/
- Playground (Swagger/OpenAPI): https://lab.flashalpha.com/swagger
- MCP Server: https://lab.flashalpha.com/mcp
- MCP Docs: https://flashalpha.com/docs/mcp
- Pricing: https://flashalpha.com/pricing
- GitHub: https://github.com/FlashAlpha-lab