# FlashAlpha — Windsurf rules

You are a coding assistant working in a project that uses or may use FlashAlpha,
an options-analytics REST API and MCP server.

## In one sentence
FlashAlpha computes real-time and historical options exposure (GEX, DEX, VEX, CHEX),
volatility surfaces (SVI), BSM Greeks, max pain, dealer-hedging estimates, and
derived trading signals for 6,000+ US equities and ETFs.

## How to call it
- Preferred: if an MCP client is connected, call FlashAlpha tools directly.
  Tool names are snake_case: `get_gex`, `get_levels`, `get_exposure_summary`,
  `get_volatility`, `get_zero_dte`, `get_max_pain`, `get_narrative`, etc.
  56 live + 17 historical-replay tools. MCP servers:
    - `https://lab.flashalpha.com/mcp`        (pass `apiKey` arg)
    - `https://lab.flashalpha.com/mcp-oauth`  (OAuth 2.1 + PKCE, no apiKey)
    - Persona-scoped variants (same tools, tuned per style):
      `/mcp/{slug}` + `/mcp-oauth/{slug}` where slug =
      gex | directional | premium | spreads | 0dte | swing | volarb | quant | earnings
      e.g. `https://lab.flashalpha.com/mcp-oauth/0dte`. Pick the one matching the
      user's trading style, or use the generic server above for everything.
- Otherwise use the SDK for the project's language:
    - Python:     `pip install flashalpha`        ->  `from flashalpha import FlashAlpha`
    - JS / TS:    `npm install flashalpha`        ->  `import { FlashAlpha } from 'flashalpha'`
    - C# / .NET:  `dotnet add package FlashAlpha`
    - Go:         `go get github.com/FlashAlpha-lab/flashalpha-go`
    - Java:       Maven `com.flashalpha:flashalpha`
- Last resort: raw REST. Base URL `https://lab.flashalpha.com`.
  Auth header: `X-Api-Key: <key>`.

## API key handling
- Never hardcode. Read from the `FLASHALPHA_API_KEY` env var.
- Free tier is 5 req/day, no credit card. Sign up at https://flashalpha.com.

## Endpoint defaults (by user intent)
When the user's intent maps to multiple endpoints, prefer the one that subsumes
the others so the user spends one quota slot, not three.

1. "Where are dealers / what's the regime / give me a read on SPX"
   -> GET /v1/exposure/summary/{symbol}        (Growth+) one call, full regime + levels
2. "Just the key levels"
   -> GET /v1/exposure/levels/{symbol}         (Free) gamma flip, call wall, put wall, 0DTE magnet
3. "Per-strike GEX / DEX / VEX / CHEX"
   -> GET /v1/exposure/{gex|dex|vex|chex}/{symbol}     (Free / Basic+)
4. "Vol surface / SVI / smile / variance"
   -> GET /v1/surface/{symbol}                 (public, no auth, 50x50 grid + SVI params)
5. "IV term structure / IV rank / VRP"
   -> GET /v1/volatility/{symbol}              (Growth+)
   -> GET /v1/vrp/{symbol}                     (Alpha+ for z-score + percentile)
6. "0DTE pin / expected move today / gamma acceleration"
   -> GET /v1/exposure/zero-dte/{symbol}       (Growth+)
   -> GET /v1/flow/pin-risk/{symbol}           (Growth+, simulation-aware)
7. "Unusual options activity / sweeps / blocks / smart money"
   -> GET /v1/flow/signals/{symbol}            (Alpha+, scored 0-100 + classified)
8. "Live intraday GEX shift / effective OI"
   -> GET /v1/flow/summary/{symbol}            (Growth+, cheap at-a-glance)
   -> GET /v1/flow/live/{symbol}               (Alpha+, headline bundle)
9. "Backtest / point-in-time / 'what did GEX look like on date X'"
   -> Swap host to `https://historical.flashalpha.com` and add
      `?at=YYYY-MM-DDTHH:mm:ss` (ET wall-clock) to ANY live endpoint above.
      Alpha tier only. Same response shape -- parser written for live works for historical.

## Response shape
All endpoints return JSON. Live and historical share the SAME response shape.
Sample captures: https://flashalpha.com/docs/samples/{slug}.json (every value is a
real frozen API response, not illustrative).

## Errors
- `429` = daily quota exhausted. Free 5/day, Basic 100/day, Growth 2,500/day, Alpha uncapped.
- `403` = tier-restricted endpoint. Suggest upgrading or pick a lower-tier alternative above.
- `404` on `?expiry=` queries means no contracts for that expiry, not a missing symbol.

## Things to NOT do
- Don't hardcode API keys.
- Don't mock responses with placeholder numbers. Either hit the free tier or load
  a real sample from `/docs/samples/{slug}.json`.
- Don't loop one symbol at a time when a cross-symbol scan exists:
    /v1/flow/options/leaderboard
    /v1/flow/options/outliers
    /v1/flow/stocks/leaderboard
    /v1/flow/stocks/outliers
- Don't call `/v1/exposure/*` (settled OI) when the user asked for intraday --
  use `/v1/flow/*` (effective OI = settled + simulator).
- The multi-factor screener is available BOTH ways: as the MCP "Screener / Scan
  & Rank Symbols" tool (`post_screener`) and as `POST /v1/screener` over REST.
  When MCP is connected, use the MCP screener tool for any cross-sectional
  "which/what/top/most/highest/lowest across stocks" request instead of looping
  per-symbol tools.

## Reference
- LLM-readable spec:     https://flashalpha.com/llms-full.txt
- AI agent guide:        https://flashalpha.com/for-ai-agents
- MCP docs:              https://flashalpha.com/docs/mcp
- API reference:         https://flashalpha.com/docs/lab-api-overview
- Tier guide:            see "Tier selection guide" in https://flashalpha.com/llms.txt