Live stream

The live stream pushes two kinds of events over one WebSocket:

Trades: every trade of your users’ verified wallets the moment it is indexed, with the trader’s CabalSpy ID profile. It is the live version of Latest trades and sends the same trade objects.
Theses: every new thesis, reply, reaction and removal, on all tokens or on one token. Theses are public, so these events are not limited to your users.

The stream is included from the Pro plan. Instances in development or sandbox mode can use it for testing.

For theses only, use the dedicated theses stream: it is included on every plan, lets you subscribe to up to 200 tokens per connection and supports the instance reach.

Connecting

Open a WebSocket and pass your API key as the api_key or apiKey query parameter, or as an Authorization Bearer header. Choose what you receive with events. There is nothing else to subscribe to, the connection starts streaming right away.

wss://api-id.cabalspy.xyz/v1/stream?apiKey=YOUR_KEY
wss://api-id.cabalspy.xyz/v1/stream?apiKey=YOUR_KEY&events=theses&blockchain=solana&mint=TOKEN_MINT
wss://api-id.cabalspy.xyz/v1/stream?apiKey=YOUR_KEY&events=trades,theses

string

required

Your API key. api_key works too, or an Authorization Bearer header.

string

default:"trades"

trades, theses or trades,theses.

string

Only events on this chain. One of solana, bnb, base, eth, rh. Empty means every chain.

string

Only thesis events of this token. Needs blockchain. Trades are not filtered by mint.

string

default:"instance"

global streams trades of every CabalSpy ID user. Enterprise plan only.

string

Your Instance ID. Only needed when your account has several instances.

const ws = new WebSocket("wss://api-id.cabalspy.xyz/v1/stream?apiKey=YOUR_KEY&events=trades,theses&blockchain=solana");

ws.onmessage = (e) => {
  const msg = JSON.parse(e.data);
  switch (msg.event) {
    case "trade":
      console.log(msg.data.trader?.username, msg.data.transaction_type, msg.data.token_symbol, msg.data.value_usd);
      break;
    case "thesis":
      console.log("new thesis on", msg.data.mint, "by", msg.data.author.username);
      break;
    case "error":
      console.error(msg.error.code, msg.error.message);
      break;
  }
};

import asyncio, json, websockets

async def main():
    url = "wss://api-id.cabalspy.xyz/v1/stream?apiKey=YOUR_KEY&events=trades,theses&blockchain=solana"
    async with websockets.connect(url) as ws:
        async for raw in ws:
            msg = json.loads(raw)
            if msg["event"] == "trade":
                t = msg["data"]
                print(t["trader"] and t["trader"]["username"], t["transaction_type"], t["token_symbol"])
            elif msg["event"].startswith("thesis"):
                print(msg["event"], msg["data"]["mint"])
            elif msg["event"] == "error":
                print("error", msg["error"])

asyncio.run(main())

Messages

Every message is a JSON object with an event field.

Event	When	Content
`subscribed`	Right after connecting.	`data.blockchain` (a chain or `all`), `data.events`, `data.mint` and `data.scope`.
`trade`	A trade of one of your users.	`data`, a trade object as in Latest trades.
`thesis`	A new thesis.	`data`, the thesis.
`thesis.reply`	A new reply.	`data`, the reply.
`thesis.reaction`	Reactions on a post changed.	`data.id` and `data.reactions`, the new counts.
`thesis.removed`	A post was deleted or hidden after reports.	`data.id`.
`heartbeat`	After 30 seconds without a message from you.	`ts`, Unix time in seconds.
`pong`	After you send `ping`.	Nothing else.
`error`	The connection is refused.	`error.code` and `error.message`. The server then closes with code 4403.

subscribed

{ "event": "subscribed", "data": { "blockchain": "solana", "events": ["theses", "trades"], "mint": null, "scope": "instance" } }

trade

{
  "event": "trade",
  "data": {
    "signature": "5xr8abc...",
    "blockchain": "solana",
    "wallet": "7j7AA3HZR2zEjwAQEKPFh2qucLY4fqZpB9iodf39w8xW",
    "mint": "3Pkrq4MmLvDXyn1fa3sz5MekKRkZkc1iLDcz5AzWpump",
    "transaction_type": "buy",
    "token_symbol": "invisibull",
    "token_name": "invisibull",
    "token_logo": "https://...",
    "token_amount": 22113972.03,
    "value": 1.66,
    "value_usd": 137.44,
    "currency": "SOL",
    "timestamp": "2026-10-13T08:03:58Z",
    "trader": {
      "csid_id": "0b7c4a52-3f1e-4f43-9d0a-2b5e7c1d9a11",
      "username": "MazeCCC",
      "name": "Maze",
      "image_url": "https://pbs.twimg.com/profile_images/.../photo.jpg",
      "kol": true
    }
  }
}

heartbeat

{ "event": "heartbeat", "ts": 1791878575 }

error

{ "event": "error", "error": { "code": "plan_required", "message": "The live stream is included from the Pro plan. Your plan: starter." } }

Thesis events

Thesis events carry blockchain and mint in data next to the fields of the post. thesis and thesis.reply contain the full object as in List theses.

thesis

{
  "event": "thesis",
  "data": {
    "blockchain": "solana",
    "mint": "3Pkrq4MmLvDXyn1fa3sz5MekKRkZkc1iLDcz5AzWpump",
    "id": "8d1f5a2e-6c4b-4e0f-9a7d-1b2c3d4e5f60",
    "chain": "solana",
    "kind": "thesis",
    "parent_id": null,
    "body": "Strong community, still early.",
    "stance": "bull",
    "author": { "csid_id": "0b7c4a52-3f1e-4f43-9d0a-2b5e7c1d9a11", "username": "MazeCCC", "name": "Maze", "image_url": "https://pbs.twimg.com/profile_images/.../photo.jpg", "kol_badge": true, "profile_url": "https://id.cabalspy.xyz/u/MazeCCC" },
    "likes": 0,
    "replies": 0,
    "reactions": {},
    "my_reactions": [],
    "via": "Example Terminal",
    "created_at": "2026-10-13T09:12:44.512113+00:00",
    "is_mine": false,
    "position": { "private": true }
  }
}

thesis.reaction

{ "event": "thesis.reaction", "data": { "blockchain": "solana", "mint": "3Pkrq4MmLvDXyn1fa3sz5MekKRkZkc1iLDcz5AzWpump", "id": "8d1f5a2e-6c4b-4e0f-9a7d-1b2c3d4e5f60", "reactions": { "like": 5 } } }

thesis.removed

{ "event": "thesis.removed", "data": { "blockchain": "solana", "mint": "3Pkrq4MmLvDXyn1fa3sz5MekKRkZkc1iLDcz5AzWpump", "id": "8d1f5a2e-6c4b-4e0f-9a7d-1b2c3d4e5f60" } }

Client-side apps without an API key can follow one token’s theses on the public websocket of the browser API.

Staying connected

Send the text ping at any time to check the connection, the server answers with pong. When you send nothing for 30 seconds, the server sends a heartbeat. At the same time it picks up users who joined or left your instance and checks that your key is still valid. A revoked or disabled key ends the connection. Reconnect with a short backoff when the connection drops, and use Latest trades or List theses to fill any gap.

Limits and errors

Each API key can hold at most 5 stream connections at once.

Code	Meaning
invalid_api_key	API key missing, invalid or not enabled for CabalSpy ID.
plan_required	The stream is included from the Pro plan.
invalid_parameter	blockchain, events or mint invalid.
missing_parameter	mint was passed without blockchain.
scope_not_allowed	scope=global needs the Enterprise plan.
too_many_connections	At most 5 stream connections per API key.

Introduction

Login

Data API

Users

Trading

Theses

Streams

Reference

Connecting

Messages

Thesis events

Staying connected

Limits and errors

​Connecting

​Messages

​Thesis events

​Staying connected

​Limits and errors

Connecting

Messages

Thesis events

Staying connected

Limits and errors