# tickstream — Full Documentation (for LLMs)

> Realtime CME futures, options and Level 2 market data over a dead-simple API.
> This single file is the complete reference — paste it into an LLM to build against tickstream.

- REST base: `https://api.tick-stream.xyz/v1` — auth header `Authorization: Bearer YOUR_API_KEY`
- WebSocket: `wss://stream.tick-stream.xyz/v1/stream?key=YOUR_API_KEY`
- Get an API key: https://tick-stream.xyz/signup
- Symbols are public roots (e.g. `ES`, `NQ`, `CL`, `SPX`); the front-month contract is resolved automatically.
- All timestamps (`ts`) are **Unix seconds**.

---

## 1. Quickstart

```bash
pip install tickstream        # Python
npm i @tickstream/client      # Node / TypeScript
cargo add tickstream          # Rust
go get github.com/Alx90s/tickstream-go   # Go
```

```python
from tickstream import Stream
for tick in Stream("sk_live_…").subscribe("ES", "NQ"):
    print(tick.symbol, tick.price, tick.size, tick.side, tick.ts)
```

```javascript
import { Stream } from "@tickstream/client";
const stream = new Stream("sk_live_…");
for await (const t of stream.subscribe("ES", "NQ"))
  console.log(t.symbol, t.price, t.size, t.side);
```

## 2. Authentication

Every request is authenticated with one secret API key (format `sk_live_…`), found on your dashboard.

- REST: send header `Authorization: Bearer sk_live_…`
- WebSocket: pass `?key=sk_live_…` in the connection URL
- Keep the key private; rotate it anytime from the dashboard (the old key stops working immediately).

Plan gating: the key resolves to your plan; channels you are not entitled to return an error
(`plan_required`). An unknown/invalid key returns `unauthorized`.

## 3. WebSocket streaming

A single long-lived WebSocket. Open it once, subscribe, and receive compact JSON frames. The SDKs
wrap heartbeats, backpressure and reconnection behind a simple iterator.

Connect: `wss://stream.tick-stream.xyz/v1/stream?key=sk_live_…`
(optional shortcut: append `&symbols=ES,NQ` to subscribe to ticks immediately).

### Control frames (client → server)

```json
{ "op": "subscribe",   "channel": "ticks",   "symbols": ["ES","NQ"] }
{ "op": "subscribe",   "channel": "book",    "symbols": ["ES"] }
{ "op": "subscribe",   "channel": "options", "symbols": ["ES","SPX"] }
{ "op": "unsubscribe", "channel": "ticks",   "symbols": ["NQ"] }
{ "op": "pong" }
```

- `op`: `subscribe` | `unsubscribe` | `pong`
- `channel`: `ticks` | `book` (Level 2) | `options`
- `symbols`: array of public symbols

### Messages (server → client)

On connect the server sends `{"type":"welcome","plan":"pro"}`. Then:

`tick` — every trade print:
```json
{ "type":"tick", "symbol":"ES", "price":5283.25, "size":3, "side":"buy", "exch":"CME", "ts":1749556800 }
```
`side` is the aggressor: `buy` or `sell`.

`book` — Level 2 snapshot (Realtime+L2 / Pro):
```json
{ "type":"book", "symbol":"ES", "bids":[[5283.0,12],[5282.75,40]], "asks":[[5283.25,8],[5283.5,33]], "imbalance":0.21, "ts":1749556800 }
```
`bids` descending, `asks` ascending; each level is `[price, size]`. `imbalance` ∈ [-1,1].

`option` — option quote with Black-76 greeks (Pro):
```json
{ "type":"option", "symbol":"ES", "expiry":"20260618", "strike":7425, "right":"put",
  "bid":92.25, "ask":93.0, "price":92.5, "oi":1089,
  "iv":0.175, "delta":-0.52, "gamma":0.0008, "theta":-1.2, "vega":3.4, "ts":1749556800 }
```
Tradier (index/equity) options also include an `occ` field (the OCC option symbol).

`error` — `{"type":"error","error":{"code":"plan_required","message":"…"}}`. Codes: `unauthorized`,
`no_subscription`, `plan_required`, `unknown_symbol`.

`ping` — the server sends `{"type":"ping"}` every ~15s; reply `{"op":"pong"}`. On disconnect,
reconnect and re-send your subscribe frames (no penalty; SDKs resubscribe automatically).

## 4. REST API

Base `https://api.tick-stream.xyz/v1`, header `Authorization: Bearer sk_live_…`.

- `GET /v1/symbols` — the market catalog: `{ "futures":[{"symbol":"ES","name":"E-mini S&P 500","exchange":"CME"},…] }`
- `GET /v1/quote?symbol=ES` — latest snapshot: `{ "symbol":"ES","price":5283.25,"bid":5283.0,"ask":5283.25,"ts":1749556800 }`
- `GET /v1/ticks?symbol=ES&start=2026-06-01T13:30:00Z&end=2026-06-01T20:00:00Z` — historical tick backfill (ISO-8601 UTC range)
- `GET /v1/options?symbol=ES` — latest option-chain snapshot per strike (Pro)

```bash
curl https://api.tick-stream.xyz/v1/quote?symbol=ES \
  -H "Authorization: Bearer sk_live_…"
```

## 5. Symbols & markets

50+ most-traded futures across CME, CBOT, NYMEX, COMEX and EUREX (4,000+ instruments available on
request). Use the public root; the front-month contract is resolved and rolled automatically.

- Equity index: ES (S&P 500), NQ (Nasdaq-100), YM (Dow), RTY (Russell 2000), EMD, MES/MNQ/MYM/M2K (micros), FDAX (DAX), FESX (Euro Stoxx 50)
- Rates: ZN (10Y), ZB (30Y), ZF (5Y), ZT (2Y), ZQ (Fed Funds), SR3 (SOFR), FGBL (Bund)
- Energy: CL (WTI Crude), NG (Natural Gas), RB (Gasoline), HO, BZ (Brent)
- Metals: GC (Gold), SI (Silver), HG (Copper) + micros
- FX: 6E (Euro), 6J (Yen), 6B (Pound), 6A, 6C, 6S
- Option underlyings: futures (ES, NQ…) + index/equity via Tradier (SPX, XSP, NDX, RUT, VIX, SPY, QQQ, IWM, DIA)

Need another symbol? Email support@tick-stream.xyz — most are enabled fast.

## 6. Level 2 (market depth)

Subscribe `{"op":"subscribe","channel":"book","symbols":["ES"]}` (Realtime+L2 or Pro). You receive
`book` snapshots with full bid/ask depth and an `imbalance` field for order-flow signals.

## 7. Options & greeks

Subscribe `{"op":"subscribe","channel":"options","symbols":["ES","SPX"]}` (Pro). Covers **CME futures
options** (via R|API) and **index/equity options** (via Tradier). Each `option` frame carries bid/ask,
open interest, implied vol and Black-76 greeks (delta, gamma, theta, vega).

## 8. Plans & limits

- **Delayed** — free: 15-minute delayed feed, 50+ futures, full historical backfill.
- **Realtime** — $19.99/mo: realtime ticks, all markets, unlimited messages.
- **Realtime + L2** — $49.99/mo: adds Level 2 order-book depth.
- **Pro** — $99.99/mo: adds futures + index/equity options with greeks.

All plans include every SDK + LLM/MCP access. Flat pricing, no per-message overages.

## 9. SDKs

- Node / TypeScript: `npm i @tickstream/client`
- Python: `pip install tickstream`
- Rust: `cargo add tickstream`
- Go: `go get github.com/Alx90s/tickstream-go`
- Plus raw WebSocket + REST for any other language.

## 10. LLM / MCP integration

Give Claude, Cursor, or any MCP agent live market-data tools.

- Claude Code (CLI): `claude mcp add tickstream -e TICKSTREAM_API_KEY=sk_live_… -- npx -y tickstream-mcp`
- Remote connector (Claude Desktop/Web): add `https://mcp.tick-stream.xyz/<API_KEY>/mcp` as a custom connector
- Cursor / VS Code: one-click install deeplink (from your dashboard)

Tools exposed: `get_quote`, `stream_ticks`, `get_book`, `get_options`, `list_symbols`.

---

Contact: support@tick-stream.xyz · Docs: https://tick-stream.xyz/docs