# WSO Options Data API — Complete Documentation
Base URL: https://api.wheelstrategyoptions.com

---

# Overview & Quickstart
Base URL: https://api.wheelstrategyoptions.com
All requests must be served over HTTPS. Bearer token authentication required for protected routes. Public metadata endpoints (/health, /ready, /openapi.json, /public/plans) do not require authentication.

First request:
```bash
curl -H "Authorization: Bearer wso_live_YOUR_KEY" https://api.wheelstrategyoptions.com/v1/chain/AAPL
```

---

# Authentication & Keys
Format: Authorization: Bearer wso_live_<49 base62 chars> (58 characters total)
Maximum 5 active keys per account. Legacy wsk_ keys are rejected.

---

# Rate Limits & Clamping
- Single subscription plan: Basic. See /pricing for current price and limits.
- Enforces per-minute GCRA rate limits and concurrency caps per account.
- Rate-limit headers: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset.
- Clamping headers: X-Limit-Clamped set to true when results or history windows are clamped.
- When throttled, the server returns HTTP 429 with a Retry-After header.

---

# Errors & Troubleshooting
Standard error envelope:
```json
{
  "error": "code_string",
  "message": "human readable explanation",
  "status": 400,
  "timestamp": "ISO-8601",
  "request_id": "c7a9b1c0-4f2e-4d1a-8c3b-5e6f7a8b9c0d"
}
```
Honour Retry-After header on HTTP 429. See /docs/errors for complete error catalog.

---

# Option Screener Guide (POST /v1/contracts/screen)
Filter candidate contracts across Greeks, DTE, strike distance, return on collateral, and earnings events.

Supported Filter Operations (20 operations from OpenAPI spec):
- Comparison: `gt`, `gte`, `lt`, `lte`, `eq`, `>`, `>=`, `<`, `<=`, `=`, `==` (numerical and date threshold comparisons)
- Pattern Matching: `like` (substring matching on text columns)
- Set Membership: `in`, `exclude` (array or comma-separated list inclusion / exclusion)
- Specialized Filters:
  - `excludeEarnings`: earnings calendar exclusion filter. Contract mode (default / omitted value) drops contracts whose expiration date is within ±7 days of the company's earnings date. Symbol mode (`value: "symbol"` or `"ticker"`) drops symbols scheduled to report earnings within the next 7 calendar days. Does not drop contracts whose expiration spans an earnings event.
  - `cleanupLiquidity`: domain-specific liquidity cleanup filter
  - `lastTradeToday`: filters contracts traded in today's trading session
  - `lastTradeRecent`: filters contracts with recent trading activity
  - `strikeFilter`: strike price criteria filter
- Ordering: `sort` (ordering predicate using value "asc" or "desc")

Note: `neq` and `between` are not supported by the screener.

Sort Grammar:
To sort results, specify a sort filter object:
```json
{"field": "<fieldName>", "operation": "sort", "value": "asc" | "desc"}
```

Supported Filter & Sort Fields (98 accepted fields from OpenAPI spec):
- **Contract & Option Spec**: `call`, `cushion`, `daysToExpiration`, `dte`, `expiration`, `expirationDays`, `expiration_days`, `moneyness`, `put`, `strike`, `strikeFilter`, `type`
- **Pricing & Spreads**: `annualizedReturn`, `askPrice`, `bidAskSpread`, `bidAskSpreadAbs`, `bidAskSpreadDollar`, `bidAskSpreadPct`, `bidAskSpreadPercent`, `bidPrice`, `lastPrice`, `markOneDayAgo`, `premium`, `premiumChange1dPct`, `spread`, `spreadAbs`, `spreadPct`, `stockPrice`, `thirtyDayAveragePremium`, `yieldPercent`
- **Greeks & Volatility**: `delta`, `gamma`, `highestStockIV`, `impliedVolatility`, `iv`, `ivr`, `lowestStockIV`, `stockIV`, `theta`, `thirtyDayAverageIV`, `vega`
- **Volume & Liquidity**: `liquidity`, `openInterest`, `openInterestHistorySamples30d`, `openInterestStdDevDiff`, `openInterestStdDevDiff30d`, `openInterestZScore`, `openInterestZScore30d`, `premiumIncreasing`, `premiumIncreasing30d`, `thirtyDayAverageVolume`, `volume`, `volumeHistorySamples30d`, `volumeStdDevDiff`, `volumeStdDevDiff30d`, `volumeZScore`, `volumeZScore30d`
- **Underlying & Fundamentals**: `consensus`, `fiftyDayAverage`, `fiftyTwoWeekHigh`, `fiftyTwoWeekLow`, `industry`, `lastTradeDate`, `lastUpdatedDate`, `marketCap`, `peRatio`, `probability`, `rating`, `rsi`, `sector`, `stockType`, `symbol`, `symbolType`, `symbols`, `twoHundredDayAverage`
- **Earnings & Calendars**: `dividendFrequency`, `dividendIsEstimated`, `dividendYield`, `dividendamount`, `dividenddate`, `dividenddays`, `dividendpaymentdate`, `earnings`, `earningsDate`, `exdividenddate`, `nextDividendAmount`, `nextDividendDate`, `nextDividendDays`, `nextDividendIsEstimated`, `nextDividendPaymentDate`
- **Scoring & Financial Health**: `contractScore`, `debtToEquityScore`, `discountedCashFlowScore`, `overallScore`, `priceToBookScore`, `priceToEarningsScore`, `returnOnAssetsScore`, `returnOnEquityScore`

Worked Examples:

### Cash-Secured Put Candidates (30–45 DTE, -0.30 to -0.20 Delta)
Standard 30–45 DTE cash-secured put selling setup seeking 20–30 delta out-of-the-money puts with minimum open interest and 1.5%+ raw return on collateral:
```json
{
  "type": "put",
  "dteMin": 30,
  "dteMax": 45,
  "deltaMin": -0.3,
  "deltaMax": -0.2,
  "openInterestMin": 500,
  "yieldPercentMin": 1.5,
  "perPage": 10
}
```

### Covered-Call Candidates across Watchlist
Scans specific underlying holdings for call selling opportunities between 21 and 45 DTE with delta between 0.25 and 0.35 and tight bid-ask spreads (bidAskSpreadPctMax is percent: 8 means 8%):
```json
{
  "type": "call",
  "symbols": [
    "AAPL",
    "MSFT",
    "NVDA"
  ],
  "dteMin": 21,
  "dteMax": 45,
  "deltaMin": 0.25,
  "deltaMax": 0.35,
  "bidAskSpreadPctMax": 8,
  "perPage": 10
}
```

### High IV Rank Excluding Earnings Window
Filters for options with high Implied Volatility Rank (IVR >= 50) while excluding contracts whose expiration falls within ±7 days of an earnings date (or use {"field": "earnings", "operation": "excludeEarnings", "value": "symbol"} to exclude underlyings reporting within the next 7 days):
```json
{
  "filters": [
    {
      "field": "ivr",
      "operation": "gte",
      "value": 50
    },
    {
      "field": "type",
      "operation": "eq",
      "value": "put"
    },
    {
      "field": "dte",
      "operation": "lte",
      "value": 45
    },
    {
      "field": "earnings",
      "operation": "excludeEarnings"
    }
  ],
  "perPage": 10
}
```

### Ranked by Contract Score (Explicit Sort)
Demonstrates explicit multi-factor sorting using {"field": "<field>", "operation": "sort", "value": "asc"|"desc"}. Supplying an explicit sort predicate is recommended over relying on default order:
```json
{
  "type": "put",
  "dteMin": 30,
  "dteMax": 45,
  "deltaMin": -0.3,
  "deltaMax": -0.2,
  "filters": [
    {
      "field": "contractScore",
      "operation": "sort",
      "value": "desc"
    }
  ],
  "perPage": 10
}
```

---

# Field Conventions
This section details field naming conventions, schema mappings, and unit representations across the WSO Options Data API.

## Endpoint Field Mapping
| Concept | Schema | Field Name | Format / Units | Notes |
|---|---|---|---|---|
| Underlying Symbol | QuoteResponse | `symbol` | string (ticker) | Primary underlying equity ticker symbol. |
| Underlying Symbol | FlowTradePrint | `ticker` | string (ticker) | Underlying equity ticker in options flow trade prints. |
| Underlying Symbol | OptionQuote | `underlying` | string (ticker) | Reference to underlying equity ticker in contract quote objects. |
| Option Contract Symbol | OptionQuote | `optionSymbol` | string (OCC format) | Standard OCC option symbol (e.g. SPY270917C00800000; up to 21 chars). |
| Option Contract Symbol | FilterResult | `optionKey` | string (OCC format) | Contract key in screener candidate rows. |
| Underlying Spot Price | QuoteResponse | `price` | number (dollars) | Current underlying equity spot price in USD. |
| Underlying Spot Price | OptionQuote | `underlyingPrice` | number (dollars) | Underlying equity spot price at option quote capture. |
| Underlying Spot Price | FlowTradePrint | `underlyingPrice` | number (dollars) | Underlying stock price at options flow trade execution. |
| Underlying Spot Price | FilterResult | `stockPrice` | number (dollars) | Underlying equity price at screener evaluation time. |
| Bid & Ask Prices | OptionQuote | `bid` | number (dollars/share) | Highest buying price per share in market quote. |
| Bid & Ask Prices | OptionQuote | `ask` | number (dollars/share) | Lowest selling price per share in market quote. |
| Bid & Ask Prices | FilterResult | `bidPrice` | number (dollars/share) | Best bid price per share in screener candidate contracts. |
| Option Side & Type | OptionQuote | `side` | "call" | "put" | Contract flavor in options chain and quote responses. |
| Option Side & Type | FlowTradePrint | `side` | "ask" | "bid" | "mid" | "unknown" | Trade execution / fill side on the tape. |
| Option Side & Type | FlowTradePrint | `optionType` | "call" | "put" | Contract flavor (call or put) in options flow trade prints. |
| Option Side & Type | FilterResult | `type` | "call" | "put" | Contract flavor in screener results. |
| Expiration & Timestamps | OptionQuote | `expiration` | string (YYYY-MM-DD) | Option contract expiration calendar date. |
| Expiration & Timestamps | FilterResult | `expiration` | string (ISO-8601) | Contract expiration timestamp in screener results. |
| Expiration & Timestamps | OptionQuote | `asOf` | string (ISO-8601 UTC) or null | Timestamp of market quote snapshot, or null if unknown. |
| Expiration & Timestamps | QuoteResponse | `asOf` | string (ISO-8601 UTC) or null | Timestamp of equity quote snapshot, or null if unknown. |
| Volatility & Greeks | OptionQuote | `iv` | number (percentage) | Implied volatility expressed as percentage (e.g. 22.37 represents 22.37%). |
| Volatility & Greeks | OptionQuote | `delta` | number (decimal fraction) | Option delta sensitivity, bounded between -1.0 and 1.0. |
| Volatility & Greeks | OptionQuote | `gamma` | number (decimal) | Option gamma rate of change per $1 move in underlying. |
| Volatility & Greeks | OptionQuote | `theta` | number (dollars/day) | Option time decay per calendar day. |
| Volatility & Greeks | OptionQuote | `vega` | number (dollars/% IV) | Option price change per 1% change in implied volatility. |
| Volatility & Greeks | TopIvStock | `stockIV` | number (percentage) | Underlying equity 30-day annualized implied volatility percentage. |
| Volatility & Greeks | TopIvStock | `ivr` | number (0–100 rank) | Implied Volatility Rank over 52-week high/low range. |
| Gamma Exposure & Grid | GexHeatmapCell | `callGex` | number (dollars/1% move) | Dealer gamma exposure from call open interest at cell coordinate. |
| Gamma Exposure & Grid | GexHeatmapCell | `putGex` | number (dollars/1% move) | Dealer gamma exposure from put open interest at cell coordinate. |
| Gamma Exposure & Grid | GexHeatmapCell | `netGex` | number (dollars/1% move) | Net dealer gamma exposure at strike/expiration cell. |
| Net Flow Time Series | NetFlowPoint | `netCallPremium` | number (dollars) | Net call premium flow for the 1-minute aggregation interval. |

## Key Unit Representations
- Implied Volatility (IV): Contract IV (`iv`) and equity volatility (`stockIV`) are expressed as percentages: 22.37 represents 22.37%. IV rank (`ivr`) is a 0–100 percentile ranking.
- Bid-Ask Spreads: Percentage spread fields (`spreadPercent`, `bidAskSpreadPct`, `bidAskSpreadPctMax`) are expressed as percentages: 8 represents 8%. Absolute spread fields (`bidAskSpreadAbs`) represent dollar amounts.
- Greeks & Sensitivities: Delta is a signed decimal ratio bounded strictly between -1.0 and 1.0 (e.g. -0.25). Other Greeks have unit-based dimensions: gamma is delta change per $1 underlying move, theta is daily decay in dollars, vega is dollar change per 1% move in implied volatility.
- OCC Option Symbols: Option contract keys follow standard OCC symbology up to 21 characters: 1–6 character underlying ticker root, 6-digit expiration date (YYMMDD), contract type ('C' or 'P'), and 8-digit strike price in thousandths of a dollar (e.g. `SPY270917C00800000`).

---

# Complete Endpoint Reference

## Service health check probe
Method: GET
Path: /health
Plan: All accounts
Description: Returns HTTP 200 and binary version string when the API service process is active.

Sample (cURL):
```bash
curl "https://api.wheelstrategyoptions.com/health"
```


## Dependency readiness probe
Method: GET
Path: /ready
Plan: All accounts
Description: Probes connectivity to the primary market database and control plane databases.

Sample (cURL):
```bash
curl "https://api.wheelstrategyoptions.com/ready"
```


## OpenAPI 3.1.0 contract document
Method: GET
Path: /openapi.json
Plan: All accounts
Description: Returns the complete OpenAPI 3.1.0 specification with ETag and public caching.

Parameters:
- If-None-Match (header, string): ETag value for conditional cache validation.

Sample (cURL):
```bash
curl "https://api.wheelstrategyoptions.com/openapi.json"
```


## OpenAPI contract document alias
Method: GET
Path: /v1/openapi.json
Plan: All accounts
Description: Versioned alias for GET /openapi.json.

Parameters:
- If-None-Match (header, string): ETag value for conditional cache validation.

Sample (cURL):
```bash
curl "https://api.wheelstrategyoptions.com/v1/openapi.json"
```


## Verify credentials and entitlement
Method: GET
Path: /v1/auth/verify
Plan: All accounts
Description: Verifies that an API key is valid, unrevoked, and checks active tier subscription status.

Sample (cURL):
```bash
curl -s -H "Authorization: Bearer $WSO_API_KEY" \
  "https://api.wheelstrategyoptions.com/v1/auth/verify"
```


## Get account usage and limits
Method: GET
Path: /v1/usage
Plan: All accounts
Description: Account usage metrics and rate limits.

Sample (cURL):
```bash
curl -s -H "Authorization: Bearer $WSO_API_KEY" \
  "https://api.wheelstrategyoptions.com/v1/usage"
```


## Get equity spot price quote
Method: GET
Path: /v1/quotes/{symbol}
Plan: Included in Basic
Description: Retrieves the latest equity spot quote and company profile name.

Parameters:
- symbol (path, string, required): Underlying equity ticker symbol (1-10 uppercase alphanumeric, dot, or hyphen). Invalid format returns 400 invalid_parameter.

Sample (cURL):
```bash
curl -s -H "Authorization: Bearer $WSO_API_KEY" \
  "https://api.wheelstrategyoptions.com/v1/quotes/AAPL"
```


## Get single option contract quote
Method: GET
Path: /v1/options/quotes/{optionSymbol}
Plan: Included in Basic
Description: Returns option pricing, Greeks, volume, and open interest for an OCC contract symbol.

Parameters:
- optionSymbol (path, string, required): Full OCC option contract symbol. Missing symbol returns 400 missing_symbol.

Sample (cURL):
```bash
curl -s -H "Authorization: Bearer $WSO_API_KEY" \
  "https://api.wheelstrategyoptions.com/v1/options/quotes/SPY270917C00800000"
```


## Batch fetch multiple option quotes
Method: GET
Path: /v1/options/quotes
Plan: Included in Basic
Description: Retrieves quotes for up to 20 comma-separated OCC option symbols in a single request. A batch counts as one request however many symbols it names; duplicate symbols are queried and returned once. Unknown symbols are returned in the `missing` array. Result order of quotes is unspecified.

Parameters:
- symbols (query, string, required): Comma-separated list of up to 20 OCC option symbols. Exceeding 20 returns 400 too_many_symbols.

Sample (cURL):
```bash
curl -s -H "Authorization: Bearer $WSO_API_KEY" \
  "https://api.wheelstrategyoptions.com/v1/options/quotes?symbols=SPY270917C00800000,SPY270917P00750000"
```


## Get option expiration schedule
Method: GET
Path: /v1/expirations/{symbol}
Plan: Included in Basic
Description: Returns available expiration dates and days to expiry (DTE) for an underlying stock.

Parameters:
- symbol (path, string, required): Underlying equity ticker symbol. Missing symbol returns 400 missing_symbol.
- minDte (query, integer): Minimum days to expiration (alias: dteMin; default 0).
- maxDte (query, integer): Maximum days to expiration (alias: dteMax; default 365; 0 means unset, defaulting to 365).

Sample (cURL):
```bash
curl -s -H "Authorization: Bearer $WSO_API_KEY" \
  "https://api.wheelstrategyoptions.com/v1/expirations/AAPL"
```


## Get filtered option chain matrix
Method: GET
Path: /v1/chain/{symbol}
Plan: Included in Basic
Description: Returns option chain contracts matrix with pricing and Greeks. Defaults to max 45 DTE window (or minDte+45 if minDte is specified). Default limit is 500; when your plan's max_rows is below the default (or requested limit exceeds max_rows), limit is clamped and X-Limit-Clamped is set to true. Near-spot pages keep the page-1 spot as underlyingPrice, and each page is sorted by expiration/strike/type for display (pages are not globally sorted).

Parameters:
- symbol (path, string, required): Underlying equity ticker symbol.
- expiration (query, string): Filter by expiration date in YYYY-MM-DD format.
- side (query, string): Filter by option side ('call' or 'put').
- strikeMin (query, number): Minimum strike price filter. strikeMin > strikeMax returns 400 invalid_range.
- strikeMax (query, number): Maximum strike price filter.
- deltaMin (query, number): Filter by minimum absolute delta value. Signed put deltas (e.g. -0.30) are accepted and normalised to absolute values [0.0 to 1.0]. |delta| > 1 returns 400 invalid_parameter.
- deltaMax (query, number): Filter by maximum absolute delta value. Signed put deltas (e.g. -0.30) are accepted and normalised to absolute values [0.0 to 1.0]. |delta| > 1 returns 400 invalid_parameter.
- cursor (query, string): Opaque pagination cursor to fetch the next page of results.
- minOI (query, integer): Minimum open interest contract floor (alias: oiMin).
- minVolume (query, integer): Minimum daily trading volume filter (alias: volumeMin).
- minDte (query, integer): Minimum days to expiration (alias: dteMin).
- maxDte (query, integer): Maximum days to expiration (defaults to minDte + 45 when unset; 0 means unset).
- limit (query, integer): Maximum number of contracts to return. Capped at your account plan's max_rows limit; see https://api.wheelstrategyoptions.com/pricing.

Sample (cURL):
```bash
curl -s -H "Authorization: Bearer $WSO_API_KEY" \
  "https://api.wheelstrategyoptions.com/v1/chain/AAPL?side=call&limit=50"
```


## Screen option contracts with multi-factor filters
Method: POST
Path: /v1/contracts/screen
Plan: Included in Basic
Description: Screen option contracts matching custom filter predicates. Request body page and pageSize take precedence over query parameters; query parameters apply only when body values are <= 0. Results are silently capped at 100 contracts (not plan-clamped). Default sort order is option_key ASC (or expiration ASC, strike ASC, option_key ASC when a single symbol is pinned); specifying an explicit sort filter (e.g. contractScore desc) is recommended.

Parameters:
- page (query, integer): Page number (1-based; body value takes precedence if > 0; query applies only when body page <= 0).
- pageSize (query, integer): Results per page (1 to 100, default 10; body value takes precedence if > 0; query applies only when body pageSize <= 0; values > 100 capped silently).

Sample (cURL):
```bash
curl -s -X POST -H "Authorization: Bearer $WSO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"symbols":["AAPL"],"deltaMax":0.35,"dteMax":45}' \
  "https://api.wheelstrategyoptions.com/v1/contracts/screen"
```


## Get earnings calendar events
Method: GET
Path: /v1/earnings
Plan: Included in Basic
Description: Returns scheduled earnings announcement dates and estimates. Default window is 30 days starting from current date in America/New_York (ET); maximum date range is 90 days. Default limit is 1000; when your plan's max_rows is below the default (or requested limit exceeds max_rows), limit is clamped and X-Limit-Clamped is set to true. X-Limit-Clamped is also set when the date range exceeds your plan's history window.

Parameters:
- from (query, string): Window start date in YYYY-MM-DD format. Clamped to account history_days. from > to returns 400 invalid_range.
- to (query, string): Window end date in YYYY-MM-DD format. Range cannot exceed 90 days (400 invalid_range).
- symbol (query, string): Filter by equity ticker symbol. Invalid symbol returns 400 invalid_parameter.
- cursor (query, string): Opaque pagination cursor to fetch the next page of results.
- limit (query, integer): Maximum events to return (1-1000, default 250). Clamped to plan max_rows.

Sample (cURL):
```bash
curl -s -H "Authorization: Bearer $WSO_API_KEY" \
  "https://api.wheelstrategyoptions.com/v1/earnings?symbol=DAL"
```


## Get dividend ex-date calendar
Method: GET
Path: /v1/dividends
Plan: Included in Basic
Description: Returns expected dividend payment dates, cash amounts, and yields. Default window is 30 days starting from current date in America/New_York (ET); maximum date range is 90 days. The unfiltered calendar excludes symbols outside our coverage universe (the stocks/ETFs we carry options data for) — e.g. foreign/OTC listings and non-optionable funds such as many closed-end funds and ETNs; pass includeAll=true to list every symbol in the source. A symbol you request explicitly is always returned. Default limit is 1000; when your plan's max_rows is below the default (or requested limit exceeds max_rows), limit is clamped and X-Limit-Clamped is set to true. X-Limit-Clamped is also set when the date range exceeds your plan's history window.

Parameters:
- from (query, string): Window start date in YYYY-MM-DD format. Clamped to account history_days. from > to returns 400 invalid_range.
- to (query, string): Window end date in YYYY-MM-DD format. Range cannot exceed 90 days (400 invalid_range).
- symbol (query, string): Filter by equity ticker symbol. Invalid symbol returns 400 invalid_parameter.
- cursor (query, string): Opaque pagination cursor to fetch the next page of results.
- includeAll (query, boolean): Include symbols outside our coverage universe (the stocks/ETFs we carry options data for) — e.g. foreign/OTC listings and non-optionable funds such as many closed-end funds and ETNs; defaults to false. When true, lists every symbol in the source. A symbol you request explicitly is always returned.
- limit (query, integer): Maximum events to return (1-1000, default 250). Clamped to plan max_rows.

Sample (cURL):
```bash
curl -s -H "Authorization: Bearer $WSO_API_KEY" \
  "https://api.wheelstrategyoptions.com/v1/dividends"
```


## Get implied volatility context
Method: GET
Path: /v1/iv/{symbol}
Plan: Included in Basic
Description: Returns current 30-day implied volatility, IV rank (IVR), 52-week high/low, and IV percentile (IVP).

Parameters:
- symbol (path, string, required): Underlying equity ticker symbol. Missing symbol returns 400 missing_symbol.

Sample (cURL):
```bash
curl -s -H "Authorization: Bearer $WSO_API_KEY" \
  "https://api.wheelstrategyoptions.com/v1/iv/AAPL"
```


## Get stocks with highest implied volatility
Method: GET
Path: /v1/stocks/top-iv
Plan: Included in Basic
Description: Returns equities ranked by highest annualized implied volatility, excluding stocks with IV > 200%. Limit defaults to 20; capped at your account plan's max_rows; requests exceeding 100 are capped silently.

Parameters:
- limit (query, integer): Maximum stocks to return (1-100, default 20). Clamped to plan max_rows.

Sample (cURL):
```bash
curl -s -H "Authorization: Bearer $WSO_API_KEY" \
  "https://api.wheelstrategyoptions.com/v1/stocks/top-iv?limit=20"
```


## Get stocks with highest IV rank
Method: GET
Path: /v1/stocks/top-ivr
Plan: Included in Basic
Description: Returns equities ranked by highest 52-week IV rank (IVR), excluding stocks with IV > 200%. Limit defaults to 20; capped at your account plan's max_rows; requests exceeding 100 are capped silently.

Parameters:
- limit (query, integer): Maximum stocks to return (1-100, default 20). Clamped to plan max_rows.

Sample (cURL):
```bash
curl -s -H "Authorization: Bearer $WSO_API_KEY" \
  "https://api.wheelstrategyoptions.com/v1/stocks/top-ivr?limit=20"
```


## Get dealer gamma exposure profile
Method: GET
Path: /v1/gex/{symbol}
Plan: Included in Basic
Description: Returns aggregate dealer gamma positioning, gamma flip threshold, and major call/put walls.

Parameters:
- symbol (path, string, required): Underlying equity ticker symbol (e.g. SPY, AAPL).
- minDte (query, integer): Minimum DTE horizon filter (alias: dteMin, default 0).
- maxDte (query, integer): Maximum days to expiration (alias: dteMax; default 60; max 730). In GEX, maxDte=0 filters for 0DTE contracts (same-day expiration) for backward compatibility; see also zeroDte=true.
- zeroDte (query, boolean): Filter strictly for 0DTE (same-day expiration) contracts. In GEX, maxDte=0 also denotes 0DTE contracts for backwards compatibility. zeroDte=true with maxDte > 0 returns 400 invalid_parameter.

Sample (cURL):
```bash
curl -s -H "Authorization: Bearer $WSO_API_KEY" \
  "https://api.wheelstrategyoptions.com/v1/gex/SPY?minDte=0&maxDte=60"
```


## Get 2D gamma exposure heatmap matrix
Method: GET
Path: /v1/gex/{symbol}/heatmap
Plan: Included in Basic
Description: Returns 2D matrix of dealer gamma exposure across strikes and expiration dates. Parameter `metric` ('net', 'call', or 'put') is accepted for compatibility and echoed back; cells always compute call, put, and net gamma. Default ±35% strike band around spot applies when neither strikeMin nor strikeMax is specified; when one bound is given, the search is one-sided. Capped at 5,000 cells (sets `truncated: true`).

Parameters:
- symbol (path, string, required): Underlying equity ticker symbol.
- metric (query, string): Gamma exposure metric: 'net', 'call', or 'put' (reserved / no-op parameter accepted for compatibility; echoes back in response with no effect on computation as cells always provide call, put, and net gamma).
- strikeMin (query, number): Lower strike price boundary in USD. strikeMin > strikeMax returns 400 invalid_range.
- strikeMax (query, number): Upper strike price boundary in USD.
- minDte (query, integer): Minimum DTE horizon filter (alias: dteMin, default 0).
- maxDte (query, integer): Maximum DTE horizon filter (alias: dteMax, 0-730, default 60).

Sample (cURL):
```bash
curl -s -H "Authorization: Bearer $WSO_API_KEY" \
  "https://api.wheelstrategyoptions.com/v1/gex/SPY/heatmap?metric=net"
```


## Get options flow trades
Method: GET
Path: /v1/flow
Plan: Included in Basic
Description: Returns recent options flow trade prints (large trades, filtered by premium). Limit defaults to 50 (max 500); minPremium defaults to 10000. Default sort order is premium descending; pass sort=time for timestamp descending. A market-wide query (without symbol) spanning more than 3 weekday trading sessions returns 400 out_of_range (FlowMaxMarketWideSessions = 3); split wide queries across multiple requests or narrow with symbols. Database query timeouts return 503 query_timeout with a Retry-After header.

Parameters:
- symbol (query, string): Underlying equity ticker symbol (alias: ticker).
- symbols (query, string): Comma-separated list of symbols (alias: tickers, max 20). Exceeding 20 returns 400 invalid_parameter.
- sentiment (query, string): Filter by derived trade sentiment ('bullish', 'bearish', or 'neutral'). Neutral includes prints with no sentiment tags.
- side (query, string): Filter by execution fill side relative to prevailing bid/ask ('ask', 'bid', or 'mid').
- type (query, string): Filter by option contract type ('call' or 'put', alias: optionType).
- executionType (query, string): Filter by trade routing structure ('sweep', 'block', or 'split', alias: execution).
- minPremium (query, number): Minimum trade premium in dollars (defaults to $10,000 for large prints; keeps per-symbol queries fast; explicit values below 10000 remain supported).
- limit (query, integer): Number of flow records to return (1 to 500, default 50; values > 500 are clamped to 500 and plan max_rows).
- sort (query, string): Sort order of returned trade prints ('premium' for premium descending, 'time' for executedAt descending; defaults to 'premium').
- from (query, string): Window start date in YYYY-MM-DD format (alias: fromDate). Older than 7 days returns 400 out_of_range. Clamped to plan history_days. When omitted, the window starts at `to` (a `to` alone is one session; a `to` past the newest session means the newest session) or, with neither, the newest session.
- to (query, string): Window end date in YYYY-MM-DD format (alias: toDate). When omitted: with symbol(s), the newest session; market-wide (no symbols), the `from` session, so a `from` alone is one session; with neither `from` nor `to`, the newest session.

Sample (cURL):
```bash
curl -s -H "Authorization: Bearer $WSO_API_KEY" \
  "https://api.wheelstrategyoptions.com/v1/flow?symbol=AAPL&limit=50"
```


## Get 1-minute net flow bars and summary
Method: GET
Path: /v1/flow/net
Plan: Included in Basic
Description: Returns cumulative 1-minute grain net flow bars and session volume/dollar totals for a single ticker. `minPremium` defaults to $10,000, which also filters trades in `summary.volume`. Date windows default to newest session; future `to` is cut back; `from` after newest session returns 400 out_of_range. Date parameters are subject to 7-day retention and plan history clamping.

Parameters:
- symbol (query, string, required): Underlying equity ticker symbol (alias: ticker). Missing symbol returns 400 missing_symbol.
- from (query, string): Window start date in YYYY-MM-DD format (alias: fromDate). Older than 7 days returns 400 out_of_range. Clamped to plan history_days. When omitted, the window starts at `to` (a `to` alone is one session; a `to` past the newest session means the newest session) or, with neither, the newest session.
- to (query, string): Window end date in YYYY-MM-DD format (alias: toDate). Defaults to the `from` session (a `from` alone is one session); with neither `from` nor `to`, the newest session.
- minPremium (query, number): Minimum trade premium in dollars (defaults to 10000).

Sample (cURL):
```bash
curl -s -H "Authorization: Bearer $WSO_API_KEY" \
  "https://api.wheelstrategyoptions.com/v1/flow/net?symbol=AAPL"
```


## Public announcement broadcast
Method: GET
Path: /public/announcement
Plan: All accounts
Description: Returns the active site announcement banner if currently configured and within its scheduled window. No authentication. Responses may be cached for up to 60 seconds.

Sample (cURL):
```bash
curl "https://api.wheelstrategyoptions.com/public/announcement" \
  -H "Authorization: Bearer wso_live_..."
```


## Public plans and pricing metadata
Method: GET
Path: /public/plans
Plan: All accounts
Description: Returns the active plans (limits and displayed prices), the enabled metered endpoints with their minimum plan, whether billing is open, and the trial length. No authentication. Responses may be cached for up to 5 minutes.

Sample (cURL):
```bash
curl "https://api.wheelstrategyoptions.com/public/plans"
```