> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cabalspy.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# Get Started

> Real-time WebSocket streams for trades, holder positions, wallet balances, cluster signals and KOL bundle detection across Solana, BNB, Base and ETH.

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 JavaScript theme={null}
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 Python theme={null}
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.

<ParamField body="op" type="string" required>
  The operation. One of subscribe, unsubscribe, subscriptions (list your active channels) or ping (check the connection, you get a pong back).
</ParamField>

<ParamField body="stream" type="string" required>
  Which stream the message applies to. One of tx, count, holder, balance, signal, bundle.
</ParamField>

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.

```json Subscribe theme={null}
{ "op": "subscribe", "stream": "holder", "token": "3Pkrq...pump" }
```

```json Unsubscribe theme={null}
{ "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

<CardGroup cols={2}>
  <Card title="Transactions" href="https://docs.cabalspy.xyz/transactions-1">
    Every buy and sell from tracked wallets, with the running position after each trade.
  </Card>

  <Card title="Count" href="https://docs.cabalspy.xyz/Count">
    The live KOL wallet count per token, a lightweight activity indicator.
  </Card>

  <Card title="Holder" href="https://docs.cabalspy.xyz/holder">
    All holders of a token with live position, bag percentage, unrealized PnL and remaining value.
  </Card>

  <Card title="Balance" href="https://docs.cabalspy.xyz/balance-1">
    The native SOL balance of tracked wallets, updated on every trade.
  </Card>

  <Card title="Signal" href="https://docs.cabalspy.xyz/signal">
    Entry and exit signals when clusters of KOL or Smart Money wallets buy or sell together.
  </Card>

  <Card title="Bundle" href="https://docs.cabalspy.xyz/bundle-1">
    Coordinated KOL bundles on a token, the side wallets buying alongside a KOL, with proof.
  </Card>
</CardGroup>

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