# API Reference

> Skylit's real-time options-Greeks heatmaps as a versioned HTTP API.

> **Beta.** The Skylit API and MCP server are in Beta with limited access. [Request access](https://www.skylit.ai/?waitlist=developer) and we'll let you know when yours opens.

The **Skylit Public API** exposes the same real-time options-Greeks (gamma / vanna)
heatmaps that power Heatseeker — per strike, with the live velocity metric and
Skylit's node classification (King, Gatekeeper, Pika, Barney, and more).

- [Live heatmap](https://www.skylit.ai/docs/api-reference/heatmap/live-per-strike-heatmap-one-or-more-symbols): Current per-strike heatmap for one or more symbols, including live `velocityPct`.
- [Historical replay](https://www.skylit.ai/docs/api-reference/heatmap/replay-per-strike-heatmap-at-a-past-instant-one-or-more-symbols): The snapshot nearest any past instant — up to 365 days back.
- [Live stream (SSE)](https://www.skylit.ai/docs/api-reference/heatmap/live-sse-stream-one-symbol-per-connection): A Server-Sent Events feed of live heatmap updates, one symbol per connection.
- [Authentication](https://www.skylit.ai/docs/api-reference/authentication): Bearer API keys, credit metering, and rate limits.
- [Use it over MCP](https://www.skylit.ai/docs/mcp/overview): Every endpoint here is also an MCP tool (`heat_*`) — query it from Claude or Cursor in natural language, same key and credits.

## Base URL

```bash
https://api.skylit.ai
```

## Quickstart

### 1. Get an API key

Generate a key from your [account console](https://app.skylit.ai). New accounts are
seeded with **5,000 credits**.

### 2. Fetch a live heatmap

Pull the current per-strike gamma heatmap for SPY:

```bash cURL
curl "https://api.skylit.ai/v1/heatmap?symbols=SPY&metric=gamma" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

```python Python
import requests

r = requests.get(
    "https://api.skylit.ai/v1/heatmap",
    params={"symbols": "SPY", "metric": "gamma"},
    headers={"Authorization": "Bearer YOUR_API_KEY"},
)
print(r.json()["data"]["symbols"][0]["strikes"][:3])
```

```javascript Node
const res = await fetch(
  "https://api.skylit.ai/v1/heatmap?symbols=SPY&metric=gamma",
  { headers: { Authorization: "Bearer YOUR_API_KEY" } },
);
const { data } = await res.json();
console.log(data.symbols[0].strikes.slice(0, 3));
```

### 3. Go cross-asset

Comma-separate symbols for a single **Trinity** call — `symbols=SPY,SPX,QQQ` — and
each comes back as an element of `data.symbols`.

## How responses look

Every success returns a `data` / `meta` envelope; errors return an `error` object. Fields are camelCase.

```json
{
  "data": {
    "symbols": [
      {
        "symbol": "SPY",
        "asOf": "2026-05-22T14:31:00Z",
        "spot": 591.23,
        "strikes": [
          { "strike": 590, "value": 1894300.4, "nodeType": "king", "velocityPct": 12.4 },
          { "strike": 595, "value": 642100.2, "nodeType": "gatekeeper", "velocityPct": -3.1 }
        ]
      }
    ]
  },
  "meta": { "metric": "gamma", "resolution": "1m", "mode": "live", "cached": false }
}
```

- **Node types** (king · gatekeeper · pika · barney · significant · normal): Each strike carries Skylit's node classification — the same vocabulary used throughout [Patternpedia](https://www.skylit.ai/docs/patternpedia/pattern-the-whipsaw).
- **velocityPct** (live only): Present on `/v1/heatmap`; omitted on `/v1/historical` (velocity is a live metric).
- **Credits** (metered per request): `/v1/heatmap` costs 1, `/v1/historical` costs 5, `/v1/stream` 1 per minute open. Every response carries `X-Credits-Remaining`. See [Authentication](https://www.skylit.ai/docs/api-reference/authentication).