# 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 are open to members with API access. If the [Developer page](https://app.skylit.ai/developer) says API access isn't enabled on your account, see [If something goes wrong](#if-something-goes-wrong).

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).

During the beta, API and MCP access is by invitation. No membership includes it
automatically.

| Access | How to get it | Starting credits | Requests per minute | Keys | Streams | Tempest (`/v1/vol`) |
| --- | --- | --: | --: | --: | --- | --- |
| **Invite code** | On the Developer page, click **Have an invite code?** and redeem it | 5,000 | 60 per key | 2 | up to 10 symbols per stream, 5 symbols across all your open streams | Not included |
| **Standard** (by arrangement) | Granted by Skylit: email [support@skylit.ai](mailto:support@skylit.ai) | set with your grant | 120 per key | 5 | up to 10 symbols per stream | Included |
| No invite or grant | Not enabled: request access at [support@skylit.ai](mailto:support@skylit.ai) | | | | | |

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` | API access is invite-only and your account has no invite or grant | Redeem an invite code on the Developer page (**Have an invite code?**), or request access at [support@skylit.ai](mailto:support@skylit.ai). 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 | Add credits, or contact support from the chat on [app.skylit.ai](https://app.skylit.ai) |
| `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 access tier (invite codes don't include it) | Skip Tempest, or ask [support@skylit.ai](mailto:support@skylit.ai) |
| `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.