---
name: skylit-api
description: Build with the Skylit market-data API and MCP server — dealer positioning (gamma/vanna heatmaps, full strike x expiration grids), options flow (scored trades, sweeps, tide, chain analytics, dark pool) and OHLCV bars. Use when writing code, scripts, bots, notebooks or agents that fetch Skylit data over REST, Server-Sent Events or MCP.
metadata:
  version: "1.0"
  source: "https://www.skylit.ai/docs"
---

# Skylit API and MCP — guide for coding agents

This file is the authoritative, self-contained reference for building against
Skylit. The endpoint sections are generated from the published OpenAPI specs,
so parameters and paths here match the live API. When in doubt, the specs are
linked at the end.

## Facts you must get right

| Topic | Rule |
| --- | --- |
| Hosts | One base URL, `https://api.skylit.ai`, serves Heatseeker (dealer positioning), Flowseeker (options flow, dark pool) and Tempest (volatility, `/v1/vol/*`). `https://flow-api.skylit.ai` is a permanent alias for Flowseeker (same keys, limits and credits); prefer `api.skylit.ai`. Atlas (OHLCV bars): `https://atlas-api.skylit.ai`. MCP server: `https://mcp.skylit.ai/mcp`. |
| Auth | Send `Authorization: Bearer <key>` on every request, REST and MCP. No other header is accepted (`X-API-Key` and query-string keys get `401`); the gateway also takes the bare key without `Bearer `, but use `Bearer`. Missing header: `401 {"error":{"code":"unauthorized","message":"Authorization field missing"}}`. Invalid, revoked or expired key: `403`. |
| Keys | One key works for every product. Read it from the `SKYLIT_API_KEY` environment variable; never hard-code it or ship it to a browser or mobile app. The number of active keys is set by the account's plan (`GET /v1/account` returns it under `limits`). Create keys at https://app.skylit.ai/developer. MCP clients can also sign in with Skylit (OAuth) instead of using a key. |
| Credits | Every successful data call debits credits from one shared balance. Responses carry `X-Credits-Remaining`. Out of credits: `402` with code `insufficient_credits`; monthly spend cap reached: `402 monthly_cap_reached`. Failed calls (any `4xx`/`5xx`) are refunded. `GET /v1/account` (free) returns the balance and the plan's limits. |
| Rate limit | A per-key requests-per-minute limit set by the account's plan, shared across all Skylit hosts (read it from `GET /v1/account` `limits.requestsPerMinute`, or `X-RateLimit-Limit`; do not hard-code it: today Pro is 120 per key, an invite 60). Every response carries `X-RateLimit-Limit`, `X-RateLimit-Remaining` and `X-RateLimit-Reset` (Unix seconds). On gateway `429 rate_limited` (no `Retry-After`), wait until `X-RateLimit-Reset`, then retry with jitter. API `429`s for concurrency or stream limits carry `Retry-After`: wait that many seconds. Full guidance: https://www.skylit.ai/docs/api-reference/rate-limits-and-retries |
| Symbols | Tickers are upper-case (`SPY`, `SPXW`, `QQQ`). Option contracts use the URL-safe OPRA form `{ticker}__{YYMMDD}{C\|P}{strike x 1000, 8 digits}`, e.g. `AAPL__260117C00250000`. Parameters may not contain quotes, backslashes or control characters (`400 invalid_parameter`). |
| Errors | Every REST error, including the gateway's 401/403/429, is `{"error":{"code":"...","message":"..."}}`. Branch on the HTTP status first, then on `error.code`; never on `message`. Heatseeker and gateway codes are lower-case (`symbol_not_found`); Flowseeker codes are upper-case (`SYMBOL_NOT_FOUND`) except the lower-case billing codes. Compare codes case-insensitively. Code list: https://www.skylit.ai/docs/api-reference/errors |
| Use | Keys are licensed to one person for their own trading and research. Do not republish, redistribute, resell, share in public bots or channels, or train models on the data. |

## Heatseeker rules (dealer positioning)

- `GET /v1/heatmap` returns the live board for several symbols per call (up to the plan's `limits.symbolsPerHeatmapCall`)
  (`symbols=SPY,QQQ`). Gamma and vanna are separate calls (`metric=gamma` or
  `metric=vanna`, default gamma).
- `maxStrikes` (default 92, max 400) keeps the N strikes nearest spot.
  `maxExpirations` (default 5, max 60) keeps the nearest N expirations, or pass
  `expirations=YYYY-MM-DD,YYYY-MM-DD` for exact ones.
- Each strike's `value` is the exposure **summed across the returned
  expirations**. Add `layout=matrix` to also get `matrix`, the grid behind it:
  `matrix[i][j]` is strike `strikes[i].strike` at expiration `expirations[j]`,
  and each row sums to that strike's `value`.
- Each symbol carries `asOf`, `spot`, `previousClose`, `priceChange`,
  `priceChangePercent`, `expirations`, `strikes[]` (`strike`, `value`,
  `nodeType`, `velocityPct`).
- `GET /v1/stream` is Server-Sent Events. Pass `symbols=SPY,QQQ` (up to the
  plan's symbols-per-stream limit) for the v2 format: named events `connected`
  (`symbols`, `creditsRemaining`, `creditsPerMinute`, `maxDurationSeconds`),
  `snapshot` (a full `SymbolHeatmap` per symbol on connect and on every board
  change), `velocity`, `symbol_unavailable`, `credits` (after each per-minute
  debit) and `closed` (`reason`). Events carry `id:`; reconnect with
  `Last-Event-ID` to resume. The legacy `symbol=SPY` form keeps the original
  single-symbol v1 format. Streams charge per symbol to open and per symbol per
  minute (symbols with no live board yet still count), and close after
  `maxDurationSeconds`: reconnect with backoff. Ignore
  event types you don't recognise and `:` comment lines (keep-alive pings).
- `GET /v1/historical` replays the board at an instant (`at=RFC3339`, within
  365 days). At most `limits.historicalInFlight` requests in flight per account (from `GET /v1/account`); more return `429
  too_many_concurrent_requests`. Run replays sequentially or two at a time.
- Poll `/v1/heatmap` no faster than every few seconds per symbol set; responses
  are cached for 5 seconds. For push updates use `/v1/stream`.
- `GET /v1/gex/levels` returns only the classified nodes (king, gatekeeper,
  pika, barney, significant) for several symbols per call, strongest first, with
  `distancePct` from spot and a `kingNode` shortcut. Prefer it over the full
  board when you only need levels.

## Account

`GET https://api.skylit.ai/v1/account` (free) returns your `creditsBalance`,
`balanceUsd` ($0.001 per credit), `unlimited`, `status` and `limits`. Call it
before large pulls and after a `402`. MCP tool: `account_usage`.

## MCP

The MCP server speaks streamable HTTP at `https://mcp.skylit.ai/mcp` and needs
the same bearer header. Every tool wraps one REST endpoint 1:1 with the same
credit cost; results include `meta.creditsRemaining`.

Claude Code:

```bash
claude mcp add --transport http skylit https://mcp.skylit.ai/mcp \
  --header "Authorization: Bearer $SKYLIT_API_KEY"
```

Cursor (`~/.cursor/mcp.json`) or any client that takes a URL plus headers:

```json
{
  "mcpServers": {
    "skylit": {
      "url": "https://mcp.skylit.ai/mcp",
      "headers": { "Authorization": "Bearer YOUR_SKYLIT_API_KEY" }
    }
  }
}
```

## Recipes

Live grid for several symbols (Python, `requests`):

```python
import os, requests

r = requests.get(
    "https://api.skylit.ai/v1/heatmap",
    params={"symbols": "SPY,QQQ", "metric": "gamma", "layout": "matrix",
            "maxStrikes": 100, "maxExpirations": 10},
    headers={"Authorization": f"Bearer {os.environ['SKYLIT_API_KEY']}"},
    timeout=15,
)
r.raise_for_status()
for s in r.json()["data"]["symbols"]:
    top = max(s["strikes"], key=lambda k: abs(k["value"]))
    print(s["symbol"], s["asOf"], s["spot"], "largest node", top["strike"], top["nodeType"])
```

Stream several symbols on one connection (Python, v2 format; resumes with
`Last-Event-ID`, stops on errors a retry can't fix; yields `(event, payload)`):

```python
import os, json, time, requests

STOP = {"insufficient_credits", "account_suspended", "monthly_cap_reached", "key_revoked"}

def stream(symbols):  # e.g. "SPY,QQQ"; bills 1 credit per symbol per minute
    url = "https://api.skylit.ai/v1/stream"
    headers = {"Authorization": f"Bearer {os.environ['SKYLIT_API_KEY']}"}
    last_id, backoff = None, 1
    while True:
        h = dict(headers, **({"Last-Event-ID": last_id} if last_id else {}))
        try:
            with requests.get(url, params={"symbols": symbols}, headers=h,
                              stream=True, timeout=(10, 60)) as r:
                if r.status_code in (400, 401, 402, 403, 404):
                    raise RuntimeError(f"{r.status_code}: {r.text[:200]}")  # fix, don't retry
                r.raise_for_status()
                backoff, event = 1, None
                for line in r.iter_lines(decode_unicode=True):
                    if line.startswith("id:"):
                        last_id = line[3:].strip()
                    elif line.startswith("event:"):
                        event = line[6:].strip()
                    elif line.startswith("data:"):
                        payload = json.loads(line[5:])
                        if event == "closed" and payload.get("reason") in STOP:
                            raise RuntimeError(f"stream closed: {payload['reason']}")
                        yield event, payload
                    # lines starting with ":" are keep-alive pings: ignore
        except requests.RequestException:
            pass  # dropped, timed out (no ping for 60 s) or 429/5xx: reconnect
        time.sleep(backoff)
        backoff = min(backoff * 2, 30)
```

Options flow — market tide and a ticker's sweeps (TypeScript, `fetch`):

```ts
const headers = { Authorization: `Bearer ${process.env.SKYLIT_API_KEY}` };
const tide = await fetch("https://api.skylit.ai/v1/market/tide", { headers }).then(r => r.json());
const sweeps = await fetch("https://api.skylit.ai/v1/sweeps/NVDA", { headers }).then(r => r.json());
```

One-minute bars (curl). Atlas returns TradingView-style columnar arrays:
`s` (`"ok"` or `"no_data"`), `t` (epoch seconds), `o`, `h`, `l`, `c`, `v`, plus
buy/sell/unclassified volume `bv`, `sv`, `uv`; index `i` across arrays is one bar.

```bash
curl "https://atlas-api.skylit.ai/v1/history?symbol=SPY&resolution=1&from=$(( $(date +%s) - 3600 ))&to=$(date +%s)" \
  -H "Authorization: Bearer $SKYLIT_API_KEY"
```

Handling errors (any language): retry `429` after `Retry-After` (or, when absent,
until `X-RateLimit-Reset`); retry `500`, `502`, `503` and `504` with exponential
backoff and full jitter (base 1 s, cap 30 s, at most 5 attempts; failed calls are
refunded); never retry `400`, `401`, `402`, `403` or `404` without changing the
request. Details and copy-paste code:
https://www.skylit.ai/docs/api-reference/rate-limits-and-retries

## Checklist before you ship

- [ ] Key read from `SKYLIT_API_KEY`, never logged or committed.
- [ ] `Authorization: Bearer` on every request.
- [ ] Batching symbols per heatmap call and per stream, within the limits from `GET /v1/account`.
- [ ] Backoff on `429` and `5xx`; no retries on 4xx.
- [ ] `X-Credits-Remaining` watched; `402` handled with a clear message.
- [ ] Output stays with the user (no redistribution).

# Endpoint reference (generated)

## Heatseeker — dealer positioning

Base URL `https://api.skylit.ai`. Spec: https://www.skylit.ai/docs/openapi.yaml

### `GET /v1/heatmap`

Live per-strike heatmap (one or more symbols)

| Parameter | In | Required | Type | Notes |
| --- | --- | --- | --- | --- |
| `symbols` | query | yes | string | One ticker, or a comma-separated list for a single cross-asset call (e.g. `SPY` or `SPY,SPX,QQQ`). Each is returned as an element of `data.symbols`. At most 10 distinct symbols (mo… |
| `metric` | query | no | one of `gamma`, `vanna` | Which Greek exposure to return per strike. |
| `maxStrikes` | query | no | default `92` | Maximum number of strikes around spot to return: an integer from 1 to 1000, or `all` for every strike the snapshot lists (SPXW lists about 730). Values above 1000 return `400 inval… |
| `maxExpirations` | query | no | default `5` | How many of the nearest expirations to net into each strike's `value`: an integer from 1 to 60, or `all`. Values above 60 return `400 invalid_parameter`. Ignored when `expirations`… |
| `includeEmpty` | query | no | boolean, default `false` | By default, an interior strike whose every returned cell is below 50 in absolute value (listed but effectively untraded) is left out, judged on the selected metric alone. So gamma … |
| `expirations` | query | no | string | Net each strike over exactly these expirations (`YYYY-MM-DD`, comma-separated) — one for a single-expiration heatmap (`2026-05-22`) or several for a custom set (`2026-05-22,2026-06… |
| `layout` | query | no | one of `net`, `matrix` | `net` (default) returns one net value per strike. `matrix` also returns `matrix`, the per-expiration grid those values are summed from. |

### `GET /v1/historical`

Replay — per-strike heatmap at a past instant (one or more symbols)

| Parameter | In | Required | Type | Notes |
| --- | --- | --- | --- | --- |
| `symbols` | query | yes | string | One ticker, or a comma-separated list for a single cross-asset call (e.g. `SPY` or `SPY,SPX,QQQ`). Each is returned as an element of `data.symbols`. At most 10 distinct symbols (mo… |
| `at` | query | yes | string (date-time) | RFC3339 instant to replay (e.g. `2026-03-05T10:01:00Z`). Not before 2023-03-28. |
| `metric` | query | no | one of `gamma`, `vanna` | Which Greek exposure to return per strike. |
| `maxStrikes` | query | no | default `92` | Maximum number of strikes around spot to return: an integer from 1 to 1000, or `all` for every strike the snapshot lists (SPXW lists about 730). Values above 1000 return `400 inval… |
| `maxExpirations` | query | no | default `5` | How many of the nearest expirations to net into each strike's `value`: an integer from 1 to 60, or `all`. Values above 60 return `400 invalid_parameter`. Ignored when `expirations`… |
| `includeEmpty` | query | no | boolean, default `false` | By default, an interior strike whose every returned cell is below 50 in absolute value (listed but effectively untraded) is left out, judged on the selected metric alone. So gamma … |
| `expirations` | query | no | string | Net each strike over exactly these expirations (`YYYY-MM-DD`, comma-separated) — one for a single-expiration heatmap (`2026-05-22`) or several for a custom set (`2026-05-22,2026-06… |
| `layout` | query | no | one of `net`, `matrix` | `net` (default) returns one net value per strike. `matrix` also returns `matrix`, the per-expiration grid those values are summed from. |

### `GET /v1/historical/range`

Replay — every snapshot in a window (up to 15 minutes, 5 symbols)

| Parameter | In | Required | Type | Notes |
| --- | --- | --- | --- | --- |
| `symbols` | query | yes | string | One ticker, or a comma-separated list for a single cross-asset call (e.g. `SPY` or `SPY,SPX,QQQ`). Each is returned as an element of `data.symbols`. At most 10 distinct symbols (mo… |
| `from` | query | yes | string (date-time) | RFC3339 start of the window (inclusive). Up to 365 days back. |
| `to` | query | yes | string (date-time) | RFC3339 end of the window (inclusive). At most 15 minutes after `from`, not in the future. |
| `metric` | query | no | one of `gamma`, `vanna` | Which Greek exposure to return per strike. |
| `maxStrikes` | query | no | default `92` | Maximum number of strikes around spot to return: an integer from 1 to 1000, or `all` for every strike the snapshot lists (SPXW lists about 730). Values above 1000 return `400 inval… |
| `maxExpirations` | query | no | default `5` | How many of the nearest expirations to net into each strike's `value`: an integer from 1 to 60, or `all`. Values above 60 return `400 invalid_parameter`. Ignored when `expirations`… |
| `expirations` | query | no | string | Net each strike over exactly these expirations (`YYYY-MM-DD`, comma-separated) — one for a single-expiration heatmap (`2026-05-22`) or several for a custom set (`2026-05-22,2026-06… |

### `GET /v1/stream`

Live SSE stream (up to 10 symbols per connection)

| Parameter | In | Required | Type | Notes |
| --- | --- | --- | --- | --- |
| `symbols` | query | no | string | Comma-separated tickers, up to 10 (e.g. `SPY,QQQ,IWM`). Selects format v2 by default. Unknown symbols → `404`. |
| `symbol` | query | no | string | Single ticker. Selects the legacy v1 format unless `format=v2`. Send `symbol` or `symbols`, not both. |
| `format` | query | no | one of `v1`, `v2` | Wire format. Defaults to `v2` with `symbols=` and `v1` with `symbol=`. `v1` is single-symbol only. |
| `lastEventId` | query | no | string | v2 resume cursor, for clients that cannot set the `Last-Event-ID` header. The header wins if both are sent. |
| `Last-Event-ID` | header | no | string | v2 resume cursor — the last `id:` received. |
| `metric` | query | no | one of `gamma`, `vanna` | Which Greek exposure to return per strike. |
| `maxStrikes` | query | no | default `92` | Maximum number of strikes around spot to return: an integer from 1 to 1000, or `all` for every strike the snapshot lists (SPXW lists about 730). Values above 1000 return `400 inval… |
| `maxExpirations` | query | no | default `5` | How many of the nearest expirations to net into each strike's `value`: an integer from 1 to 60, or `all`. Values above 60 return `400 invalid_parameter`. Ignored when `expirations`… |
| `includeEmpty` | query | no | boolean, default `false` | By default, an interior strike whose every returned cell is below 50 in absolute value (listed but effectively untraded) is left out, judged on the selected metric alone. So gamma … |
| `expirations` | query | no | string | v2 only — same meaning as on `/v1/heatmap`. Rejected with `400` on v1. |
| `layout` | query | no | one of `net`, `matrix` | v2 only — `matrix` adds the per-expiration grid to each snapshot, as on `/v1/heatmap`. |

### `GET /v1/gex/levels`

Key levels (classified nodes) for one or more symbols

| Parameter | In | Required | Type | Notes |
| --- | --- | --- | --- | --- |
| `symbols` | query | yes | string | One ticker, or a comma-separated list for a single cross-asset call (e.g. `SPY` or `SPY,SPX,QQQ`). Each is returned as an element of `data.symbols`. At most 10 distinct symbols (mo… |
| `metric` | query | no | one of `gamma`, `vanna` | Which Greek exposure to return per strike. |
| `maxStrikes` | query | no | default `92` | Maximum number of strikes around spot to return: an integer from 1 to 1000, or `all` for every strike the snapshot lists (SPXW lists about 730). Values above 1000 return `400 inval… |
| `maxExpirations` | query | no | default `5` | How many of the nearest expirations to net into each strike's `value`: an integer from 1 to 60, or `all`. Values above 60 return `400 invalid_parameter`. Ignored when `expirations`… |
| `includeEmpty` | query | no | boolean, default `false` | By default, an interior strike whose every returned cell is below 50 in absolute value (listed but effectively untraded) is left out, judged on the selected metric alone. So gamma … |
| `expirations` | query | no | string | Net each strike over exactly these expirations (`YYYY-MM-DD`, comma-separated) — one for a single-expiration heatmap (`2026-05-22`) or several for a custom set (`2026-05-22,2026-06… |

### `GET /v1/account`

Your balance and limits

### `GET /v1/stats/daily`

Daily statistics per symbol (ranking and spot range)

| Parameter | In | Required | Type | Notes |
| --- | --- | --- | --- | --- |
| `symbols` | query | yes | string | Comma-separated tickers (up to 50). |
| `from` | query | yes | string (date) | First UTC date (`YYYY-MM-DD`), not before 2023-03-28. |
| `to` | query | no | string (date) | Last UTC date (`YYYY-MM-DD`), inclusive. Default today; at most 31 days after `from`. |
| `metric` | query | no | one of `gamma`, `vanna` | Which Greek exposure to return per strike. |

### `GET /v1/symbols`

Symbol catalog

### `GET /v1/vol/iv`

Implied volatility (SVX) per symbol

| Parameter | In | Required | Type | Notes |
| --- | --- | --- | --- | --- |
| `symbols` | query | yes | string | Comma-separated Tempest symbols (up to 10). Tempest keys the S&P complex on the option root `SPXW` and Nasdaq-100 on `NDXP`; see `/v1/vol/symbols`. |

### `GET /v1/vol/term`

Implied-volatility term structure per symbol

| Parameter | In | Required | Type | Notes |
| --- | --- | --- | --- | --- |
| `symbols` | query | yes | string | Comma-separated Tempest symbols (up to 10). Tempest keys the S&P complex on the option root `SPXW` and Nasdaq-100 on `NDXP`; see `/v1/vol/symbols`. |

### `GET /v1/vol/cones`

Expected-move cones per symbol

| Parameter | In | Required | Type | Notes |
| --- | --- | --- | --- | --- |
| `symbols` | query | yes | string | Comma-separated Tempest symbols (up to 10). Tempest keys the S&P complex on the option root `SPXW` and Nasdaq-100 on `NDXP`; see `/v1/vol/symbols`. |

### `GET /v1/vol/sigma`

Move in units of the implied move (Sigma) per symbol

| Parameter | In | Required | Type | Notes |
| --- | --- | --- | --- | --- |
| `symbols` | query | yes | string | Comma-separated Tempest symbols (up to 10). Tempest keys the S&P complex on the option root `SPXW` and Nasdaq-100 on `NDXP`; see `/v1/vol/symbols`. |

### `GET /v1/vol/surface`

Volatility surface and skew per symbol

| Parameter | In | Required | Type | Notes |
| --- | --- | --- | --- | --- |
| `symbols` | query | yes | string | Comma-separated Tempest symbols (up to 10). Tempest keys the S&P complex on the option root `SPXW` and Nasdaq-100 on `NDXP`; see `/v1/vol/symbols`. |

### `GET /v1/vol/tilt`

Call-vs-put premium imbalance (Tilt) per symbol

| Parameter | In | Required | Type | Notes |
| --- | --- | --- | --- | --- |
| `symbols` | query | yes | string | Comma-separated Tempest symbols (up to 10). Tempest keys the S&P complex on the option root `SPXW` and Nasdaq-100 on `NDXP`; see `/v1/vol/symbols`. |

### `GET /v1/vol/events`

Event (earnings) implied move and VRP per symbol

| Parameter | In | Required | Type | Notes |
| --- | --- | --- | --- | --- |
| `symbols` | query | yes | string | Comma-separated Tempest symbols (up to 10). Tempest keys the S&P complex on the option root `SPXW` and Nasdaq-100 on `NDXP`; see `/v1/vol/symbols`. |

### `GET /v1/vol/snapshot`

Every Tempest module per symbol

| Parameter | In | Required | Type | Notes |
| --- | --- | --- | --- | --- |
| `symbols` | query | yes | string | Comma-separated Tempest symbols (up to 10). Tempest keys the S&P complex on the option root `SPXW` and Nasdaq-100 on `NDXP`; see `/v1/vol/symbols`. |

### `GET /v1/vol/market`

The S&P volatility complex

### `GET /v1/vol/screener`

Screen the whole Tempest universe (Radar)

| Parameter | In | Required | Type | Notes |
| --- | --- | --- | --- | --- |
| `sort` | query | no | string, default `svx30` | Field to sort by (default `svx30`): svx30, svx1d, svx30_pct_1y, svx1d_pct_1y, svx9_pct_1y, svx3m_pct_1y, iv_rank, iv_pct, ratio_vix, term_slope, rr25_30, skew_pct_1y, tilt_21, tilt… |
| `order` | query | no | one of `asc`, `desc` |  |
| `limit` | query | no | integer, default `50`, min 1, max 500 |  |
| `offset` | query | no | integer, default `0`, min 0 |  |
| `min_iv_rank` | query | no | number | Example bound; every sortable field accepts `min_` and `max_`. |
| `curve` | query | no | string | Curve state, e.g. `contango` or `backwardation`. |

### `GET /v1/vol/history`

Daily Tempest history per symbol

| Parameter | In | Required | Type | Notes |
| --- | --- | --- | --- | --- |
| `symbols` | query | yes | string | Comma-separated Tempest symbols (up to 10). Tempest keys the S&P complex on the option root `SPXW` and Nasdaq-100 on `NDXP`; see `/v1/vol/symbols`. |
| `from` | query | no | string (date) | First session (`YYYY-MM-DD`, ET). Default one month before `to`. |
| `to` | query | no | string (date) | Last session, inclusive. Default today (ET). At most 800 calendar days after `from`. |
| `fields` | query | no | string | Comma-separated columns to return (default all). |

### `GET /v1/vol/derived`

Realized vs implied and the usual range (one year)

| Parameter | In | Required | Type | Notes |
| --- | --- | --- | --- | --- |
| `symbols` | query | yes | string | Comma-separated Tempest symbols (up to 10). Tempest keys the S&P complex on the option root `SPXW` and Nasdaq-100 on `NDXP`; see `/v1/vol/symbols`. |

### `GET /v1/vol/status`

Tempest freshness, coverage and market state (free)

### `GET /v1/vol/symbols`

Symbols covered by Tempest (free)

### `GET /v1/vol/stream`

Live Tempest updates (Server-Sent Events)

| Parameter | In | Required | Type | Notes |
| --- | --- | --- | --- | --- |
| `symbols` | query | yes | string | Comma-separated Tempest symbols (up to 10). Tempest keys the S&P complex on the option root `SPXW` and Nasdaq-100 on `NDXP`; see `/v1/vol/symbols`. |
| `modules` | query | no | string | Comma-separated subset of iv, term, cones, sigma, surface, tilt, events (default all). |
| `market` | query | no | boolean, default `false` | Also push the market volatility complex. |
| `lastEventId` | query | no | integer | Resume point when the client cannot send `Last-Event-ID`. |

### `GET /v1/openapi.json`

This OpenAPI specification, as JSON.

## Flowseeker — options flow and dark pool

Base URL `https://api.skylit.ai`. Spec: https://www.skylit.ai/docs/flowseeker-openapi.yaml

### `GET /v1/flow/{ticker}`

Raw flow feed for a ticker (Flow Score + FlowBonus per trade)

| Parameter | In | Required | Type | Notes |
| --- | --- | --- | --- | --- |
| `ticker` | path | yes | string | Underlying ticker symbol (uppercase, e.g. `SPY`, `AAPL`). |
| `timeframe` | query | no | one of `5m`, `15m`, `1h`, `4h`, `1d` | Trailing window label for the request. Supported values: `5m`, `15m`, `1h`, `4h`, `1d`. |
| `limit` | query | no | integer, default `100`, min 1, max 500 | Max trades returned. Server caps this at 500. |
| `min_premium` | query | no | number (double) | Minimum total premium per trade (USD). |
| `option_type` | query | no | one of `call`, `put`, `all` | Filter to calls or puts. `all` returns both. |
| `trade_type` | query | no | one of `sweep`, `multi_leg`, `all` | Filter by trade type. Comma-separated for multiple; every token must be one of the listed values. |
| `moneyness` | query | no | one of `deep_itm`, `itm`, `atm`, `otm`, `deep_otm`, `all` | Moneyness category filter. Comma-separated for multiple (e.g. `otm,deep_otm`). Every token must be one of the listed values; an unknown token returns `400`. |
| `start_time` | query | no | string | Optional lower bound for the trade window. Accepts RFC 3339 (`2026-05-27T13:30:00Z`) or Unix seconds. Omit to use the timeframe. |
| `end_time` | query | no | string | Optional upper bound (RFC 3339 or Unix seconds). |
| `max_premium` | query | no | number (double) | Maximum total premium per trade (USD). |
| `min_contracts` | query | no | integer, min 0 | Minimum contract size per trade. |
| `max_contracts` | query | no | integer, min 0 | Maximum contract size per trade. |
| `single_leg_only` | query | no | boolean, default `false` | If `true`, exclude trades flagged as part of a multi-leg structure. |
| `min_dte` | query | no | integer | Minimum days to expiration. |
| `max_dte` | query | no | integer | Maximum days to expiration. |
| `min_strike` | query | no | number (double) | Minimum strike price (inclusive). |
| `max_strike` | query | no | number (double) | Maximum strike price (inclusive). |
| `expiration` | query | no | string (date) | Filter to a single expiration date (YYYY-MM-DD). |
| `conviction_weights` | query | no | string | Optional JSON object overriding the Flow Score conviction weights. Weights must be non-negative and sum to within 0.95–1.05, else 400. |
| `min_flow_score` | query | no | integer, min -100, max 100 | Filter to trades with `flowScore` ≥ this value (-100..100). |
| `min_flow_bonus` | query | no | integer, min 0 | Filter to trades with `flowBonus` ≥ this value. |
| `min_rvol` | query | no | number (double), min 0 | Filter to trades with relative volume ≥ this multiple. |
| `include_clusters` | query | no | boolean, default `true` | If `true`, attach `cluster*` fields when a trade is part of a multi-leg cluster (sweep, condor, etc.). |
| `date` | query | no | string (date) | Trading date (YYYY-MM-DD). Defaults to current trading date. |

### `GET /v1/flow/{ticker}/aggregate`

Aggregate flow over an arbitrary [start, end] window

| Parameter | In | Required | Type | Notes |
| --- | --- | --- | --- | --- |
| `ticker` | path | yes | string | Underlying ticker symbol (uppercase, e.g. `SPY`, `AAPL`). |
| `start_time` | query | yes | string | Lower bound of the window. Accepts RFC 3339 (`2026-05-27T13:30:00Z`) or Unix seconds. |
| `end_time` | query | yes | string | Upper bound of the window (RFC 3339 or Unix seconds). |
| `option_type` | query | no | one of `call`, `put`, `all` |  |
| `min_premium` | query | no | number (double) |  |
| `exclude_multi_leg` | query | no | boolean, default `false` | Exclude trades flagged as part of a multi-leg structure. |
| `min_dte` | query | no | integer, min 0 |  |
| `max_dte` | query | no | integer, min 0 |  |
| `date` | query | no | string (date) |  |

### `GET /v1/flow/{ticker}/tide`

Per-ticker net-premium time series ("flow tide")

| Parameter | In | Required | Type | Notes |
| --- | --- | --- | --- | --- |
| `ticker` | path | yes | string | Underlying ticker symbol (uppercase, e.g. `SPY`, `AAPL`). |
| `start_time` | query | yes | string | Lower bound of the window. Accepts RFC 3339 (`2026-05-27T13:30:00Z`) or Unix seconds. |
| `end_time` | query | yes | string | Upper bound of the window (RFC 3339 or Unix seconds). |
| `bucket` | query | no | one of `1min`, `5min`, `15min`, `30min`, `1h` | Bucket size for the time series. Pre-aggregated tables back the sub-hourly resolutions. Coarser buckets (`1d`, `1w`) are rejected on intraday endpoints. |
| `option_type` | query | no | one of `call`, `put`, `all` |  |
| `min_premium` | query | no | number (double) |  |
| `exclude_multi_leg` | query | no | boolean, default `false` |  |
| `min_dte` | query | no | integer, min 0 |  |
| `max_dte` | query | no | integer, min 0 |  |
| `date` | query | no | string (date) |  |

### `GET /v1/flow/{ticker}/baseline`

Trailing per-time-of-day flow baseline (avg + stddev)

| Parameter | In | Required | Type | Notes |
| --- | --- | --- | --- | --- |
| `ticker` | path | yes | string | Underlying ticker symbol (uppercase, e.g. `SPY`, `AAPL`). |
| `bucket` | query | no | one of `1min`, `5min`, `15min`, `30min`, `1h` | Bucket size for the time series. Pre-aggregated tables back the sub-hourly resolutions. Coarser buckets (`1d`, `1w`) are rejected on intraday endpoints. |
| `lookback_days` | query | no | integer, default `20`, min 1, max 30 | Trailing window size in trading days. |
| `start_time_of_day` | query | no | string, default `09:30` | Lower bound of intraday window (HH:MM ET). |
| `end_time_of_day` | query | no | string, default `16:00` | Upper bound of intraday window (HH:MM ET). |
| `min_dte` | query | no | integer, min 0 |  |
| `max_dte` | query | no | integer, min 0 |  |

### `GET /v1/flow/{ticker}/momentum`

Live momentum signal vs baseline (5m / 30m / 1h windows)

| Parameter | In | Required | Type | Notes |
| --- | --- | --- | --- | --- |
| `ticker` | path | yes | string | Underlying ticker symbol (uppercase, e.g. `SPY`, `AAPL`). |
| `as_of` | query | no | string | Replay anchor. Accepts RFC 3339 or Unix seconds. Defaults to "now". |
| `lookback_days` | query | no | integer, default `20`, min 1, max 30 | Trailing window size in trading days. |
| `min_dte` | query | no | integer, min 0 |  |
| `max_dte` | query | no | integer, min 0 |  |

### `GET /v1/flow/{ticker}/strikes`

Strike-level flow concentration

| Parameter | In | Required | Type | Notes |
| --- | --- | --- | --- | --- |
| `ticker` | path | yes | string | Underlying ticker symbol (uppercase, e.g. `SPY`, `AAPL`). |
| `start_time` | query | yes | string | Lower bound of the window. Accepts RFC 3339 (`2026-05-27T13:30:00Z`) or Unix seconds. |
| `end_time` | query | yes | string | Upper bound of the window (RFC 3339 or Unix seconds). |
| `top_n` | query | no | integer, default `20`, min 1, max 100 | Number of strikes to return. |
| `right` | query | no | one of `call`, `put` | Restrict to calls or puts only. |
| `min_premium` | query | no | number (double) |  |
| `order_by` | query | no | one of `net_premium`, `total_premium`, `volume` |  |
| `min_dte` | query | no | integer, min 0 |  |
| `max_dte` | query | no | integer, min 0 |  |

### `GET /v1/flow/{ticker}/historical-compare`

Today's flow vs trailing average (with similar-days lookback)

| Parameter | In | Required | Type | Notes |
| --- | --- | --- | --- | --- |
| `ticker` | path | yes | string | Underlying ticker symbol (uppercase, e.g. `SPY`, `AAPL`). |
| `date` | query | no | string (date) | Date to evaluate (YYYY-MM-DD). Defaults to today. |

### `GET /v1/flow/sector/{sector}`

Sector- or industry-level flow aggregation

| Parameter | In | Required | Type | Notes |
| --- | --- | --- | --- | --- |
| `sector` | path | yes | string | Sector ETF symbol (`XLK`, `XLF`, `XLE`, `XLV`, `XLY`, `XLP`, `XLU`, `XLI`, `XLB`, `XLRE`, `XLC`) or full sector name (`Technology`, `Financials`, `Healthcare`, etc.). |
| `date` | query | no | string (date) |  |
| `top_n` | query | no | integer, default `10`, min 1, max 50 |  |

### `GET /v1/flow/market-breadth`

Market-wide breadth, advance/decline, and sector rotation

| Parameter | In | Required | Type | Notes |
| --- | --- | --- | --- | --- |
| `date` | query | no | string (date) | Trading date (YYYY-MM-DD). Defaults to today. |
| `fir_threshold` | query | no | number (double), default `10.0` | Absolute FIR threshold (in %) used to classify a ticker as advancing or declining. Tickers with `\|fir\| < threshold` count as unchanged. |

### `GET /v1/sweeps/{ticker}`

Aggregated multi-exchange sweep activity

| Parameter | In | Required | Type | Notes |
| --- | --- | --- | --- | --- |
| `ticker` | path | yes | string | Underlying ticker symbol (uppercase, e.g. `SPY`, `AAPL`). |
| `timeframe` | query | no | one of `5m`, `15m`, `1h`, `4h`, `1d` | Trailing window. Currently only restricts the trading day; the handler reads the full day's sweep partition. `5m`/`15m`/`1h`/ `4h` reserved for future intraday filtering. |
| `min_premium` | query | no | number (double) |  |
| `option_type` | query | no | one of `call`, `put`, `all` |  |
| `moneyness` | query | no | one of `deep_itm`, `itm`, `atm`, `otm`, `deep_otm`, `all` |  |
| `min_dte` | query | no | integer, min 0 |  |
| `max_dte` | query | no | integer, min 0 |  |
| `min_strike` | query | no | number (double) |  |
| `max_strike` | query | no | number (double) |  |
| `expiration` | query | no | string (date) | Restrict to a single expiration date (`YYYY-MM-DD`). |
| `limit` | query | no | integer, default `100`, min 1, max 500 | Max sweep rows returned (server caps at 500). |
| `date` | query | no | string (date) |  |

### `GET /v1/aggregate/{ticker}`

Aggregate sentiment scoring across timeframes (VWF / SDF / FIR / Composite)

| Parameter | In | Required | Type | Notes |
| --- | --- | --- | --- | --- |
| `ticker` | path | yes | string | Underlying ticker symbol (uppercase, e.g. `SPY`, `AAPL`). |
| `timeframes` | query | no | string, default `1d` | Comma-separated timeframes, or `all`. Supported atoms: `1h, 4h, 1d, 7d, 30d, 90d`. `all` expands to all six. Unknown atoms are treated as a single trading day. At most 8 entries. P… |
| `include_breakdown` | query | no | boolean, default `true` | Attach the per-timeframe VWF/SDF/FIR component split. |
| `include_moneyness` | query | no | boolean, default `false` | Attach a `byMoneyness` array (deep_itm → deep_otm). |
| `moneyness_filter` | query | no | one of `deep_itm`, `itm`, `atm`, `otm`, `deep_otm`, `all` |  |
| `expiration_filter` | query | no | one of `0dte`, `weekly`, `monthly`, `leaps`, `all` | Restrict to one expiration bucket. |
| `time_decay` | query | no | boolean, default `false` | Apply exponential time decay to VWF / SDF / FIR components. |
| `time_decay_half_life` | query | no | integer, default `30`, min 1 | Half-life in minutes for the decay (only applied when `timeDecay=true`). |
| `date` | query | no | string (date) |  |

### `GET /v1/vol-oi/{ticker}`

Volume-vs-Open-Interest accumulation analysis

| Parameter | In | Required | Type | Notes |
| --- | --- | --- | --- | --- |
| `ticker` | path | yes | string | Underlying ticker symbol (uppercase, e.g. `SPY`, `AAPL`). |
| `timeframe` | query | no | one of `daily`, `weekly` |  |
| `option_type` | query | no | one of `call`, `put`, `all` |  |
| `moneyness` | query | no | one of `otm_10plus`, `otm_5_10`, `otm_3_5`, `atm_itm`, `all` |  |
| `min_oi` | query | no | integer, min 0 |  |
| `date` | query | no | string (date) |  |

### `GET /v1/moneyness/{ticker}`

Moneyness breakdown with pattern detection

| Parameter | In | Required | Type | Notes |
| --- | --- | --- | --- | --- |
| `ticker` | path | yes | string | Underlying ticker symbol (uppercase, e.g. `SPY`, `AAPL`). |
| `timeframe` | query | no | one of `intraday`, `daily`, `7d`, `30d` |  |
| `date` | query | no | string (date) |  |
| `min_premium` | query | no | number (double) |  |

### `GET /v1/score/{trade_id}`

Detailed scoring for a single trade

| Parameter | In | Required | Type | Notes |
| --- | --- | --- | --- | --- |
| `trade_id` | path | yes | string | Trade id (`flow_{hex}_{idx}`, bare hex timestamp, or raw nanos). |

### `GET /v1/chain-ratio/{ticker}`

Chain-level bid/ask/mid distribution

| Parameter | In | Required | Type | Notes |
| --- | --- | --- | --- | --- |
| `ticker` | path | yes | string | Underlying ticker symbol (uppercase, e.g. `SPY`, `AAPL`). |
| `date` | query | no | string (date) |  |
| `timeframe` | query | no | one of `5m`, `15m`, `1h`, `4h`, `1d` |  |
| `option_type` | query | no | one of `call`, `put`, `all` |  |
| `min_premium` | query | no | integer, min 0 |  |
| `min_dte` | query | no | integer, min 0 |  |
| `max_dte` | query | no | integer, min 0 |  |

### `GET /v1/contract-ratio/{symbol}`

Per-contract bid/ask/mid distribution

| Parameter | In | Required | Type | Notes |
| --- | --- | --- | --- | --- |
| `symbol` | path | yes | string | OPRA option symbol in URL-safe form: `{ticker}__{YYMMDD}{C\|P}{strike×1000, 8 digits}` — the ticker and the 15-character contract block are joined by a **double underscore** (`__`).… |
| `date` | query | no | string (date) |  |
| `timeframe` | query | no | one of `5m`, `15m`, `1h`, `4h`, `1d` |  |
| `min_premium` | query | no | integer, min 0 |  |

### `GET /v1/chain-bull-bear/{ticker}`

Chain-level call/put-aware bull/bear pressure

| Parameter | In | Required | Type | Notes |
| --- | --- | --- | --- | --- |
| `ticker` | path | yes | string | Underlying ticker symbol (uppercase, e.g. `SPY`, `AAPL`). |
| `date` | query | no | string (date) |  |
| `timeframe` | query | no | one of `5m`, `15m`, `1h`, `4h`, `1d` |  |
| `option_type` | query | no | one of `call`, `put`, `all` |  |
| `min_premium` | query | no | integer, min 0 |  |
| `min_dte` | query | no | integer, min 0 |  |
| `max_dte` | query | no | integer, min 0 |  |

### `GET /v1/contract-bull-bear/{symbol}`

Per-contract call/put-aware bull/bear pressure

| Parameter | In | Required | Type | Notes |
| --- | --- | --- | --- | --- |
| `symbol` | path | yes | string | OPRA option symbol in URL-safe form: `{ticker}__{YYMMDD}{C\|P}{strike×1000, 8 digits}` — the ticker and the 15-character contract block are joined by a **double underscore** (`__`).… |
| `date` | query | no | string (date) |  |
| `timeframe` | query | no | one of `5m`, `15m`, `1h`, `4h`, `1d` |  |
| `min_premium` | query | no | integer, min 0 |  |

### `GET /v1/market/overview`

Market-wide flow overview for the current trading day

| Parameter | In | Required | Type | Notes |
| --- | --- | --- | --- | --- |
| `tickers` | query | no | string | Comma-separated list of tickers (e.g. `AAPL,NVDA,SPY`, max 50). When omitted, returns true market-wide stats over every ticker. |

### `GET /v1/market/tide`

Bucketed market-wide net call premium / net put premium time series

| Parameter | In | Required | Type | Notes |
| --- | --- | --- | --- | --- |
| `interval` | query | no | one of `1D`, `2D`, `3D`, `5D`, `7D`, `14D`, `30D`, `45D`, `60D`, `90D`, `120D`, `180D`, `360D` | Trailing window length. Defaults to a single trading day (`1D`); multi-day intervals roll up history at the chosen bucket size. Intraday buckets (`1min`–`30min`) allow at most `30D… |
| `bucket` | query | no | one of `1min`, `5min`, `15min`, `30min`, `1d`, `1w` | Bucket size for the time series. |
| `date` | query | no | string (date) | Trading date anchor (`YYYY-MM-DD`). Defaults to today. |
| `exclude_multi_leg` | query | no | boolean, default `false` | Exclude multi-leg / spread trades from the directional totals. |
| `exclude_deep_itm` | query | no | boolean, default `false` | Exclude deep in-the-money trades (`moneyness_percent < -20`) from the directional totals. This reads raw trades rather than the pre-aggregated series: `interval` is capped at `5D` … |

### `GET /v1/underlying`

List underlyings active on a date

| Parameter | In | Required | Type | Notes |
| --- | --- | --- | --- | --- |
| `limit` | query | no | integer, default `100`, min 1, max 500 | Maximum rows to return. Server caps at 500. |
| `date` | query | no | string (date) | Trading date the request targets, in `YYYY-MM-DD`. Defaults to the current trading date (the most recent session that has settled enough data to be queryable). Past dates fall thro… |
| `min_premium` | query | no | number (double), min 0 | Minimum total premium (USD) for the day. |
| `min_volume` | query | no | integer, min 0 | Minimum total option volume for the day. |

### `GET /v1/underlying/search`

Prefix-search active tickers

| Parameter | In | Required | Type | Notes |
| --- | --- | --- | --- | --- |
| `q` | query | yes | string | Search prefix (1–10 characters, uppercased server-side). |
| `limit` | query | no | integer, default `20`, min 1, max 50 |  |
| `date` | query | no | string (date) | Trading date the request targets, in `YYYY-MM-DD`. Defaults to the current trading date (the most recent session that has settled enough data to be queryable). Past dates fall thro… |

### `GET /v1/underlying/top/daily`

Top underlyings by daily flow

| Parameter | In | Required | Type | Notes |
| --- | --- | --- | --- | --- |
| `limit` | query | no | integer, default `100`, min 1, max 500 | Maximum rows to return. Server caps at 500. |
| `date` | query | no | string (date) | Trading date the request targets, in `YYYY-MM-DD`. Defaults to the current trading date (the most recent session that has settled enough data to be queryable). Past dates fall thro… |
| `min_premium` | query | no | number (double), min 0 |  |
| `min_volume` | query | no | integer, min 0 |  |
| `order_by` | query | no | one of `premium`, `volume`, `net_premium`, `call_put_ratio` |  |
| `order` | query | no | one of `asc`, `desc` |  |

### `GET /v1/underlying/top/weekly`

Top underlyings by trailing-5-day flow

| Parameter | In | Required | Type | Notes |
| --- | --- | --- | --- | --- |
| `limit` | query | no | integer, default `100`, min 1, max 500 | Maximum rows to return. Server caps at 500. |
| `date` | query | no | string (date) | Trading date the request targets, in `YYYY-MM-DD`. Defaults to the current trading date (the most recent session that has settled enough data to be queryable). Past dates fall thro… |
| `min_premium` | query | no | number (double), min 0 |  |
| `min_volume` | query | no | integer, min 0 |  |
| `order_by` | query | no | one of `premium`, `volume`, `net_premium`, `call_put_ratio` |  |
| `order` | query | no | one of `asc`, `desc` |  |

### `GET /v1/underlying/bulk/stats`

Bulk underlying stats for a list of tickers

| Parameter | In | Required | Type | Notes |
| --- | --- | --- | --- | --- |
| `tickers` | query | yes | string | Comma-separated list of tickers (max 50). |
| `date` | query | no | string (date) | Trading date the request targets, in `YYYY-MM-DD`. Defaults to the current trading date (the most recent session that has settled enough data to be queryable). Past dates fall thro… |

### `GET /v1/underlying/{ticker}/stats`

Daily stats for a single underlying

| Parameter | In | Required | Type | Notes |
| --- | --- | --- | --- | --- |
| `ticker` | path | yes | string | Underlying ticker symbol (uppercase, e.g. `SPY`, `AAPL`). |
| `date` | query | no | string (date) | Trading date the request targets, in `YYYY-MM-DD`. Defaults to the current trading date (the most recent session that has settled enough data to be queryable). Past dates fall thro… |

### `GET /v1/underlying/{ticker}/chart`

Intraday chart bars for a ticker

| Parameter | In | Required | Type | Notes |
| --- | --- | --- | --- | --- |
| `ticker` | path | yes | string | Underlying ticker symbol (uppercase, e.g. `SPY`, `AAPL`). |
| `interval` | query | yes | string | Trailing window covered by the bars (e.g. `1D`, `7D`, `30D`). At most `30D` with an intraday bucket, `365D` with `1d`/`1w`. Priced by range: 3 credits per started 30 days. |
| `bucket` | query | yes | one of `1min`, `5min`, `10min`, `15min`, `30min`, `1d`, `1w` | Bucket size. |

### `GET /v1/underlying/{ticker}/trades`

Raw enriched trades for a ticker

| Parameter | In | Required | Type | Notes |
| --- | --- | --- | --- | --- |
| `ticker` | path | yes | string | Underlying ticker symbol (uppercase, e.g. `SPY`, `AAPL`). |
| `start` | query | no | string | Lower time bound — ISO 8601 (e.g. `2026-01-12T09:30:00Z`) or Unix seconds. Defaults to start-of-trading-day. |
| `end` | query | no | string | Upper time bound — ISO 8601 or Unix seconds. Defaults to now. |
| `limit` | query | no | integer, default `50`, min 1, max 500 |  |
| `only_sweeps` | query | no | boolean, default `false` |  |
| `only_multi_leg` | query | no | boolean, default `false` |  |
| `exclude_multi_leg` | query | no | boolean, default `false` |  |
| `moneyness` | query | no | one of `ITM`, `ATM`, `OTM` |  |
| `min_moneyness_pct` | query | no | number (double) |  |
| `max_moneyness_pct` | query | no | number (double) |  |
| `min_premium` | query | no | number (double), min 0 |  |
| `min_dte` | query | no | integer |  |
| `max_dte` | query | no | integer |  |
| `min_strike` | query | no | number (double) |  |
| `max_strike` | query | no | number (double) |  |
| `expiration` | query | no | string (date) |  |

### `GET /v1/underlying/{ticker}/by-strike`

Premium / volume by strike

| Parameter | In | Required | Type | Notes |
| --- | --- | --- | --- | --- |
| `ticker` | path | yes | string | Underlying ticker symbol (uppercase, e.g. `SPY`, `AAPL`). |
| `interval` | query | no | one of `1D`, `1W`, `7D` |  |
| `dte_filter` | query | no | one of `all`, `0-7`, `8-30`, `31-90`, `90+` | DTE bucket — `all`, `0-7`, `8-30`, `31-90`, or `90+`. |
| `date` | query | no | string (date) | Trading date the request targets, in `YYYY-MM-DD`. Defaults to the current trading date (the most recent session that has settled enough data to be queryable). Past dates fall thro… |

### `GET /v1/underlying/{ticker}/by-strike/{strike}/expirations`

Premium / volume by expiration for a strike

| Parameter | In | Required | Type | Notes |
| --- | --- | --- | --- | --- |
| `ticker` | path | yes | string | Underlying ticker symbol (uppercase, e.g. `SPY`, `AAPL`). |
| `strike` | path | yes | string | Strike price (decimal allowed; e.g. `580` or `580.5`). |
| `interval` | query | no | one of `1D`, `1W`, `7D` |  |
| `dte_filter` | query | no | one of `all`, `0-7`, `8-30`, `31-90`, `90+` |  |
| `date` | query | no | string (date) | Trading date the request targets, in `YYYY-MM-DD`. Defaults to the current trading date (the most recent session that has settled enough data to be queryable). Past dates fall thro… |

### `GET /v1/underlying/{ticker}/expirations`

List traded expirations for a ticker

| Parameter | In | Required | Type | Notes |
| --- | --- | --- | --- | --- |
| `ticker` | path | yes | string | Underlying ticker symbol (uppercase, e.g. `SPY`, `AAPL`). |
| `date` | query | no | string (date) | Trading date the request targets, in `YYYY-MM-DD`. Defaults to the current trading date (the most recent session that has settled enough data to be queryable). Past dates fall thro… |

### `GET /v1/underlying/{ticker}/chain`

Option chain snapshot

| Parameter | In | Required | Type | Notes |
| --- | --- | --- | --- | --- |
| `ticker` | path | yes | string | Underlying ticker symbol (uppercase, e.g. `SPY`, `AAPL`). |
| `expiration` | query | yes | string (date) | Expiration date (`YYYY-MM-DD`). |
| `min_volume` | query | no | integer, min 0 | Suppress strikes whose total (call+put) volume is below this floor. |
| `date` | query | no | string (date) | Trading date the request targets, in `YYYY-MM-DD`. Defaults to the current trading date (the most recent session that has settled enough data to be queryable). Past dates fall thro… |

### `GET /v1/underlying/{ticker}/history`

Daily history for a ticker

| Parameter | In | Required | Type | Notes |
| --- | --- | --- | --- | --- |
| `ticker` | path | yes | string | Underlying ticker symbol (uppercase, e.g. `SPY`, `AAPL`). |
| `start_date` | query | yes | string (date) |  |
| `end_date` | query | yes | string (date) |  |

### `GET /v1/underlying/{ticker}/rvol`

Relative-volume bars for a ticker

| Parameter | In | Required | Type | Notes |
| --- | --- | --- | --- | --- |
| `ticker` | path | yes | string | Underlying ticker symbol (uppercase, e.g. `SPY`, `AAPL`). |
| `interval` | query | no | string, default `1D` | Trailing window — `{N}D` where N is 1–365 (e.g. `1D`, `7D`, `30D`). |
| `bucket` | query | no | one of `1min`, `5min`, `10min`, `15min`, `30min`, `1d`, `1w` |  |
| `avg_period` | query | no | string, default `14d` | Baseline lookback as `{N}d` (e.g. `14d`, `30d`). Max 365 days. |
| `date` | query | no | string (date) | Trading date the request targets, in `YYYY-MM-DD`. Defaults to the current trading date (the most recent session that has settled enough data to be queryable). Past dates fall thro… |
| `order_by` | query | no | one of `rvol`, `volume`, `premium`, `time` |  |
| `order` | query | no | one of `asc`, `desc` | Sort direction. Defaults to `asc` when `order_by=time`, otherwise `desc`. |
| `limit` | query | no | integer, min 1 |  |
| `format` | query | no | one of `full`, `summary` |  |

### `GET /v1/contract/top/daily`

Top contracts by daily flow

| Parameter | In | Required | Type | Notes |
| --- | --- | --- | --- | --- |
| `limit` | query | no | integer, default `100`, min 1, max 500 | Maximum rows to return. Server caps at 500. |
| `date` | query | no | string (date) | Trading date the request targets, in `YYYY-MM-DD`. Defaults to the current trading date (the most recent session that has settled enough data to be queryable). Past dates fall thro… |
| `ticker` | query | no | string |  |
| `min_premium` | query | no | number (double) |  |
| `max_premium` | query | no | number (double) |  |
| `min_volume` | query | no | integer, min 0 |  |
| `max_volume` | query | no | integer, min 0 |  |
| `min_oi` | query | no | integer, min 0 |  |
| `max_oi` | query | no | integer, min 0 |  |
| `right` | query | no | one of `C`, `P` |  |
| `min_dte` | query | no | integer |  |
| `max_dte` | query | no | integer |  |
| `min_strike` | query | no | number (double) |  |
| `max_strike` | query | no | number (double) |  |
| `expiration` | query | no | string (date) |  |
| `min_iv` | query | no | number (double) |  |
| `max_iv` | query | no | number (double) |  |
| `order_by` | query | no | one of `premium`, `volume`, `oi`, `iv` |  |
| `order` | query | no | one of `asc`, `desc` |  |
| `only_sweeps` | query | no | boolean, default `false` |  |
| `only_multi_leg` | query | no | boolean, default `false` |  |
| `exclude_multi_leg` | query | no | boolean, default `false` |  |

### `GET /v1/contract/top/weekly`

Top contracts by trailing-5-day flow

| Parameter | In | Required | Type | Notes |
| --- | --- | --- | --- | --- |
| `limit` | query | no | integer, default `100`, min 1, max 500 | Maximum rows to return. Server caps at 500. |
| `date` | query | no | string (date) | Trading date the request targets, in `YYYY-MM-DD`. Defaults to the current trading date (the most recent session that has settled enough data to be queryable). Past dates fall thro… |
| `ticker` | query | no | string |  |
| `min_premium` | query | no | number (double) |  |
| `max_premium` | query | no | number (double) |  |
| `min_volume` | query | no | integer, min 0 |  |
| `max_volume` | query | no | integer, min 0 |  |
| `min_oi` | query | no | integer, min 0 |  |
| `max_oi` | query | no | integer, min 0 |  |
| `right` | query | no | one of `C`, `P` |  |
| `min_dte` | query | no | integer |  |
| `max_dte` | query | no | integer |  |
| `min_strike` | query | no | number (double) |  |
| `max_strike` | query | no | number (double) |  |
| `expiration` | query | no | string (date) |  |
| `min_iv` | query | no | number (double) |  |
| `max_iv` | query | no | number (double) |  |
| `order_by` | query | no | one of `premium`, `volume`, `oi`, `iv` |  |
| `order` | query | no | one of `asc`, `desc` |  |
| `only_sweeps` | query | no | boolean, default `false` |  |
| `only_multi_leg` | query | no | boolean, default `false` |  |
| `exclude_multi_leg` | query | no | boolean, default `false` |  |

### `GET /v1/contract/unusual-volume`

Contracts with unusual relative volume

| Parameter | In | Required | Type | Notes |
| --- | --- | --- | --- | --- |
| `limit` | query | no | integer, default `50`, min 1, max 200 | Maximum rows to return. |
| `min_rvol` | query | no | number (double), default `2.0` |  |
| `avg_period` | query | no | string, default `10d` | Baseline window as `{N}d`. Must be 2–365 days. |
| `min_avg_volume` | query | no | integer, default `100`, min 0 |  |
| `min_premium` | query | no | number (double) |  |
| `ticker` | query | no | string |  |
| `right` | query | no | one of `C`, `P` |  |
| `min_dte` | query | no | integer |  |
| `max_dte` | query | no | integer |  |
| `min_strike` | query | no | number (double) |  |
| `max_strike` | query | no | number (double) |  |
| `expiration` | query | no | string (date) |  |
| `date` | query | no | string (date) | Target trading date (`YYYY-MM-DD`). Defaults to the **previous calendar day** (not the current trading date) since baselines need a settled session. |
| `order_by` | query | no | one of `rvol`, `volume`, `premium`, `vol_oi`, `oi_change` |  |
| `min_vol_oi_ratio` | query | no | number (double) |  |
| `min_oi_change` | query | no | integer |  |
| `max_oi_change` | query | no | integer |  |
| `only_sweeps` | query | no | boolean |  |
| `only_multi_leg` | query | no | boolean |  |
| `exclude_multi_leg` | query | no | boolean |  |
| `min_oi_change_pct` | query | no | number (double) |  |
| `min_bid_imbalance` | query | no | number (double), min 0, max 1 |  |
| `min_ask_imbalance` | query | no | number (double), min 0, max 1 |  |
| `moneyness` | query | no | one of `ITM`, `ATM`, `OTM` |  |
| `min_moneyness_pct` | query | no | number (double) |  |
| `max_moneyness_pct` | query | no | number (double) |  |
| `min_iv` | query | no | number (double) |  |
| `max_iv` | query | no | number (double) |  |
| `exclude_tickers` | query | no | string | Comma-separated tickers to exclude (e.g. `SPY,QQQ,IWM`). |

### `GET /v1/contract/unusual-oi`

Contracts with significant OI changes

| Parameter | In | Required | Type | Notes |
| --- | --- | --- | --- | --- |
| `limit` | query | no | integer, default `50`, min 1, max 200 | Maximum rows to return. |
| `min_oi_change` | query | no | integer, default `500` |  |
| `min_oi_change_pct` | query | no | number (double), default `25.0` |  |
| `ticker` | query | no | string |  |
| `right` | query | no | one of `C`, `P` |  |
| `min_dte` | query | no | integer |  |
| `max_dte` | query | no | integer |  |
| `min_premium` | query | no | number (double) |  |
| `min_volume` | query | no | integer, min 0 |  |
| `date` | query | no | string (date) | Target trading date (`YYYY-MM-DD`). Defaults to the **previous calendar day** (not the current trading date). |
| `order_by` | query | no | one of `oi_change`, `oi_change_pct`, `volume`, `premium` |  |
| `direction` | query | no | one of `opening`, `closing`, `both` |  |
| `only_sweeps` | query | no | boolean |  |
| `only_multi_leg` | query | no | boolean |  |
| `exclude_multi_leg` | query | no | boolean |  |

### `GET /v1/contract/bulk/stats`

Bulk contract stats for a list of symbols

| Parameter | In | Required | Type | Notes |
| --- | --- | --- | --- | --- |
| `symbols` | query | yes | string | Comma-separated OPRA symbols (max 50). |
| `date` | query | no | string (date) | Trading date the request targets, in `YYYY-MM-DD`. Defaults to the current trading date (the most recent session that has settled enough data to be queryable). Past dates fall thro… |

### `GET /v1/contract/{symbol}/stats`

Daily stats for a single contract

| Parameter | In | Required | Type | Notes |
| --- | --- | --- | --- | --- |
| `symbol` | path | yes | string | OPRA option symbol in URL-safe form: `{ticker}__{YYMMDD}{C\|P}{strike×1000, 8 digits}` — the ticker and the 15-character contract block are joined by a **double underscore** (`__`).… |
| `date` | query | no | string (date) | Trading date the request targets, in `YYYY-MM-DD`. Defaults to the current trading date (the most recent session that has settled enough data to be queryable). Past dates fall thro… |

### `GET /v1/contract/{symbol}/chart`

Intraday chart bars for a contract

| Parameter | In | Required | Type | Notes |
| --- | --- | --- | --- | --- |
| `symbol` | path | yes | string | OPRA option symbol in URL-safe form: `{ticker}__{YYMMDD}{C\|P}{strike×1000, 8 digits}` — the ticker and the 15-character contract block are joined by a **double underscore** (`__`).… |
| `interval` | query | yes | string | Trailing window — `{N}D` where N is 1–365 (e.g. `1D`, `7D`). At most `30D` with an intraday bucket. Priced by range: 3 credits per started 30 days. |
| `bucket` | query | yes | one of `1min`, `5min`, `10min`, `15min`, `30min`, `1d`, `1w` |  |

### `GET /v1/contract/{symbol}/trades`

Raw enriched trades for a contract

| Parameter | In | Required | Type | Notes |
| --- | --- | --- | --- | --- |
| `symbol` | path | yes | string | OPRA option symbol in URL-safe form: `{ticker}__{YYMMDD}{C\|P}{strike×1000, 8 digits}` — the ticker and the 15-character contract block are joined by a **double underscore** (`__`).… |
| `start` | query | no | string | Lower time bound — RFC 3339 or Unix seconds. Defaults to start-of-trading-day. |
| `end` | query | no | string | Upper time bound — RFC 3339 or Unix seconds. Defaults to now. |
| `limit` | query | no | integer, default `50`, min 1, max 500 |  |
| `only_sweeps` | query | no | boolean |  |
| `only_multi_leg` | query | no | boolean |  |
| `exclude_multi_leg` | query | no | boolean |  |
| `min_premium` | query | no | number (double), min 0 |  |

### `GET /v1/contract/{symbol}/history`

Daily history for a contract

| Parameter | In | Required | Type | Notes |
| --- | --- | --- | --- | --- |
| `symbol` | path | yes | string | OPRA option symbol in URL-safe form: `{ticker}__{YYMMDD}{C\|P}{strike×1000, 8 digits}` — the ticker and the 15-character contract block are joined by a **double underscore** (`__`).… |
| `start_date` | query | yes | string (date) |  |
| `end_date` | query | yes | string (date) |  |

### `GET /v1/contract/{symbol}/rvol`

Relative-volume bars for a contract

| Parameter | In | Required | Type | Notes |
| --- | --- | --- | --- | --- |
| `symbol` | path | yes | string | OPRA option symbol in URL-safe form: `{ticker}__{YYMMDD}{C\|P}{strike×1000, 8 digits}` — the ticker and the 15-character contract block are joined by a **double underscore** (`__`).… |
| `interval` | query | no | string, default `1D` | Trailing window — `{N}D` where N is 1–365. |
| `bucket` | query | no | one of `1min`, `5min`, `10min`, `15min`, `30min`, `1d`, `1w` |  |
| `avg_period` | query | no | string, default `14d` | Baseline lookback as `{N}d` (e.g. `14d`). Max 365 days. |
| `date` | query | no | string (date) | Trading date the request targets, in `YYYY-MM-DD`. Defaults to the current trading date (the most recent session that has settled enough data to be queryable). Past dates fall thro… |
| `order_by` | query | no | one of `rvol`, `volume`, `premium`, `time` |  |
| `order` | query | no | one of `asc`, `desc` | Sort direction. Defaults to `asc` when `order_by=time`, otherwise `desc`. |
| `limit` | query | no | integer, min 1 |  |
| `format` | query | no | one of `full`, `summary` |  |

### `GET /v1/dark-pool/trades`

Paginated off-exchange (TRF) prints

| Parameter | In | Required | Type | Notes |
| --- | --- | --- | --- | --- |
| `tickers` | query | no | string | Comma-separated tickers to include (e.g. `AAPL,NVDA`, max 50). Omit for all names. |
| `date` | query | no | string (date) | Single trade date (`YYYY-MM-DD`, ET). Defaults to today (ET). |
| `date_start` | query | no | string (date) | Inclusive start of a trade-date range (`YYYY-MM-DD`, ET). Max span 31 days. |
| `date_end` | query | no | string (date) | Inclusive end of a trade-date range (`YYYY-MM-DD`, ET). Max span 31 days. |
| `time_start` | query | no | string | Inclusive lower bound of the time-of-day window (`HH:MM`, ET). |
| `time_end` | query | no | string | Inclusive upper bound of the time-of-day window (`HH:MM`, ET). |
| `min_notional` | query | no | number (double), default `1000000` | Minimum notional (USD). Defaults to 1,000,000. Pass 0 for the firehose. |
| `max_notional` | query | no | number (double) |  |
| `min_size` | query | no | integer, min 0 |  |
| `max_size` | query | no | integer, min 0 |  |
| `min_price` | query | no | number (double) |  |
| `max_price` | query | no | number (double) |  |
| `min_avg_vol` | query | no | number (double) | Minimum AvgVol — the print's size as a percent of the underlying's average daily volume (`pctAvgVol`). Prints with no known ADV are excluded when this is set. |
| `max_avg_vol` | query | no | number (double) | Maximum AvgVol (percent of average daily volume). Prints with no known ADV are excluded when this is set. |
| `sectors` | query | no | string | Comma-separated GICS sectors to include. |
| `industries` | query | no | string | Comma-separated GICS industries to include. |
| `venue` | query | no | one of `FINN`, `FINC` | Reporting venue filter. Omit for both. |
| `limit` | query | no | integer, default `500`, min 1, max 5000 | Page size (server caps at 5000). |
| `offset` | query | no | integer, default `0`, min 0, max 50000 | Row offset for pagination. |
| `order` | query | no | one of `asc`, `desc` | Sort by trade time. |

### `GET /v1/dark-pool/top-prints/{ticker}`

Largest individual dark-pool prints for a ticker

| Parameter | In | Required | Type | Notes |
| --- | --- | --- | --- | --- |
| `ticker` | path | yes | string | Underlying ticker symbol (uppercase, e.g. `SPY`, `AAPL`). |
| `top_n` | query | no | integer, default `5`, min 1, max 20 | Number of largest prints to return. |
| `lookback_days` | query | no | integer, default `45`, min 1, max 180 | Calendar-day trailing window. |
| `as_of_date` | query | no | string (date) | Optional anchor date (`YYYY-MM-DD`); the window becomes `[as_of_date - lookback_days, as_of_date]`. Omit for a today-anchored window. |

### `GET /v1/openapi.json`

This OpenAPI specification, as JSON

## Atlas — OHLCV bars

Base URL `https://atlas-api.skylit.ai`. Spec: https://www.skylit.ai/docs/atlas-openapi.yaml

### `GET /v1/history`

OHLCV price bars for a symbol and resolution

| Parameter | In | Required | Type | Notes |
| --- | --- | --- | --- | --- |
| `symbol` | query | yes | string | Ticker (e.g. `SPY`). |
| `resolution` | query | yes | one of `1`, `2`, `3`, `5`, `15`, `30`, `60`, `240`, `480`, `D`, `W` | Bar size. Intraday minutes or `D`/`W`. |
| `from` | query | yes | integer (int64) | Window start, Unix seconds (UTC). |
| `to` | query | yes | integer (int64) | Window end, Unix seconds (UTC). |
| `countback` | query | no | integer, min 1 | When set, return exactly this many bars ending at `to` (takes precedence over `from`, per the UDF spec). |
| `extended` | query | no | boolean, default `false` | Include extended-hours (pre / post-market) bars. Default is regular trading hours only (09:30–16:00 ET). |

### `GET /v1/search`

Search symbols

| Parameter | In | Required | Type | Notes |
| --- | --- | --- | --- | --- |
| `query` | query | yes | string | Search text (ticker or name fragment). |
| `limit` | query | no | integer, default `25`, min 1, max 500 | Max results. Stay within 1–500; out-of-range values are not rejected today, and their behaviour is not guaranteed. |

### `GET /v1/symbols`

Resolve a symbol

| Parameter | In | Required | Type | Notes |
| --- | --- | --- | --- | --- |
| `symbol` | query | yes | string | Ticker (e.g. `SPY`). |

### `GET /v1/config`

Datafeed configuration

### `GET /v1/time`

Server time

### `GET /v1/openapi.json`

This OpenAPI specification, as JSON

## MCP tools

Each tool calls the listed endpoint with the same credit cost. Bold arguments are required.

| Tool | Returns | Arguments | Endpoint | Credits |
| --- | --- | --- | --- | --: |
| `flow_search` | Search underlyings by ticker fragment | **`q`**, `limit` | `GET /v1/underlying/search` | 1 |
| `list_active_underlyings` | Every underlying that traded options on a date, ranked by premium | `date`, `limit`, `min_premium`, `min_volume` | `GET /v1/underlying` | 1 |
| `expirations` | Available expiration dates for an underlying, with contract counts | **`ticker`**, `date` | `GET /v1/underlying/{ticker}/expirations` | 1 |
| `flow_feed` | Recent scored trades (Flow Score, FlowBonus) + VWF/SDF/FIR aggregates | **`ticker`**, `date`, `limit`, `min_premium`, `moneyness`, `option_type`, `timeframe`, `trade_type` | `GET /v1/flow/{ticker}` | 1 |
| `trade_score` | Full scoring + context for one trade id (from a `flow_feed` row) | **`trade_id`** | `GET /v1/score/{trade_id}` | 1 |
| `aggregate_score` | Composite + VWF/SDF/FIR across one or more trailing timeframes | **`ticker`**, `date`, `include_breakdown`, `include_moneyness`, `timeframes` | `GET /v1/aggregate/{ticker}` | 3 |
| `flow_aggregate` | Server-side rollup over an arbitrary `[start_time, end_time]` window | **`ticker`**, **`start_time`**, **`end_time`**, `date`, `exclude_multi_leg`, `max_dte`, `min_dte`, `min_premium`, `option_type` | `GET /v1/flow/{ticker}/aggregate` | 3 |
| `sweeps` | Aggregated multi-exchange sweeps with venues, premium, moneyness, score | **`ticker`**, `date`, `limit`, `min_premium`, `moneyness`, `option_type`, `timeframe` | `GET /v1/sweeps/{ticker}` | 3 |
| `flow_momentum` | Live 5m/30m/1h flow vs trailing baseline, with z-scores + trend label | **`ticker`**, `as_of`, `lookback_days` | `GET /v1/flow/{ticker}/momentum` | 3 |
| `flow_baseline` | Trailing per-time-of-day baseline `flow_momentum` compares against | **`ticker`**, `bucket`, `end_time_of_day`, `lookback_days`, `max_dte`, `min_dte`, `start_time_of_day` | `GET /v1/flow/{ticker}/baseline` | 3 |
| `flow_strikes` | Top-N strikes by net/total premium with bull/bear split + OI context | **`ticker`**, **`start_time`**, **`end_time`**, `min_premium`, `order_by`, `right`, `top_n` | `GET /v1/flow/{ticker}/strikes` | 3 |
| `flow_tide` | Bucketed bullish vs bearish premium with cumulative net premium | **`ticker`**, **`start_time`**, **`end_time`**, `bucket`, `min_premium`, `option_type` | `GET /v1/flow/{ticker}/tide` | 3 |
| `by_strike` | Strike-level distribution of a day's flow, optionally by DTE band | **`ticker`**, `date`, `dte_filter`, `interval` | `GET /v1/underlying/{ticker}/by-strike` | 3 |
| `top_underlyings_daily` | Top underlyings by single-day flow (call/put split, net premium, ratio) | `date`, `limit`, `min_premium`, `min_volume`, `order`, `order_by` | `GET /v1/underlying/top/daily` | 1 |
| `top_underlyings_weekly` | Same, over the trailing week | `date`, `limit`, `min_premium`, `min_volume`, `order`, `order_by` | `GET /v1/underlying/top/weekly` | 1 |
| `top_contracts_daily` | Single-day top-contract screener (premium / volume / OI / sweeps) | `date`, `limit`, `min_oi`, `min_premium`, `min_volume`, `only_sweeps`, `order`, `order_by`, `right`, `ticker` | `GET /v1/contract/top/daily` | 3 (1 with `ticker`) |
| `top_contracts_weekly` | Same, over the trailing week | `date`, `limit`, `min_oi`, `min_premium`, `min_volume`, `only_sweeps`, `order`, `order_by`, `right`, `ticker` | `GET /v1/contract/top/weekly` | 1 |
| `unusual_volume` | Contracts with anomalous volume vs an `avg_period` baseline (RVOL) | `avg_period`, `date`, `exclude_tickers`, `limit`, `min_premium`, `min_rvol`, `moneyness`, `order_by`, `right`, `ticker` | `GET /v1/contract/unusual-volume` | 3 |
| `unusual_oi` | Contracts with significant open-interest changes (opening vs closing) | `date`, `direction`, `limit`, `min_oi_change`, `min_oi_change_pct`, `order_by`, `right`, `ticker` | `GET /v1/contract/unusual-oi` | 3 |
| `chain_bull_bear` | Chain-level bull/bear/neutral % with call- and put-only breakdowns | **`ticker`**, `date`, `min_premium`, `option_type`, `timeframe` | `GET /v1/chain-bull-bear/{ticker}` | 3 |
| `contract_bull_bear` | Bull/bear/neutral % for a single OPRA contract | **`symbol`**, `date`, `min_premium`, `timeframe` | `GET /v1/contract-bull-bear/{symbol}` | 1 |
| `chain_ratio` | Chain-level ask/bid/mid + aggression ratios with a bias interpretation | **`ticker`**, `date`, `max_dte`, `min_dte`, `min_premium`, `option_type`, `timeframe` | `GET /v1/chain-ratio/{ticker}` | 1 |
| `contract_ratio` | Same bid/ask/mid pressure for a single OPRA contract | **`symbol`**, `date`, `min_premium`, `timeframe` | `GET /v1/contract-ratio/{symbol}` | 1 |
| `underlying_stats` | Daily aggregate stats for an underlying (premium, volume, net, OI) | **`ticker`**, `date` | `GET /v1/underlying/{ticker}/stats` | 1 |
| `underlying_bulk_stats` | One-day stats (premium, volume, call/put split, net premium) for up to 50 tickers in one call; tickers with no options activity are absent | **`tickers`**, `date` | `GET /v1/underlying/bulk/stats` | 5 |
| `contract_bulk_stats` | One-day stats for up to 50 option contracts (OPRA symbols) in one call | **`symbols`**, `date` | `GET /v1/contract/bulk/stats` | 5 |
| `underlying_history` | Daily options-flow history for a ticker, one row per trading day (premium, volume, call/put split, net premium) | **`ticker`**, **`start_date`**, **`end_date`** | `GET /v1/underlying/{ticker}/history` | 5 |
| `contract_history` | Daily history for one contract: premium, volume, OI change, bid/ask split, sweep and multi-leg share, VWAP, last price, IV, trade count | **`symbol`**, **`start_date`**, **`end_date`** | `GET /v1/contract/{symbol}/history` | 5 |
| `flow_historical_compare` | Today's flow vs its trailing 20-trading-day average: deltas, percentile ranks and the five most similar past days | **`ticker`**, `date` | `GET /v1/flow/{ticker}/historical-compare` | 5 |
| `contract_stats` | Daily aggregate stats for a contract (volume, OI, premium, IV) | **`symbol`**, `date` | `GET /v1/contract/{symbol}/stats` | 1 |
| `vol_oi` | Vol/OI accumulation analysis; distinguishes new positioning from closing | **`ticker`**, `date`, `min_oi`, `moneyness`, `option_type`, `timeframe` | `GET /v1/vol-oi/{ticker}` | 1 |
| `moneyness` | Premium/sentiment split across deep_itm…deep_otm + detected patterns | **`ticker`**, `date`, `min_premium`, `timeframe` | `GET /v1/moneyness/{ticker}` | 1 |
| `option_chain` | Full chain at an expiration (per-strike call/put volume, OI, premium) | **`ticker`**, **`expiration`**, `date`, `min_volume` | `GET /v1/underlying/{ticker}/chain` | 3 |
| `underlying_chart` | Intraday OHLC-style bars for an underlying | **`ticker`**, **`interval`**, **`bucket`** | `GET /v1/underlying/{ticker}/chart` | 3 |
| `contract_chart` | Intraday OHLC-style bars for a single contract | **`symbol`**, **`interval`**, **`bucket`** | `GET /v1/contract/{symbol}/chart` | 3 |
| `underlying_rvol` | Relative-volume bars for an underlying (`format=summary` for stats only) | **`ticker`**, `avg_period`, `bucket`, `date`, `format`, `interval`, `limit`, `order`, `order_by` | `GET /v1/underlying/{ticker}/rvol` | 1 |
| `contract_rvol` | Relative-volume bars for a single contract | **`symbol`**, `avg_period`, `bucket`, `date`, `format`, `interval`, `limit`, `order`, `order_by` | `GET /v1/contract/{symbol}/rvol` | 1 |
| `market_overview` | Market-wide flow for the day + top tickers by premium | `tickers` | `GET /v1/market/overview` | 3 |
| `market_tide` | Bucketed net call/put premium time series with an SPY overlay | `bucket`, `date`, `exclude_deep_itm`, `exclude_multi_leg`, `interval` | `GET /v1/market/tide` | 3 |
| `market_breadth` | SPY/QQQ/IWM sentiment, advance/decline, per-sector rotation | `date`, `fir_threshold` | `GET /v1/flow/market-breadth` | 3 |
| `sector_flow` | Sector/industry flow aggregation with top-contributor tickers | **`sector`**, `date`, `top_n` | `GET /v1/flow/sector/{sector}` | 3 |
| `dark_pool_trades` | Paginated off-exchange prints (filters: tickers / date range / notional / venue / sector); `$1M+` by default, span capped at 31 days | `date`, `date_end`, `date_start`, `limit`, `max_notional`, `min_notional`, `offset`, `order`, `sectors`, `tickers`, `venue` | `GET /v1/dark-pool/trades` | 5 |
| `dark_pool_top_prints` | Top-N largest prints for a ticker over a trailing window, ordered by notional | **`ticker`**, `as_of_date`, `lookback_days`, `top_n` | `GET /v1/dark-pool/top-prints/{ticker}` | 3 |
| `heat_heatmap` | Current per-strike gamma/vanna heatmap + live velocity (multi-symbol) | **`symbols`**, `expirations`, `layout`, `max_expirations`, `max_strikes`, `metric` | `GET /v1/heatmap` | 1 |
| `heat_levels` | Key levels only: classified nodes (king, gatekeeper, pika, barney, significant), strongest first, with distance from spot | **`symbols`**, `expirations`, `max_expirations`, `max_strikes`, `metric` | `GET /v1/gex/levels` | 1 |
| `heat_historical_heatmap` | Replay the heatmap at a past instant (up to 365 days back) | **`symbols`**, **`at`**, `expirations`, `max_expirations`, `max_strikes`, `metric` | `GET /v1/historical` | 5 |
| `heat_stats_daily` | Daily gamma/vanna stats for up to 50 symbols over up to 31 days (400 symbol-days): spot OHLC, largest positive and negative strike exposure, concentration | **`symbols`**, **`from`**, `metric`, `to` | `GET /v1/stats/daily` | 5 |
| `heat_symbols` | Every symbol with gamma/vanna data: index flag, previous tickers after a rename, available metrics and history date range | none | `GET /v1/symbols` | 0 |
| `tempest_iv` | Constant-maturity IV (SVX) at 1d/9d/30d/3m/6m, IV rank and percentiles, ratio to the VIX, term slope and mean-reversion odds | **`symbols`** | `GET /v1/vol/iv` | 1 |
| `tempest_term` | Implied vol per listed expiry, for contango/backwardation reads | **`symbols`** | `GET /v1/vol/term` | 1 |
| `tempest_cones` | The 1-sigma move priced for today's close, 1 day, the week, monthly opex and 30 days, as percent and price bands | **`symbols`** | `GET /v1/vol/cones` | 1 |
| `tempest_sigma` | Today's move in units of the one-day move priced at the prior close, move budget left, odds of 1- and 2-sigma days, last 60 sessions | **`symbols`** | `GET /v1/vol/sigma` | 1 |
| `tempest_surface` | 30-day 25-delta risk reversal and butterfly, ATM vol, skew percentile, a per-symbol SKEW index and the smile per expiry | **`symbols`** | `GET /v1/vol/surface` | 3 |
| `tempest_tilt` | One-strike-OTM call vs put imbalance (raw and forward-adjusted), the cheap side, z-score and percentile | **`symbols`** | `GET /v1/vol/tilt` | 1 |
| `tempest_events` | Next earnings date and timing, implied event move vs past realized moves, VRP and 20-day realized vol | **`symbols`** | `GET /v1/vol/events` | 1 |
| `tempest_snapshot` | Every Tempest module in one call (iv, term, cones, sigma, surface, tilt, events) | **`symbols`** | `GET /v1/vol/snapshot` | 5 |
| `tempest_market` | VIX1D/9D/VIX/3M/6M, VVIX and SKEW from SPX and VIX chains, curve state and roll, regime, Mag-7 dispersion, Fear & Greed | none | `GET /v1/vol/market` | 1 |
| `tempest_screener` | Radar: screen every covered symbol on IV rank, SVX percentiles, ratio to VIX, skew, tilt, expected move, sigma, earnings, VRP; up to 500 rows | `curve`, `filters`, `limit`, `offset`, `order`, `sector`, `sort` | `GET /v1/vol/screener` | 5 |
| `tempest_history` | One row per stored session at its close (OHLC, SVX per tenor, ATM vol, term slope, skew, tilt, chain depth), up to about two years | **`symbols`**, `fields`, `from`, `to` | `GET /v1/vol/history` | 1 per 10 symbol-weekdays in the window, min 1 (3 for 1 symbol x 1 month) |
| `tempest_derived` | One year daily: 20-day realized vol, VRP series and percentile, the SVX30 usual-range band, earnings-eve sessions, spot-vol correlation | **`symbols`** | `GET /v1/vol/derived` | 3 |
| `tempest_status` | When Tempest last computed, the session it belongs to, whether it is serving the frozen close, market state and coverage counts | none | `GET /v1/vol/status` | 0 |
| `tempest_symbols` | Every symbol Tempest covers, with its latest asOf and last stored daily session | none | `GET /v1/vol/symbols` | 0 |
| `account_usage` | Balance in credits and US dollars, unlimited flag, and the limits that apply | none | `GET /v1/account` | 0 |

## Machine-readable sources

- OpenAPI: https://www.skylit.ai/docs/openapi.yaml, https://www.skylit.ai/docs/flowseeker-openapi.yaml, https://www.skylit.ai/docs/atlas-openapi.yaml
- Live specs: https://api.skylit.ai/v1/openapi.json (core), https://api.skylit.ai/v1/flow/openapi.json (Flowseeker), https://atlas-api.skylit.ai/v1/openapi.json (Atlas)
- Errors: https://www.skylit.ai/docs/api-reference/errors. Rate limits and retries: https://www.skylit.ai/docs/api-reference/rate-limits-and-retries
- Every docs page as Markdown: append `.md` to its URL. Index: https://www.skylit.ai/docs/llms.txt
- This skill: https://www.skylit.ai/.well-known/agent-skills/skylit-api/skill.md