WebSocket Streams - Real-Time KOL and Smart Money Data

CabalSpy provides real-time WebSocket streams for tracked KOL, Smart Money and Whale activity, delivered the moment it happens. Where the REST API returns a snapshot when you ask, the streams push updates to you continuously, live trades, changing positions, moving balances, and freshly detected signals and bundles. Everything runs over a single connection. You open one WebSocket, authenticate once, then subscribe to as many channels as you need. Each channel is independent, and you can subscribe and unsubscribe at any time without reconnecting.

Connecting

Connect to the endpoint and pass your API key, either as a query parameter or as a Bearer header. A connection without a valid key is closed immediately.

JavaScript

const ws = new WebSocket("wss://stream.cabalspy.xyz?apiKey=YOUR_KEY");

ws.onopen = () => {
  ws.send(JSON.stringify({
    op: "subscribe", stream: "tx", blockchain: "solana", type: "kol", token: "*",
  }));
};

ws.onmessage = (e) => {
  const msg = JSON.parse(e.data);
  console.log(msg.event, msg.data);
};

Python

import json, websocket

def on_open(ws):
    ws.send(json.dumps({
        "op": "subscribe", "stream": "tx", "blockchain": "solana", "type": "kol", "token": "*",
    }))

def on_message(ws, message):
    msg = json.loads(message)
    print(msg.get("event"))

ws = websocket.WebSocketApp(
    "wss://stream.cabalspy.xyz?apiKey=YOUR_KEY",
    on_open=on_open, on_message=on_message,
)
ws.run_forever()

On connect you receive a welcome message that lists the available streams and shows example subscriptions, so you can confirm the connection works before subscribing.

How subscriptions work

You drive everything with small JSON messages. Every message has an op field that says what to do, and a stream field that says which stream it applies to.

string

required

The operation. One of subscribe, unsubscribe, subscriptions (list your active channels) or ping (check the connection, you get a pong back).

string

required

Which stream the message applies to. One of tx, count, holder, balance, signal, bundle.

A subscribe message adds a channel, an unsubscribe message removes it. Each stream page shows the exact fields for that stream, but the shape is always the same.

{ "op": "subscribe", "stream": "holder", "token": "3Pkrq...pump" }

Unsubscribe

{ "op": "unsubscribe", "stream": "holder", "token": "3Pkrq...pump" }

Most streams accept a token or wallet filter. Use a specific mint, contract or wallet address to follow one thing, or the value ”*” to follow everything of that kind. Following a single token or wallet usually also returns a starting snapshot.

Available streams

Transactions

Every buy and sell from tracked wallets, with the running position after each trade.

Count

The live KOL wallet count per token, a lightweight activity indicator.

Holder

All holders of a token with live position, bag percentage, unrealized PnL and remaining value.

Balance

The native SOL balance of tracked wallets, updated on every trade.

Signal

Entry and exit signals when clusters of KOL or Smart Money wallets buy or sell together.

Bundle

Coordinated KOL bundles on a token, the side wallets buying alongside a KOL, with proof.

Stream categories

The six streams fall into three groups by what they describe. Holdings and position, what wallets hold right now. The holder stream covers all holders of a token, the balance stream covers a wallet native SOL balance. Signals and detection, derived alerts rather than raw activity. The signal stream fires on buy and sell clusters, the bundle stream surfaces coordinated KOL bundles as they form. Trades and activity, the raw event flow. The transactions stream carries individual trades, the count stream carries the live wallet count per token.

Modes and cost

Each delivered message counts against your plan, the same way a REST request does. A wildcard subscription on a busy chain can produce a lot of messages, so filter to a specific token or wallet when you can. The holder and bundle streams add a mode control. In full mode you also get live position updates every time the market cap moves, in events mode you get only real trades and detections. With full mode, an optional mc_interval caps those price updates to at most once every N seconds. Each of those pages explains the trade-off in detail.

Staying connected

The server sends periodic pings and expects your client to answer with pong, which browsers and standard WebSocket libraries do automatically. A connection that stops answering is dropped. You can also send op ping yourself at any time to confirm the connection is alive.

Introduction

Trades & Activity

Signals & Detection

Holdings & Position

Get Started

Connecting

How subscriptions work

Available streams

Transactions

Count

Holder

Balance

Signal

Bundle

Stream categories

Modes and cost

Staying connected

​Connecting

​How subscriptions work

​Available streams

Transactions

Count

Holder

Balance

Signal

Bundle

​Stream categories

​Modes and cost

​Staying connected

Connecting

How subscriptions work

Available streams

Stream categories

Modes and cost

Staying connected