# API/MCP field guide

> Query Skylit's dealer positioning, options flow and volatility data from your own code, or let an AI assistant query it for you over the Model Context Protocol.

> **Note:** Educational material, not financial advice. Nothing here is a recommendation to buy or sell any security. Options involve significant risk and are not suitable for every investor. Past behavior of any reading or setup does not guarantee future results.

> **Note:** **Beta.** The API and MCP server are open to members with API access and still in active development. Tools, limits and names can change. Check what your account includes on the [Developer page](https://app.skylit.ai/developer).

## Why it matters
Skylit computes a lot of things that are hard to compute: where dealers are positioned strike by strike, which options trades were aggressive, and how much movement is priced into a chain relative to that symbol's own past. The app shows you those answers. The API and the MCP server hand you **the same computed numbers** so your own code — or your own AI assistant — can use them.

That matters in three ways:

- **Your screen and your script agree.** Both read the same series, so a rule you check in code is a rule about what the board actually showed.
- **An assistant can answer in English.** Over the Model Context Protocol you ask a question and the assistant picks the tool, reads the result and answers. You do not write the call.
- **You can see what it costs.** Calls are metered in credits, each response carries the balance left, and anything that fails is refunded.

> **Info:** **In plain English.** The app is one way to read Skylit's data: with your eyes. This is the other way: with code, or with an AI assistant that calls Skylit for you. Same numbers, billed by the call.

Everything is **read-only**. There is no way to place, change or cancel an order through the API or the MCP server.

## Where to find it
Open the [Developer page](https://app.skylit.ai/developer) in Skylit. It is where you:

- create and revoke keys — up to five on a paid plan,
- see your credit balance, your monthly allowance and the limits on your account,
- buy a credit pack,
- redeem an invite code, under **Have an invite code?**,
- review and disconnect any AI client you connected with **Sign in with Skylit**.

The full reference lives in the docs:

- [API Reference](https://www.skylit.ai/docs/api-reference/introduction) — every call, its parameters, its response and its cost.
- [MCP overview](https://www.skylit.ai/docs/mcp/overview) — the server, how to authenticate, and what the tools cover.
- [Quickstart](https://www.skylit.ai/docs/mcp/quickstart) — connecting a client, with or without a key.
- [Tool catalog](https://www.skylit.ai/docs/mcp/tools) — all 63 tools, grouped, with costs.
- [Intelligence tools](https://www.skylit.ai/docs/mcp/intelligence) — the short tool list that answers a whole question in one call.
- [Plans and credits](https://www.skylit.ai/docs/api-reference/plans-and-credits) — which plan reaches which data.

## Read it in 30 seconds
| | |
| --- | --- |
| **Data** | `https://api.skylit.ai` over HTTPS, JSON out |
| **AI assistants** | `https://mcp.skylit.ai/mcp` — 63 tools, or the short intelligence list |
| **Sign-in** | A key as a bearer token, or **Sign in with Skylit** on clients that support it |
| **Metering** | Credits, one credit is \$0.001; cost published per call; failures refunded |
| **Allowance** | 100,000 credits a month on Pro and Developer; smaller starting balances elsewhere |
| **Speed** | 600 requests a minute per key |
| **Live** | Server-Sent Events streams for the positioning board and for volatility |
| **Writes** | None. Read-only throughout |

## How to use it
### Over HTTP
Send your key as a bearer token and read JSON. The data divides into four groups:

- **Positioning** — the live per-strike gamma and vanna board for one or more symbols, with the velocity metric and Skylit's node classification; the same board at a past instant; every snapshot across a window; and the classified key levels on their own.
- **Flow** — scored trades, multi-exchange sweeps, bullish-versus-bearish tide, momentum against a trailing baseline of the same time of day, strike concentration, screeners for unusual volume and open-interest change, and dark pool prints.
- **Volatility** — implied volatility per symbol with its percentile, term structure, expected-move cones, the move in units of the implied move, surface and skew, call-versus-put premium imbalance, event implied moves, a screener over the whole universe, and daily history.
- **Account and catalog** — your balance and limits, the symbol catalog, and daily statistics per symbol. The account call is free.

Two of the groups also stream over Server-Sent Events, so a long-running process follows the session rather than polling it.

Price bars are served separately, on their own host; the [API Reference](https://www.skylit.ai/docs/api-reference/introduction) says which.

### Over MCP
The [Model Context Protocol](https://modelcontextprotocol.io) is a standard way for an AI assistant to call outside tools. Point a client at `https://mcp.skylit.ai/mcp` and the assistant can query Skylit in the middle of a conversation: ask *"were there unusual bullish sweeps on TSLA on Friday?"* and it calls the tool that answers, reads the result and replies.

Two ways to connect:

- **Sign in with Skylit.** Clients that support it — including Claude, Claude Code, Cursor, VS Code and ChatGPT — need only the address. The client opens a Skylit page and you click **Approve**. No key is ever pasted into a config file, and you can disconnect it later from the Developer page.
- **A key.** Headless agents, scripts and clients without sign-in send `Authorization: Bearer <your key>` instead.

There are 63 tools, each wrapping one call one-to-one: same sign-in, same cost, same JSON. They are grouped so an assistant can find valid symbols first and then reach for analytics.

> **Tip:** **Start an agent on the intelligence list.** The 63-tool list is a lot of context for an assistant to carry. A separate, much shorter **intelligence** list answers a whole question in one call — where the key levels are, whether volatility is high for this symbol, what moved on the board since a given time, what the market looks like right now, what today's flow is saying — and returns a few factual sentences alongside the figures behind them. See [Intelligence tools](https://www.skylit.ai/docs/mcp/intelligence).

To let an assistant read these guides instead of live data, there is a separate free docs server that needs no key: see [Docs MCP](https://www.skylit.ai/docs/mcp/docs-mcp).

### Credits
Calls are metered in credits. One credit is \$0.001, every call's cost is published on its reference page, and the cost is the same on every plan.

- Pro, Protege, Quant, Lifetime Bootcamp and the **Developer plan at \$349 a month** include **100,000 credits a month**, which reset at the start of each month and are spent before any you added yourself. The Developer plan is the API and MCP access on its own, without the web platform's trading tools.
- Initiate and Community start with **5,000 credits**, once, and then run pay as you go, each with a daily ceiling.
- **Credit packs** start at \$50 for 55,000 credits and stay valid for twelve months. Add one from the Developer page; promo codes do not apply to packs.
- **Anything that fails is refunded** — a rejected or errored call costs nothing, and the balance reported on it already includes the refund.

> **Warning:** **Read your limits, don't hard-code them.** Limits change. The free account call and the rate-limit header always report what applies to your key. Have your agent read them at startup instead of copying a number out of a guide.

### Keys
Treat a key like a password. Keep it in an environment variable, never in source control and never pasted into a shared prompt. If one leaks, revoke it on the Developer page and create another — you can hold five at once, which is enough to rotate without downtime.

## Use it with other Skylit tools
- **Heatseeker.** The board, the key levels and the replay window you read on screen, as JSON. Useful for checking an idea against what the board actually showed at the time.
- **Flowseeker.** The scored flow, sweeps and tide behind the live feed, so a screen you assembled by hand can run on a schedule.
- **Tempest.** Volatility readings and the whole-universe screener, on plans that include Tempest. On a plan without it the volatility tools answer with a free refusal rather than a surprise charge.
- **Atlas.** Price bars come from their own host, so a chart you build yourself can line up with the board.

## Ask Talon
Talon already reads this data inside Skylit, so you do not need a key to ask it a question in the app. The MCP server is for the assistant you run yourself — in your editor, in your terminal, or on a machine with no screen.

## Good to know
- **Read-only, always.** No call and no tool can place, change or cancel an order.
- **Beta.** Tools, groupings and limits can still change. Names in the tool catalog are the stable surface; treat anything else as liable to move.
- **Session guardrails on MCP.** The gateway caps how many calls one assistant session may make and how many may be in flight at once. Past the cap a tool returns an error explaining the limit rather than running unbounded, and credits are only ever spent on calls that reach the data.
- **A plan without a product gets a free refusal.** Asking for volatility data on a plan that does not include it returns a not-entitled error and costs nothing.
- **Live numbers move.** A figure fetched a second ago and a figure on screen now can differ. Each response carries the time it was computed; line the two up on that rather than on wall-clock time.
- **Educational.** The data describes what the market is doing. It is not advice, and nothing in a response is a recommendation.

## What's new
_Nothing new for members yet._

## Glossary
_Glossary not exported yet. Run `scripts/export_copy.py`._