# Getting started for agentic traders

> From zero to live REST calls and a connected MCP server in Claude, Claude Code or Cursor in about five minutes.

> **Beta.** The API and MCP server come with paid Skylit memberships. See [Plans and credits](https://www.skylit.ai/docs/api-reference/plans-and-credits) for what your plan includes.

One Skylit account gives your agent three data sets through one credit balance:

| Data | What it answers | REST base URL |
| --- | --- | --- |
| **Heatseeker** | Where are dealer gamma/vanna levels (king node, gatekeepers, walls)? | `https://api.skylit.ai` |
| **Flowseeker** | What options flow, sweeps and dark-pool prints are hitting a ticker? | `https://api.skylit.ai` (or `https://flow-api.skylit.ai`) |
| **Atlas** | OHLCV price bars and symbol search | `https://atlas-api.skylit.ai` |
| **MCP server** | All of the above as tools for Claude, Cursor and other MCP clients | `https://mcp.skylit.ai/mcp` |

## 1. Sign in and open the Developer page

Sign in at [app.skylit.ai](https://app.skylit.ai) and open
[Developer](https://app.skylit.ai/developer). Your API account is created the
first time you open it (1 credit = $0.001).

API and MCP access comes with a paid Skylit membership:

| Plan | Data | Credits | Requests per minute | Keys |
| --- | --- | --- | --: | --: |
| **Pro** (also Protege, Quant and Lifetime Bootcamp) | Every symbol and every API, Tempest and historical replay included | 100,000 every month | 120 per key (600 per account across 5 keys) | 5 |
| **Developer** ($349/month, API and MCP only) | Same as Pro | 100,000 every month | 120 per key (600 per account across 5 keys) | 5 |
| **Initiate** | The Initiate plan's 63 index and ETF symbols, historical replay included; no Tempest | 5,000 to start, then pay as you go | 120 per key (600 per account across 5 keys) | 5 |
| **Community** | Flowseeker only | 5,000 to start, then pay as you go | 120 per key (600 per account across 5 keys) | 5 |

Community and up can buy credit packs on the Developer page ($50 buys 55,000
credits). Have an invite code? Redeem it on the Developer page (**Have an invite
code?**). Details: [Plans and credits](https://www.skylit.ai/docs/api-reference/plans-and-credits).

Plans can change. `GET /v1/account` (free) and the `X-RateLimit-Limit` header
always show the values that apply to you, so have your agent read them at startup.

## 2. Pick how your agent connects

### MCP client (no key needed)

Claude, Claude Code and Cursor can sign in with your Skylit account (OAuth).
You don't copy a key: the client opens a Skylit consent page, you click
**Approve**, and the connection appears on the Developer page as
"Connected app".

**Claude (desktop or claude.ai):** Settings, then Connectors, then **Add custom
connector**. Name it `Skylit`, URL `https://mcp.skylit.ai/mcp`, then click
**Connect** and approve.

**Claude Code:**

```bash
claude mcp add --transport http skylit https://mcp.skylit.ai/mcp
```

Then run `/mcp` inside Claude Code, pick **skylit** and choose
**Authenticate**.

**Cursor:** add this to `~/.cursor/mcp.json` (or `.cursor/mcp.json` in a
project), then click **Connect** or **Login** next to the server in
Cursor Settings, MCP:

```json
{
  "mcpServers": {
    "skylit": { "url": "https://mcp.skylit.ai/mcp" }
  }
}
```

### API key (scripts, bots, headless agents)

On the Developer page, open **API keys** and click **Create key**. The full
key is shown **once**: copy it into your secret store or environment.

```bash
export SKYLIT_API_KEY="paste-your-key-here"
```

The same key works for REST and for MCP clients that let you set a header:

```bash
# Claude Code, headless (no browser sign-in)
claude mcp add --transport http skylit https://mcp.skylit.ai/mcp \
  --header "Authorization: Bearer $SKYLIT_API_KEY"
```

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

Your plan sets how many active keys you can have. Use one key per bot so you
can rotate or revoke one without stopping the others.

> **Warning:** Treat keys like passwords. Never commit them, paste them into a shared prompt or
> put them in browser code. If a key leaks, rotate it on the Developer page.

## 3. Make your first REST calls

Every request sends `Authorization: Bearer <key>`.

```bash
# Free: your balance and limits
curl -s https://api.skylit.ai/v1/account -H "Authorization: Bearer $SKYLIT_API_KEY"

# SPY dealer-positioning levels (king node, gatekeepers, walls)
curl -s "https://api.skylit.ai/v1/gex/levels?symbols=SPY" -H "Authorization: Bearer $SKYLIT_API_KEY"

# Latest scored options flow for SPY
curl -s "https://api.skylit.ai/v1/flow/SPY" -H "Authorization: Bearer $SKYLIT_API_KEY"

# SPY 1-minute bars (from/to are Unix seconds)
curl -s "https://atlas-api.skylit.ai/v1/history?symbol=SPY&resolution=1&from=1790602200&to=1790625600" \
  -H "Authorization: Bearer $SKYLIT_API_KEY"
```

```python
import os, requests

s = requests.Session()
s.headers["Authorization"] = f"Bearer {os.environ['SKYLIT_API_KEY']}"

levels = s.get("https://api.skylit.ai/v1/gex/levels", params={"symbols": "SPY,QQQ"})
levels.raise_for_status()
for sym in levels.json()["data"]["symbols"]:
    king = sym["kingNode"]  # null when no king node is classified
    print(sym["symbol"], "king", king["strike"] if king else None, "spot", sym["spot"])
print("credits left:", levels.headers.get("X-Credits-Remaining"))
```

It prints something like this (your numbers will differ):

```text
SPY king 761 spot 765.44
QQQ king 735 spot 736.93
credits left: 4998
```

`GET /v1/account` answers with your balance and the limits your agent should
respect (abridged; values depend on your plan):

```json
{
  "data": {
    "status": "active",
    "creditsBalance": 4998,
    "balanceUsd": 4.998,
    "limits": {
      "requestsPerMinute": 120,
      "symbolsPerHeatmapCall": 10,
      "symbolsPerStream": 10,
      "streamSymbolsConcurrent": 25,
      "historicalInFlight": 2,
      "activeKeys": 5,
      "streamMaxDurationMinutes": 60
    }
  }
}
```

Successful responses are `{"data": ..., "meta": ...}`; errors are
`{"error": {"code", "message"}}`.

## 4. Try the MCP tools

Ask your agent something like:

> Where are SPY's key gamma levels right now, and is today's options flow leaning bullish or bearish?

A good agent calls `heat_levels` and `flow_feed` (or `underlying_stats`), then
answers. Useful first tools:

| Tool | Use it for |
| --- | --- |
| `account_usage` | Balance and limits (free). Ask the agent to call it first. |
| `heat_levels` | Key dealer levels for several symbols in one call (comma-separated, e.g. `SPY,QQQ`) |
| `heat_heatmap` | The full per-strike gamma/vanna board |
| `flow_feed`, `sweeps` | Scored trades and multi-exchange sweeps for a ticker |

Each tool's description states its credit cost.

See the full [tool catalog](https://www.skylit.ai/docs/mcp/tools) and [example prompts](https://www.skylit.ai/docs/mcp/examples).

## 5. Watch your credits

- Every chargeable response carries `X-Credits-Remaining`; MCP results carry
  `creditsRemaining` in `meta`.
- **Failed calls are free.** Any `4xx` or `5xx` is refunded.
- Streams (`/v1/stream`) charge 1 credit per symbol to open, then 1 credit per
  symbol per minute, including symbols that have no live board yet (outside
  market hours). The `connected` event states `creditsPerMinute` and
  `maxDurationSeconds`. A 10-symbol stream left open for an hour costs about
  600 credits.
- The Developer page's **Usage** tab shows spend by endpoint and by key.
- Each endpoint's price is on its [API Reference](https://www.skylit.ai/docs/api-reference/introduction)
  page (`x-credits` in the OpenAPI specs).

## 6. Stay inside your plan's limits

Your plan sets your request rate, number of keys, symbols per call, historical
calls in flight and streams. `GET /v1/account` (or the `account_usage` tool)
returns the exact values for your account, so have your agent read them at
startup instead of hard-coding them.

Every response carries `X-RateLimit-Limit`, `X-RateLimit-Remaining` and
`X-RateLimit-Reset` (Unix seconds) for the key you used; the limit is shared
across all Skylit APIs. When `X-RateLimit-Remaining` reaches `0` you get
`429 rate_limited`: wait until `X-RateLimit-Reset`, then retry. Back off with
jitter rather than retrying in a tight loop.

## If something goes wrong

| You see | Meaning | What to do |
| --- | --- | --- |
| Developer page says "API access not enabled", or `403 API access not enabled for this account` | Your account has no paid plan that includes the API | Choose a plan on [app.skylit.ai](https://app.skylit.ai/products) (see [Plans and credits](https://www.skylit.ai/docs/api-reference/plans-and-credits)), or redeem an invite code on the Developer page (**Have an invite code?**). Questions: the support chat on [app.skylit.ai](https://app.skylit.ai) |
| `401 Authorization field missing` | No `Authorization` header | Send `Authorization: Bearer <key>`. `X-API-Key` and `?token=` are not read |
| `403` with a key | Key revoked, expired, or account suspended | Check the key on the Developer page or create a new one |
| `402 insufficient_credits` | Balance is 0 | Buy a credit pack on the Developer page, or wait for your Monthly API Credits to reset on the 1st (ET) |
| `402 daily_cap_reached` | A daily credit cap set on your account was reached | Wait until midnight ET (`Retry-After`) |
| `402 monthly_cap_reached` | Your account's monthly spend cap was reached | Contact support to raise it |
| `403 not_entitled` on `/v1/vol` or a `tempest_*` tool | Tempest data isn't in your plan (Initiate, Community and invite codes don't include it) | Skip Tempest, or upgrade to Pro or Developer |
| `429 rate_limited` | Over your plan's per-minute request limit on this key | Wait for `X-RateLimit-Reset`, then retry |
| `429` or `503` with `Retry-After` | Too many concurrent historical calls or streams | Wait `Retry-After` seconds |
| MCP client shows "needs login" or a `401` | OAuth sign-in expired or wasn't completed | Reconnect or re-authenticate the server in your client |

- [Build with a coding agent](https://www.skylit.ai/docs/api-reference/agents): One Markdown guide your agent can read to build against the API.
- [MCP quickstart](https://www.skylit.ai/docs/mcp/quickstart): More clients, and raw HTTP for developers.