### FlashAlpha SDK Installation and Quick Start

Source: https://github.com/flashalpha-lab/flashalpha-python/blob/main/article-flashalpha-python-sdk.md

Instructions on how to install the FlashAlpha Python SDK using pip and a quick start example demonstrating how to initialize the client and fetch Gamma Exposure (GEX) data.

```APIDOC
## FlashAlpha SDK Installation and Quick Start

### Description
Install the FlashAlpha Python SDK using pip and get started with a basic example.

### Installation
```bash
pip install flashalpha
```

### Quick Start
```python
from flashalpha import FlashAlpha

fa = FlashAlpha("YOUR_API_KEY")

# Gamma exposure by strike
gex = fa.gex("SPY")
print(f"Net GEX: ${gex['net_gex']:,.0f}")
print(f"Gamma flip: {gex['gamma_flip']}")
```
```

--------------------------------

### Install FlashAlpha Python SDK

Source: https://github.com/flashalpha-lab/flashalpha-python/blob/main/article-flashalpha-python-sdk.md

Install the FlashAlpha Python SDK using pip. This command fetches and installs the latest version of the library.

```bash
pip install flashalpha
```

--------------------------------

### Install and Initialize FlashAlpha Client

Source: https://context7.com/flashalpha-lab/flashalpha-python/llms.txt

Install the SDK using pip and initialize the FlashAlpha client with your API key. Handle potential errors like authentication issues, tier restrictions, not found symbols, or rate limits explicitly.

```python
# pip install flashalpha

from flashalpha import (
    FlashAlpha,
    AuthenticationError,
    TierRestrictedError,
    NotFoundError,
    RateLimitError,
)

fa = FlashAlpha("YOUR_API_KEY")  # timeout defaults to 30s

# All errors are typed — handle them explicitly
try:
    data = fa.gex("SPY")
except AuthenticationError:
    print("Invalid or missing API key")
except TierRestrictedError as e:
    print(f"Upgrade required: {e.current_plan} → {e.required_plan}")
except NotFoundError:
    print("Symbol not found or no data available")
except RateLimitError as e:
    print(f"Quota exceeded — retry after {e.retry_after}s")
```

--------------------------------

### Clone and Install FlashAlpha Python SDK

Source: https://github.com/flashalpha-lab/flashalpha-python/blob/main/CONTRIBUTING.md

Clone the repository and install the SDK in editable mode with development dependencies.

```bash
git clone https://github.com/FlashAlpha-lab/flashalpha-python.git
cd flashalpha-python
pip install -e ".[dev]"
pytest tests/test_client.py -v
```

--------------------------------

### Quick Start: Get Net GEX

Source: https://github.com/flashalpha-lab/flashalpha-python/blob/main/article-flashalpha-python-sdk.md

Initialize the FlashAlpha client with your API key and retrieve the net Gamma Exposure (GEX) for a given symbol. Prints the net GEX value and the gamma flip level.

```python
from flashalpha import FlashAlpha

fa = FlashAlpha("YOUR_API_KEY")

# Gamma exposure by strike
gex = fa.gex("SPY")
print(f"Net GEX: ${gex['net_gex']:,.0f}")
print(f"Gamma flip: {gex['gamma_flip']}")
```

--------------------------------

### Get Exposure History Request

Source: https://github.com/flashalpha-lab/flashalpha-python/blob/main/docs/api.md

Example cURL command to retrieve daily exposure snapshots for a given symbol over a specified number of days. Requires an API key and the Growth plan or higher.

```bash
curl -H "X-Api-Key: YOUR_API_KEY" \
  "https://lab.flashalpha.com/v1/exposure/history/SPY?days=7"
```

--------------------------------

### Example Response for Narrative Analysis

Source: https://github.com/flashalpha-lab/flashalpha-python/blob/main/docs/api.md

This JSON object illustrates a successful response from the GET /v1/exposure/narrative/{symbol} endpoint, providing a detailed textual and structured analysis of options exposure.

```json
{
  "symbol": "SPY",
  "underlying_price": 597.505,
  "as_of": "2026-02-28T16:30:45Z",
  "narrative": {
    "regime": "Dealers are long gamma (net GEX +$2.9B) — expect mean-reverting, range-bound price action.",
    "gex_change": "Net GEX increased from +$2.6B to +$2.9B (+11.5%) — gamma cushion strengthening.",
    "key_levels": "Call wall at 600, Put wall at 595, Gamma flip at 595.25.",
    "flow": "Top OI changes: +5,000 call OI at 600 strike, -2,000 put OI at 595 strike.",
    "vanna": "Positive vanna (+$1.2B) with VIX at 18.5 — vol compression supports upside.",
    "charm": "Positive charm (+$850M) — time decay pushing dealers to buy, providing support.",
    "zero_dte": "0DTE accounts for 10% of total GEX — minimal intraday impact.",
    "outlook": "Positive gamma regime with strengthening cushion. Testing 600 call wall.",
    "data": {
      "net_gex": 2850000000,
      "net_gex_prior": 2600000000,
      "net_gex_change_pct": 9.6,
      "vix": 18.5,
      "gamma_flip": 595.25,
      "call_wall": 600.0,
      "put_wall": 595.0,
      "regime": "positive_gamma",
      "zero_dte_pct": 10.0,
      "top_oi_changes": [
        {
          "strike": 600.0,
          "type": "C",
          "oi_change": 5000,
          "volume": 1250
        }
      ]
    }
  }
}
```

--------------------------------

### Response Example for Exposure Summary

Source: https://github.com/flashalpha-lab/flashalpha-python/blob/main/docs/api.md

Example JSON response structure for the comprehensive exposure summary endpoint.

```json
{
  "symbol": "SPY",
  "underlying_price": 597.505,
  "as_of": "2026-02-28T16:30:45Z",
  "gamma_flip": 595.25,
  "regime": "positive_gamma",
  "exposures": {
    "net_gex": 2850000000,
    "net_dex": -450000000,
    "net_vex": 1200000000,
    "net_chex": 850000000
  },
  "interpretation": {
    "gamma": "Dealers long gamma — expect range-bound, mean-reverting price action",
    "vanna": "Positive vanna — benefits from vol compression",
    "charm": "Time decay favors dealers — supports decline into close"
  },
  "hedging_estimate": {
    "spot_down_1pct": {
      "dealer_shares_to_trade": 4780000,
      "direction": "buy",
      "notional_usd": 2852000000
    },
    "spot_up_1pct": {
      "dealer_shares_to_trade": -4780000,
      "direction": "sell",
      "notional_usd": 2852000000
    }
  },
  "zero_dte": {
    "net_gex": 285000000,
    "pct_of_total_gex": 10.0,
    "expiration": "2026-02-28"
  }
}
```

--------------------------------

### Example Response for Exposure Levels

Source: https://github.com/flashalpha-lab/flashalpha-python/blob/main/docs/api.md

This JSON object represents a successful response from the GET /v1/exposure/levels/{symbol} endpoint, detailing various technical levels derived from options data.

```json
{
  "symbol": "SPY",
  "underlying_price": 597.505,
  "as_of": "2026-02-28T16:30:45Z",
  "levels": {
    "gamma_flip": 595.25,
    "max_positive_gamma": 600.0,
    "max_negative_gamma": 585.0,
    "call_wall": 600.0,
    "put_wall": 595.0,
    "highest_oi_strike": 600.0,
    "zero_dte_magnet": 598.0
  }
}
```

--------------------------------

### Response Example for VEX Exposure

Source: https://github.com/flashalpha-lab/flashalpha-python/blob/main/docs/api.md

Example JSON response structure for the VEX exposure endpoint.

```json
{
  "symbol": "SPY",
  "underlying_price": 597.505,
  "as_of": "2026-02-28T16:30:45Z",
  "net_vex": 1200000000,
  "vex_interpretation": "Positive vanna — benefits from vol compression",
  "strikes": [
    {
      "strike": 575.0,
      "call_vex": 2300000,
      "put_vex": 1800000,
      "net_vex": 4100000
    }
  ]
}
```

--------------------------------

### Response Example for DEX Exposure

Source: https://github.com/flashalpha-lab/flashalpha-python/blob/main/docs/api.md

Example JSON response structure for the DEX exposure endpoint.

```json
{
  "symbol": "SPY",
  "underlying_price": 597.505,
  "as_of": "2026-02-28T16:30:45Z",
  "net_dex": -450000000,
  "strikes": [
    {
      "strike": 575.0,
      "call_dex": 5600000,
      "put_dex": 4200000,
      "net_dex": 9800000
    }
  ]
}
```

--------------------------------

### Response Example for CHEX Exposure

Source: https://github.com/flashalpha-lab/flashalpha-python/blob/main/docs/api.md

Example JSON response structure for the CHEX exposure endpoint.

```json
{
  "symbol": "SPY",
  "underlying_price": 597.505,
  "as_of": "2026-02-28T16:30:45Z",
  "net_chex": 850000000,
  "chex_interpretation": "Positive charm — time decay benefits dealers",
  "strikes": [
    {
      "strike": 575.0,
      "call_chex": 950000,
      "put_chex": 620000,
      "net_chex": 1570000
    }
  ]
}
```

--------------------------------

### GET /v1/account

Source: https://github.com/flashalpha-lab/flashalpha-python/blob/main/docs/api.md

Retrieves account information and quota details.

```APIDOC
## GET /v1/account

### Description
Account info and quota.

### Method
GET

### Endpoint
`/v1/account`
```

--------------------------------

### GET /v1/exposure/summary/{symbol}

Source: https://github.com/flashalpha-lab/flashalpha-python/blob/main/docs/api.md

Retrieves a full exposure summary for a given symbol.

```APIDOC
## GET /v1/exposure/summary/{symbol}

### Description
Full exposure summary.

### Method
GET

### Endpoint
`/v1/exposure/summary/{symbol}`

### Parameters
#### Path Parameters
- **symbol** (string) - Required - The equity or ETF symbol.
```

--------------------------------

### GET /v1/exposure/levels/{symbol}

Source: https://github.com/flashalpha-lab/flashalpha-python/blob/main/docs/api.md

Retrieves key support and resistance levels for a given symbol.

```APIDOC
## GET /v1/exposure/levels/{symbol}

### Description
Key support/resistance levels.

### Method
GET

### Endpoint
`/v1/exposure/levels/{symbol}`

### Parameters
#### Path Parameters
- **symbol** (string) - Required - The equity or ETF symbol.
```

--------------------------------

### Initialize FlashAlpha Client

Source: https://github.com/flashalpha-lab/flashalpha-python/blob/main/README.md

Instantiate the FlashAlpha client with your API key.

```APIDOC
## Initialize FlashAlpha Client

### Description
Instantiate the FlashAlpha client with your API key to interact with the API.

### Method
```python
FlashAlpha(api_key: str)
```

### Parameters
#### Path Parameters
- **api_key** (str) - Required - Your unique FlashAlpha API key.
```

--------------------------------

### Make Your First API Call

Source: https://github.com/flashalpha-lab/flashalpha-python/blob/main/docs/api.md

Use this command to make your first API call to fetch gamma exposure data for SPY. Replace YOUR_API_KEY with your actual API key.

```bash
curl -H "X-Api-Key: YOUR_API_KEY" https://lab.flashalpha.com/v1/exposure/gex/SPY
```

--------------------------------

### Get Options Exposure Key Levels and Summary

Source: https://github.com/flashalpha-lab/flashalpha-python/blob/main/README.md

Fetch key levels like call wall, put wall, and gamma flip, as well as a full exposure summary for a symbol. The narrative outlook is also available.

```python
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']}")

summary = fa.exposure_summary("SPY")                        # Full summary (Growth+)
narrative = fa.narrative("SPY")                              # AI narrative (Growth+)
print(narrative["narrative"]["outlook"])
```

--------------------------------

### Get Max Pain Analysis Request

Source: https://github.com/flashalpha-lab/flashalpha-python/blob/main/docs/api.md

Example cURL command to retrieve max pain analysis for a symbol. Requires an API key and the Basic plan or higher. The expiration parameter can be used to filter for a specific expiry date.

```bash
curl -H "X-Api-Key: YOUR_API_KEY" \
  "https://lab.flashalpha.com/v1/maxpain/SPY"
```

```bash
curl -H "X-Api-Key: YOUR_API_KEY" \
  "https://lab.flashalpha.com/v1/maxpain/SPY?expiration=2026-04-17"
```

--------------------------------

### Get Stock Summary (Authenticated)

Source: https://github.com/flashalpha-lab/flashalpha-python/blob/main/docs/api.md

Use this command to fetch live, real-time stock summary data. Ensure you replace 'YOUR_API_KEY' with your actual API key.

```bash
curl -H "X-Api-Key: YOUR_API_KEY" \
  "https://lab.flashalpha.com/v1/stock/SPY/summary"
```

--------------------------------

### Example API Response: 200 OK for Symbol List

Source: https://github.com/flashalpha-lab/flashalpha-python/blob/main/docs/api.md

A successful response listing available symbols and their count, along with a note on supported symbols and caching.

```json
{
  "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.",
  "last_updated": "2026-02-28T16:30:45Z"
}
```

--------------------------------

### Authenticate API Calls

Source: https://github.com/flashalpha-lab/flashalpha-python/blob/main/docs/api.md

Demonstrates how to authenticate API calls using the X-Api-Key header. This is required for most endpoints.

```bash
curl -H "X-Api-Key: YOUR_API_KEY" https://lab.flashalpha.com/v1/symbols
```

--------------------------------

### Run Integration Tests for FlashAlpha Python SDK

Source: https://github.com/flashalpha-lab/flashalpha-python/blob/main/CONTRIBUTING.md

Execute integration tests for the SDK. Requires setting the FLASHALPHA_API_KEY environment variable.

```bash
FLASHALPHA_API_KEY=your_key pytest tests/test_integration.py -m integration -v
```

--------------------------------

### GET /v1/exposure/summary/{symbol}

Source: https://github.com/flashalpha-lab/flashalpha-python/blob/main/docs/api.md

Returns a comprehensive exposure summary including net GEX/DEX/VEX/CHEX totals, gamma regime, and dealer hedging estimates. Requires Growth plan or higher.

```APIDOC
## GET /v1/exposure/summary/{symbol}

### Description
Returns a comprehensive exposure summary: net GEX/DEX/VEX/CHEX totals, gamma regime, verbal interpretation, dealer hedging estimates for +/-1% spot moves, and 0DTE contribution.

### Method
GET

### Endpoint
/v1/exposure/summary/{symbol}

### Parameters
#### Path Parameters
- **symbol** (string) - Required - Underlying symbol

### Request Example
```bash
curl -H "X-Api-Key: YOUR_API_KEY" \
  "https://lab.flashalpha.com/v1/exposure/summary/SPY"
```

### Response
#### Success Response (200)
- **symbol** (string) - Underlying symbol
- **underlying_price** (float) - The current price of the underlying asset
- **as_of** (string) - Timestamp of the data
- **gamma_flip** (float) - The gamma flip level
- **regime** (string) - The current market regime (e.g., positive_gamma)
- **exposures** (object) - Net exposure totals
  - **net_gex** (integer) - Net Gamma Exposure
  - **net_dex** (integer) - Net Delta Exposure
  - **net_vex** (integer) - Net Vanna Exposure
  - **net_chex** (integer) - Net Charm Exposure
- **interpretation** (object) - Verbal interpretations of exposures
  - **gamma** (string) - Interpretation of gamma exposure
  - **vanna** (string) - Interpretation of vanna exposure
  - **charm** (string) - Interpretation of charm exposure
- **hedging_estimate** (object) - Dealer hedging estimates for spot moves
  - **spot_down_1pct** (object) - Estimate for a 1% spot decrease
    - **dealer_shares_to_trade** (integer) - Number of shares dealers need to trade
    - **direction** (string) - Direction of trading (buy/sell)
    - **notional_usd** (integer) - Notional value in USD
  - **spot_up_1pct** (object) - Estimate for a 1% spot increase
    - **dealer_shares_to_trade** (integer) - Number of shares dealers need to trade
    - **direction** (string) - Direction of trading (buy/sell)
    - **notional_usd** (integer) - Notional value in USD
- **zero_dte** (object) - Contribution from 0DTE options
  - **net_gex** (integer) - Net GEX for 0DTE
  - **pct_of_total_gex** (float) - Percentage of total GEX from 0DTE
  - **expiration** (string) - Expiration date for 0DTE data

#### Response Example
```json
{
  "symbol": "SPY",
  "underlying_price": 597.505,
  "as_of": "2026-02-28T16:30:45Z",
  "gamma_flip": 595.25,
  "regime": "positive_gamma",
  "exposures": {
    "net_gex": 2850000000,
    "net_dex": -450000000,
    "net_vex": 1200000000,
    "net_chex": 850000000
  },
  "interpretation": {
    "gamma": "Dealers long gamma — expect range-bound, mean-reverting price action",
    "vanna": "Positive vanna — benefits from vol compression",
    "charm": "Time decay favors dealers — supports decline into close"
  },
  "hedging_estimate": {
    "spot_down_1pct": {
      "dealer_shares_to_trade": 4780000,
      "direction": "buy",
      "notional_usd": 2852000000
    },
    "spot_up_1pct": {
      "dealer_shares_to_trade": -4780000,
      "direction": "sell",
      "notional_usd": 2852000000
    }
  },
  "zero_dte": {
    "net_gex": 285000000,
    "pct_of_total_gex": 10.0,
    "expiration": "2026-02-28"
  }
}
```
```

--------------------------------

### Run Unit Tests for FlashAlpha Python SDK

Source: https://github.com/flashalpha-lab/flashalpha-python/blob/main/CONTRIBUTING.md

Execute unit tests for the SDK. No API key is required for these tests.

```bash
pytest tests/test_client.py -v
```

--------------------------------

### Get Account Details

Source: https://github.com/flashalpha-lab/flashalpha-python/blob/main/docs/api.md

Retrieve account details, plan, and usage quota for the authenticated user. Requires an API key in the request header.

```bash
curl -H "X-Api-Key: YOUR_API_KEY" https://lab.flashalpha.com/v1/account
```

--------------------------------

### GET /health

Source: https://github.com/flashalpha-lab/flashalpha-python/blob/main/docs/api.md

Performs a health check of the API.

```APIDOC
## GET /health

### Description
Health check.

### Method
GET

### Endpoint
`/health`
```

--------------------------------

### Kelly Option Sizing Response (200 OK)

Source: https://github.com/flashalpha-lab/flashalpha-python/blob/main/docs/api.md

A successful response includes input parameters, calculated sizing fractions (full, half, quarter Kelly), and detailed analysis metrics like expected ROI and probability of profit. The recommendation field provides a human-readable sizing suggestion.

```json
{
  "inputs": {
    "spot": 580, "strike": 580, "dte": 30, "sigma": 0.18, "premium": 12.69,
    "mu": 0.12, "type": "call", "risk_free_rate": 0.045, "dividend_yield": 0.013
  },
  "sizing": {
    "kelly_fraction": 0.076842,
    "half_kelly": 0.038421,
    "quarter_kelly": 0.01921,
    "kelly_pct": 7.68,
    "half_kelly_pct": 3.84
  },
  "analysis": {
    "expected_roi": 0.160546,
    "expected_roi_pct": 16.05,
    "expected_payoff": 14.7273,
    "probability_of_profit": 0.391739,
    "probability_of_profit_pct": 39.17,
    "probability_itm": 0.557494,
    "probability_itm_pct": 55.75,
    "max_loss": 12.69,
    "breakeven": 592.69,
    "expected_growth_rate": 0.00584368
  },
  "recommendation": "Risk 3.8% of bankroll (half-Kelly). Probability of profit: 39.2%. Expected ROI: 16.1%."
}
```

--------------------------------

### GET /v1/tickers

Source: https://github.com/flashalpha-lab/flashalpha-python/blob/main/docs/api.md

Retrieves a list of all available stock tickers.

```APIDOC
## GET /v1/tickers

### Description
All available stock tickers.

### Method
GET

### Endpoint
`/v1/tickers`
```

--------------------------------

### Get Key Options-Derived Levels

Source: https://context7.com/flashalpha-lab/flashalpha-python/llms.txt

Retrieve key options-derived levels for technical analysis, including the gamma flip, call wall, put wall, max/min gamma strikes, highest OI strike, and 0DTE intraday magnet. This endpoint is available on the Free tier.

```python
result = fa.exposure_levels("SPY")
lvl = result["levels"]

print(f"Spot:              {result['underlying_price']}")
print(f"Gamma flip:        {lvl['gamma_flip']}   ← regime boundary")
print(f"Call wall (resist):{lvl['call_wall']}")
print(f"Put wall (support):{lvl['put_wall']}")
print(f"0DTE magnet:       {lvl['zero_dte_magnet']}")
print(f"Highest OI strike: {lvl['highest_oi_strike']}")
```

--------------------------------

### GET /v1/pricing/kelly

Source: https://github.com/flashalpha-lab/flashalpha-python/blob/main/docs/api.md

Retrieves Kelly criterion sizing for options.

```APIDOC
## GET /v1/pricing/kelly

### Description
Kelly criterion sizing for options.

### Method
GET

### Endpoint
`/v1/pricing/kelly`
```

--------------------------------

### GET /v1/pricing/iv

Source: https://github.com/flashalpha-lab/flashalpha-python/blob/main/docs/api.md

Retrieves implied volatility from market price.

```APIDOC
## GET /v1/pricing/iv

### Description
Implied volatility from market price.

### Method
GET

### Endpoint
`/v1/pricing/iv`
```

--------------------------------

### GET /v1/symbols

Source: https://github.com/flashalpha-lab/flashalpha-python/blob/main/docs/api.md

Retrieves currently queried symbols with live data.

```APIDOC
## GET /v1/symbols

### Description
Currently queried symbols with live data.

### Method
GET

### Endpoint
`/v1/symbols`
```

--------------------------------

### Get Comprehensive Exposure Summary

Source: https://github.com/flashalpha-lab/flashalpha-python/blob/main/docs/api.md

Retrieves a detailed exposure summary including GEX, DEX, VEX, CHEX, gamma regime, and hedging estimates. Requires Growth plan or higher.

```bash
curl -H "X-Api-Key: YOUR_API_KEY" \
  "https://lab.flashalpha.com/v1/exposure/summary/SPY"
```

--------------------------------

### AI Narrative

Source: https://github.com/flashalpha-lab/flashalpha-python/blob/main/README.md

Get an AI-generated narrative and outlook for a given symbol.

```APIDOC
## AI Narrative

### Description
Retrieves an AI-generated narrative and market outlook for a specified underlying asset, providing insights into current market conditions and potential future movements.

### Method
```python
fa.narrative(symbol: str)
```

### Parameters
#### Path Parameters
- **symbol** (str) - Required - The ticker symbol of the underlying asset (e.g., 'SPY').

### Response
#### Success Response (200)
- **narrative** (dict) - A dictionary containing the AI-generated narrative, including:
    - **outlook** (str) - The AI-generated market outlook.
```

--------------------------------

### Fetch Account Information

Source: https://context7.com/flashalpha-lab/flashalpha-python/llms.txt

Retrieves account details including the subscription plan, daily quota limit, usage today, remaining requests, and reset time. Requires authentication.

```python
# Account info
acct = fa.account()
print(f"Plan:      {acct['plan']}")
print(f"Limit:     {acct['daily_limit']}")
print(f"Used:      {acct['usage_today']}")
print(f"Remaining: {acct['remaining']}")
print(f"Resets at: {acct['resets_at']}")
```

--------------------------------

### Error Handling

Source: https://github.com/flashalpha-lab/flashalpha-python/blob/main/README.md

Example of how to handle common errors when using the FlashAlpha API.

```APIDOC
## Error Handling

### Description
Demonstrates how to handle potential errors when interacting with the FlashAlpha API, such as authentication issues, tier restrictions, not found errors, and rate limiting.

### Request Example
```python
from flashalpha import (
    FlashAlpha,
    AuthenticationError,
    TierRestrictedError,
    NotFoundError,
    RateLimitError,
)

fa = FlashAlpha("YOUR_API_KEY")

try:
    data = fa.exposure_summary("SPY")
except AuthenticationError:
    print("Invalid API key")
except TierRestrictedError as e:
    print(f"Need {e.required_plan} plan (you have {e.current_plan})")
except NotFoundError:
    print("Symbol not found")
except RateLimitError as e:
    print(f"Rate limited — retry after {e.retry_after}s")
```

### Error Types
- **AuthenticationError**: Raised for invalid API keys.
- **TierRestrictedError**: Raised when the requested resource requires a higher API plan.
- **NotFoundError**: Raised when a requested symbol or resource is not found.
- **RateLimitError**: Raised when the API rate limit has been exceeded.
```

--------------------------------

### REST API: Live Screener (POST)

Source: https://context7.com/flashalpha-lab/flashalpha-python/llms.txt

Performs a live screener query using a POST request with a JSON body. Requires an API key and Content-Type header. This is a Growth+ feature.

```bash
# Live screener — POST with JSON body (Growth+)
curl -H "X-Api-Key: YOUR_API_KEY" -H "Content-Type: application/json" \
  -X POST https://lab.flashalpha.com/v1/screener \
  -d '{"filters":{"field":"harvest_score","operator":"gte","value":70},"sort":[{"field":"harvest_score","direction":"desc"}],"select":["symbol","harvest_score"]}'
```

--------------------------------

### GET /v1/volatility/{symbol}

Source: https://github.com/flashalpha-lab/flashalpha-python/blob/main/docs/api.md

Retrieves comprehensive volatility analysis for a given symbol.

```APIDOC
## GET /v1/volatility/{symbol}

### Description
Comprehensive volatility analysis.

### Method
GET

### Endpoint
`/v1/volatility/{symbol}`

### Parameters
#### Path Parameters
- **symbol** (string) - Required - The equity or ETF symbol.
```

--------------------------------

### Analyze 0DTE Pin Risk with FlashAlpha

Source: https://github.com/flashalpha-lab/flashalpha-python/blob/main/article-flashalpha-python-sdk.md

Initializes the FlashAlpha client and retrieves 0DTE data for SPY to analyze pin risk metrics. Requires an API key.

```python
from flashalpha import FlashAlpha

fa = FlashAlpha("YOUR_API_KEY")

dte = fa.zero_dte("SPY")
pin = dte["pin_risk"]
print(f"Pin score:     {pin['pin_score']}/100")
print(f"Magnet strike: {pin['magnet_strike']}")
print(f"Distance:      {pin['distance_to_magnet_pct']:.2f}%")
print(f"Max pain:      {pin['max_pain']}")
print(f"Top 3 OI:      {pin['oi_concentration_top3_pct']:.1f}%")
```

--------------------------------

### GET /v1/exposure/narrative/{symbol}

Source: https://github.com/flashalpha-lab/flashalpha-python/blob/main/docs/api.md

Retrieves verbal narrative analysis for a given symbol.

```APIDOC
## GET /v1/exposure/narrative/{symbol}

### Description
Verbal narrative analysis.

### Method
GET

### Endpoint
`/v1/exposure/narrative/{symbol}`

### Parameters
#### Path Parameters
- **symbol** (string) - Required - The equity or ETF symbol.
```

--------------------------------

### Get Volatility Analysis for a Symbol

Source: https://github.com/flashalpha-lab/flashalpha-python/blob/main/docs/api.md

Fetches comprehensive volatility analysis for a given US equity or ETF symbol. This includes realized volatility, IV-RV spreads, skew profiles, term structure, GEX by DTE, theta decay, put/call breakdowns, OI concentration, hedging scenarios, and liquidity analysis.

```bash
curl -H "X-Api-Key: YOUR_API_KEY" https://lab.flashalpha.com/v1/volatility/TSLA
```

--------------------------------

### Authenticate API Calls with Query Parameter

Source: https://github.com/flashalpha-lab/flashalpha-python/blob/main/docs/api.md

Shows an alternative method for API authentication by passing the API key as a query parameter. This is useful for environments where headers are restricted.

```bash
https://lab.flashalpha.com/v1/symbols?apiKey=YOUR_API_KEY
```

--------------------------------

### GET /v1/surface/{symbol}

Source: https://github.com/flashalpha-lab/flashalpha-python/blob/main/docs/api.md

Retrieves the volatility surface grid for a given symbol.

```APIDOC
## GET /v1/surface/{symbol}

### Description
Volatility surface grid.

### Method
GET

### Endpoint
`/v1/surface/{symbol}`

### Parameters
#### Path Parameters
- **symbol** (string) - Required - The equity or ETF symbol.
```

--------------------------------

### GET /optionquote/{ticker}

Source: https://github.com/flashalpha-lab/flashalpha-python/blob/main/docs/api.md

Retrieves option quotes with Greeks for a given ticker.

```APIDOC
## GET /optionquote/{ticker}

### Description
Option quotes with greeks.

### Method
GET

### Endpoint
`/optionquote/{ticker}`

### Parameters
#### Path Parameters
- **ticker** (string) - Required - The stock ticker symbol.
```

--------------------------------

### Example 200 Response for Options Chain Analysis

Source: https://github.com/flashalpha-lab/flashalpha-python/blob/main/docs/api.md

This JSON object represents a successful response for an options chain analysis query. It includes details on max pain, open interest, dealer alignment, and expected move.

```json
{
  "symbol": "SPY",
  "underlying_price": 548.32,
  "as_of": "2026-04-09T15:30:00Z",
  "max_pain_strike": 545,
  "distance": {
    "absolute": 3.32,
    "percent": 0.61,
    "direction": "above"
  },
  "signal": "neutral",
  "expiration": "2026-04-17",
  "put_call_oi_ratio": 1.284,
  "pain_curve": [
    { "strike": 540, "call_pain": 0, "put_pain": 18500000, "total_pain": 18500000 },
    { "strike": 545, "call_pain": 2500000, "put_pain": 1200000, "total_pain": 3700000 },
    { "strike": 550, "call_pain": 8400000, "put_pain": 0, "total_pain": 8400000 }
  ],
  "oi_by_strike": [
    { "strike": 540, "call_oi": 12000, "put_oi": 28000, "total_oi": 40000, "call_volume": 3200, "put_volume": 5800 },
    { "strike": 545, "call_oi": 35000, "put_oi": 42000, "total_oi": 77000, "call_volume": 8100, "put_volume": 9400 },
    { "strike": 550, "call_oi": 18000, "put_oi": 8000, "total_oi": 26000, "call_volume": 4500, "put_volume": 2100 }
  ],
  "max_pain_by_expiration": [
    { "expiration": "2026-04-11", "max_pain_strike": 547, "dte": 2, "total_oi": 520000 },
    { "expiration": "2026-04-17", "max_pain_strike": 545, "dte": 8, "total_oi": 1840000 },
    { "expiration": "2026-05-16", "max_pain_strike": 540, "dte": 37, "total_oi": 980000 }
  ],
  "dealer_alignment": {
    "alignment": "converging",
    "description": "Max pain (545) near gamma flip (546) between walls (538–555) — strong converging magnet.",
    "gamma_flip": 546,
    "call_wall": 555,
    "put_wall": 538
  },
  "regime": "positive_gamma",
  "expected_move": {
    "straddle_price": 4.82,
    "atm_iv": 18.4,
    "max_pain_within_expected_range": true
  },
  "pin_probability": 68
}
```