Signal WebSocket Stream - Live Cluster Entry and Exit

{
  "success": true,
  "channel": "signal.solana",
  "event": "signal",
  "data": {
    "signal_kind": "entry",
    "blockchain": "solana",
    "wallet_types": ["kol"],
    "mint": "3Pkrq4MmLvDXyn1fa3sz5MekKRkZkc1iLDcz5AzWpump",
    "token": {
      "mint": "3Pkrq4MmLvDXyn1fa3sz5MekKRkZkc1iLDcz5AzWpump",
      "symbol": "invisibull",
      "name": "invisibull",
      "supply": 1000000000,
      "decimals": 6,
      "market_cap": 40.08,
      "market_cap_usd": 3301.2,
      "market_cap_currency": "SOL",
      "pool": "pump",
      "on_curve": true,
      "bonding_curve_progress": 42.5
    },
    "threshold": {
      "fired_on": "entry",
      "exit_type": null,
      "exit_remaining": null,
      "currency": "SOL",
      "kol": { "min_buy": 0.5, "entry_at": [3, 5], "exit_at": [1], "max_wallet_buy": null }
    },
    "cluster": {
      "kol": { "qualifying": 5, "sold": 0, "holding": 5 },
      "qualifying_total": 5,
      "total_invested": 12.4,
      "total_invested_usd": 1021.4,
      "unrealized_pnl_sol": -0.4,
      "unrealized_pnl_usd": -32.9,
      "unrealized_pnl_pct": -3.2,
      "currency": "SOL"
    },
    "trigger": {
      "wallet": "7j7AA3HZR2zEjwAQEKPFh2qucLY4fqZpB9iodf39w8xW",
      "action": "buy",
      "value": 3.2,
      "signature": "5xr8abc...",
      "created_at": "2026-07-06T10:52:00Z"
    },
    "wallets": [
      {
        "wallet": "7j7AA3HZR2zEjwAQEKPFh2qucLY4fqZpB9iodf39w8xW",
        "wallet_type": "kol",
        "win_rate": 61.34,
        "profile": {
          "name": "Maze",
          "image_url": "https://cabalspy.xyz/images/7j7AA3HZR2zEjwAQEKPFh2qucLY4fqZpB9iodf39w8xW.png",
          "twitter": "https://x.com/MazeCCC",
          "telegram": "",
          "blockchain": "solana",
          "currency": "SOL",
          "type": "kol"
        },
        "invested": 3.2,
        "invested_usd": 263.6,
        "max_single_buy": 3.2,
        "buy_txn": 1,
        "sell_txn": 0,
        "sold_value": 0.0,
        "sold": false,
        "bag_pct": 100.0,
        "first_buy_at": "2026-07-06T10:20:00Z",
        "entry_market_cap": 44.6,
        "entry_market_cap_usd": 3673.2,
        "unrealized_pnl_sol": -0.1,
        "unrealized_pnl_pct": -3.2
      }
    ]
  },
  "meta": {
    "request_id": "req_5162c7cf7f87",
    "version": "2.0.0",
    "timestamp": "2026-07-06T11:01:57Z"
  }
}

{
  "success": true,
  "channel": "signal.bnb",
  "event": "signal",
  "data": {
    "signal_kind": "entry",
    "blockchain": "bnb",
    "wallet_types": ["kol"],
    "mint": "0x1a2b3c4d5e6f7890abcdef1234567890abcdef12",
    "token": {
      "mint": "0x1a2b3c4d5e6f7890abcdef1234567890abcdef12",
      "symbol": "FOUR",
      "name": "Four Token",
      "supply": 1000000000,
      "decimals": 18,
      "market_cap": 1250.5,
      "market_cap_usd": 750300.0,
      "market_cap_currency": "BNB",
      "pool": "0xpool1234567890abcdef1234567890abcdef1234",
      "on_curve": true,
      "bonding_curve_progress": null
    },
    "threshold": {
      "fired_on": "entry",
      "exit_type": null,
      "exit_remaining": null,
      "currency": "BNB",
      "kol": { "min_buy": 0.2, "entry_at": [3], "exit_at": [1], "max_wallet_buy": null }
    },
    "cluster": {
      "kol": { "qualifying": 3, "sold": 0, "holding": 3 },
      "qualifying_total": 3,
      "total_invested": 2.1,
      "total_invested_usd": 1260.0,
      "unrealized_pnl_sol": 0.35,
      "unrealized_pnl_usd": 210.0,
      "unrealized_pnl_pct": 16.6,
      "currency": "BNB"
    },
    "trigger": {
      "wallet": "0x7a16ff8270133f063aab6c9977183d9e72835428",
      "action": "buy",
      "value": 0.5,
      "signature": "0xabc123...",
      "created_at": "2026-07-17T09:12:04Z"
    },
    "wallets": [
      {
        "wallet": "0x7a16ff8270133f063aab6c9977183d9e72835428",
        "wallet_type": "kol",
        "win_rate": 58.2,
        "profile": {
          "name": "BNB Whale",
          "image_url": null,
          "twitter": "",
          "telegram": "",
          "blockchain": "bnb",
          "currency": "BNB",
          "type": "kol"
        },
        "invested": 0.5,
        "invested_usd": 300.0,
        "max_single_buy": 0.5,
        "buy_txn": 1,
        "sell_txn": 0,
        "sold_value": 0.0,
        "sold": false,
        "bag_pct": 100.0,
        "first_buy_at": "2026-07-17T09:12:04Z",
        "entry_market_cap": 1070.0,
        "entry_market_cap_usd": 642000.0,
        "unrealized_pnl_sol": 0.084,
        "unrealized_pnl_pct": 16.8
      }
    ]
  },
  "meta": {
    "request_id": "req_9a1b2c3d4e5f",
    "version": "2.0.0",
    "timestamp": "2026-07-17T09:12:05Z"
  }
}

Live trade signals as they form. When enough tracked wallets of a type buy the same token, an entry signal fires. When enough of them exit, an exit signal fires. Each signal carries the cluster of wallets, the token with live market cap, per wallet positions with unrealized PnL, and the trigger trade. You define the thresholds when you subscribe, per wallet type, so the same stream can drive a simple two KOL alert or a gated KOL plus Smart Money strategy with win rate and token age filters.

Endpoint

Connect to wss://stream.cabalspy.xyz.

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

ws.onopen = () => {
  ws.send(JSON.stringify({
    op: "subscribe", stream: "signal", blockchain: "solana", token: "*",
    kol: { min_buy: 0.5, entry_at: [3, 5], exit_at: [1] },
    min_win_rate: 50,
  }));
};

ws.onmessage = (e) => {
  const msg = JSON.parse(e.data);
  if (msg.event === "signal") {
    const d = msg.data;
    console.log(d.signal_kind, d.token.symbol, "wallets", d.cluster.qualifying_total);
  }
};

import json, websocket

def on_open(ws):
    ws.send(json.dumps({
        "op": "subscribe", "stream": "signal", "blockchain": "solana", "token": "*",
        "kol": {"min_buy": 0.5, "entry_at": [3, 5], "exit_at": [1]},
        "min_win_rate": 50,
    }))

def on_message(ws, message):
    msg = json.loads(message)
    if msg.get("event") == "signal":
        d = msg["data"]
        print(d["signal_kind"], d["token"]["symbol"])

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

Authentication

Provide your API key as a query parameter, wss://stream.cabalspy.xyz?apiKey=YOUR_KEY, or as a header, Authorization: Bearer YOUR_KEY. Invalid keys are closed with code 1008.

Chains and wallet types

blockchain	Wallet types	Native currency
solana	kol, smart, whale	SOL
bnb	kol, smart	BNB
base	kol, smart	ETH
eth	kol	ETH
rh	kol, smart	ETH

Smart Money is not available on eth, so a smart block on that chain has no effect. min_buy and every value in the payload are denominated in the chain native currency, so a min_buy of 0.5 means 0.5 SOL on Solana and 0.5 BNB on BNB Chain. Live market cap, entry market cap and unrealized PnL are now delivered on every chain. On BNB, Base, Ethereum and Robinhood these fields used to be null and are now filled. To start receiving signals, send a subscribe message after the connection opens. You pick a chain, a token to watch, and the rules that decide when a signal fires. The simplest subscription fires an entry when three or more KOL wallets buy the same token, and an exit when only one is left holding.

Simple KOL cluster

{
  "op": "subscribe",
  "stream": "signal",
  "blockchain": "solana",
  "token": "*",
  "kol": { "entry_at": [3], "exit_at": [1] }
}

The token field is ”*” for all tokens, or a single token mint or contract address to watch one token. The rules live in a kol block and, if you want Smart Money too, a smart block. Each block has the same shape. Inside a block, entry_at is a list of wallet counts that each fire an entry signal. For example entry_at of [3, 5] fires once when the third qualifying wallet buys, and again when the fifth does. exit_at is a list of remaining holder counts that fire an exit, so [1] fires when only one qualifying wallet is still holding. min_buy is the smallest buy, in native currency, for a wallet to count. max_wallet_buy is an optional upper limit per wallet.

KOL and Smart Money together, with filters

{
  "op": "subscribe",
  "stream": "signal",
  "blockchain": "solana",
  "token": "*",
  "kol":   { "min_buy": 0.5, "entry_at": [3, 5], "exit_at": [1] },
  "smart": { "min_buy": 1.0, "entry_at": [2] },
  "min_win_rate": 50,
  "min_token_age": 1,
  "max_token_age": 48
}

The same cluster on BNB, min_buy is in BNB

{
  "op": "subscribe",
  "stream": "signal",
  "blockchain": "bnb",
  "token": "*",
  "kol":   { "min_buy": 0.2, "entry_at": [3], "exit_at": [1] },
  "smart": { "min_buy": 0.5, "entry_at": [2] }
}

When you provide both a kol and a smart block, the entry gate is an AND. Every configured type must reach its own entry_at minimum before an entry signal fires.

string

required

The operation. Use subscribe to start.

string

required

Set to signal for this stream.

string

required

Chain. One of solana, bnb, base, eth, rh. Smart Money is not available on eth.

string

Which token to watch. Either ”*” for all tokens, or a single token mint or contract address.

object

KOL rules. Fields: min_buy (minimum buy per wallet, native currency), entry_at (list of wallet counts that fire an entry, up to 3 values), exit_at (list of remaining holder counts that fire an exit, up to 2 values), max_wallet_buy (optional per wallet cap).

object

Smart Money rules, same shape as kol. Only where Smart Money is supported.

number

Only count wallets whose lifetime win rate is at least this percentage.

array

Whitelist. Only these wallet addresses count toward a cluster.

array

Blacklist. These wallet addresses never count.

number

Only fire for tokens at least this many hours old, measured from the first tracked buy.

number

Only fire for tokens at most this many hours old.

If you send threshold fields at the top level without a kol or smart block, they are treated as the KOL block, so older integrations keep working. The subscribe reply echoes back the rules it parsed and any warnings, for example an unknown field, or a win rate filter you asked for while win rate data is temporarily unavailable.

Unsubscribe and other operations

To stop, send op unsubscribe with the same chain and token. This removes the subscription for that token regardless of which types you configured.

Unsubscribe

{
  "op": "unsubscribe",
  "stream": "signal",
  "blockchain": "solana",
  "token": "*"
}

To see your active subscriptions, send op subscriptions. To check the connection is alive, send op ping and you get a pong back.

List your subscriptions

{ "op": "subscriptions", "stream": "signal" }

Event

Each fired signal delivers a signal event.

string

signal.

object

Show data

string

entry or exit.

string

The chain.

array

The wallet types the signal covers.

string

The token mint or contract address.

object

Token block with mint, symbol, name, supply, decimals, and live market_cap, market_cap_usd, market_cap_currency, pool, on_curve and bonding_curve_progress. Delivered on every chain. bonding_curve_progress is Solana only and null elsewhere.

object

What fired, with fired_on, exit_type and exit_remaining for exits, and the per type thresholds that were configured.

object

Show cluster

integer

Total qualifying wallets across all configured types.

number

Total invested by the cluster in native currency.

number

Total invested in USD.

number

Sum of the cluster wallet unrealized PnL in the chain native currency. Despite the field name this carries BNB or ETH on those chains, read currency to label it.

number

Cluster unrealized PnL in USD.

number

Portfolio weighted unrealized PnL percentage.

string

Native currency. SOL, BNB or ETH. Each configured type also appears here as an object with qualifying, sold and holding counts.

object

The trade that fired the signal, with wallet, action, value, signature and created_at.

array

Show wallet in the cluster

string

Wallet address.

string

kol or smart.

number

Lifetime win rate, or null.

object

Wallet profile.

number

Invested in native currency.

number

Invested in USD.

number

Largest single buy.

integer

Number of buys.

integer

Number of sells.

number

Total sold value.

boolean

Whether the wallet has sold.

number

Percent of peak holding still held, or null.

string

Timestamp of the first buy.

number

Market cap in the chain native currency when the wallet first bought, frozen. Delivered on every chain.

number

Entry market cap in USD.

number

Unrealized PnL on the held bag in the chain native currency.

number

Unrealized PnL percentage.

Market cap, entry_market_cap and unrealized PnL are only filled while a current market cap for the token is known. If a token has not traded since the stream started, these stay null until its first price arrives.

{
  "success": true,
  "channel": "signal.solana",
  "event": "signal",
  "data": {
    "signal_kind": "entry",
    "blockchain": "solana",
    "wallet_types": ["kol"],
    "mint": "3Pkrq4MmLvDXyn1fa3sz5MekKRkZkc1iLDcz5AzWpump",
    "token": {
      "mint": "3Pkrq4MmLvDXyn1fa3sz5MekKRkZkc1iLDcz5AzWpump",
      "symbol": "invisibull",
      "name": "invisibull",
      "supply": 1000000000,
      "decimals": 6,
      "market_cap": 40.08,
      "market_cap_usd": 3301.2,
      "market_cap_currency": "SOL",
      "pool": "pump",
      "on_curve": true,
      "bonding_curve_progress": 42.5
    },
    "threshold": {
      "fired_on": "entry",
      "exit_type": null,
      "exit_remaining": null,
      "currency": "SOL",
      "kol": { "min_buy": 0.5, "entry_at": [3, 5], "exit_at": [1], "max_wallet_buy": null }
    },
    "cluster": {
      "kol": { "qualifying": 5, "sold": 0, "holding": 5 },
      "qualifying_total": 5,
      "total_invested": 12.4,
      "total_invested_usd": 1021.4,
      "unrealized_pnl_sol": -0.4,
      "unrealized_pnl_usd": -32.9,
      "unrealized_pnl_pct": -3.2,
      "currency": "SOL"
    },
    "trigger": {
      "wallet": "7j7AA3HZR2zEjwAQEKPFh2qucLY4fqZpB9iodf39w8xW",
      "action": "buy",
      "value": 3.2,
      "signature": "5xr8abc...",
      "created_at": "2026-07-06T10:52:00Z"
    },
    "wallets": [
      {
        "wallet": "7j7AA3HZR2zEjwAQEKPFh2qucLY4fqZpB9iodf39w8xW",
        "wallet_type": "kol",
        "win_rate": 61.34,
        "profile": {
          "name": "Maze",
          "image_url": "https://cabalspy.xyz/images/7j7AA3HZR2zEjwAQEKPFh2qucLY4fqZpB9iodf39w8xW.png",
          "twitter": "https://x.com/MazeCCC",
          "telegram": "",
          "blockchain": "solana",
          "currency": "SOL",
          "type": "kol"
        },
        "invested": 3.2,
        "invested_usd": 263.6,
        "max_single_buy": 3.2,
        "buy_txn": 1,
        "sell_txn": 0,
        "sold_value": 0.0,
        "sold": false,
        "bag_pct": 100.0,
        "first_buy_at": "2026-07-06T10:20:00Z",
        "entry_market_cap": 44.6,
        "entry_market_cap_usd": 3673.2,
        "unrealized_pnl_sol": -0.1,
        "unrealized_pnl_pct": -3.2
      }
    ]
  },
  "meta": {
    "request_id": "req_5162c7cf7f87",
    "version": "2.0.0",
    "timestamp": "2026-07-06T11:01:57Z"
  }
}

{
  "success": true,
  "channel": "signal.bnb",
  "event": "signal",
  "data": {
    "signal_kind": "entry",
    "blockchain": "bnb",
    "wallet_types": ["kol"],
    "mint": "0x1a2b3c4d5e6f7890abcdef1234567890abcdef12",
    "token": {
      "mint": "0x1a2b3c4d5e6f7890abcdef1234567890abcdef12",
      "symbol": "FOUR",
      "name": "Four Token",
      "supply": 1000000000,
      "decimals": 18,
      "market_cap": 1250.5,
      "market_cap_usd": 750300.0,
      "market_cap_currency": "BNB",
      "pool": "0xpool1234567890abcdef1234567890abcdef1234",
      "on_curve": true,
      "bonding_curve_progress": null
    },
    "threshold": {
      "fired_on": "entry",
      "exit_type": null,
      "exit_remaining": null,
      "currency": "BNB",
      "kol": { "min_buy": 0.2, "entry_at": [3], "exit_at": [1], "max_wallet_buy": null }
    },
    "cluster": {
      "kol": { "qualifying": 3, "sold": 0, "holding": 3 },
      "qualifying_total": 3,
      "total_invested": 2.1,
      "total_invested_usd": 1260.0,
      "unrealized_pnl_sol": 0.35,
      "unrealized_pnl_usd": 210.0,
      "unrealized_pnl_pct": 16.6,
      "currency": "BNB"
    },
    "trigger": {
      "wallet": "0x7a16ff8270133f063aab6c9977183d9e72835428",
      "action": "buy",
      "value": 0.5,
      "signature": "0xabc123...",
      "created_at": "2026-07-17T09:12:04Z"
    },
    "wallets": [
      {
        "wallet": "0x7a16ff8270133f063aab6c9977183d9e72835428",
        "wallet_type": "kol",
        "win_rate": 58.2,
        "profile": {
          "name": "BNB Whale",
          "image_url": null,
          "twitter": "",
          "telegram": "",
          "blockchain": "bnb",
          "currency": "BNB",
          "type": "kol"
        },
        "invested": 0.5,
        "invested_usd": 300.0,
        "max_single_buy": 0.5,
        "buy_txn": 1,
        "sell_txn": 0,
        "sold_value": 0.0,
        "sold": false,
        "bag_pct": 100.0,
        "first_buy_at": "2026-07-17T09:12:04Z",
        "entry_market_cap": 1070.0,
        "entry_market_cap_usd": 642000.0,
        "unrealized_pnl_sol": 0.084,
        "unrealized_pnl_pct": 16.8
      }
    ]
  },
  "meta": {
    "request_id": "req_9a1b2c3d4e5f",
    "version": "2.0.0",
    "timestamp": "2026-07-17T09:12:05Z"
  }
}

Billing

Signals are billed more heavily than a single event because each one aggregates a whole cluster. Every delivered signal deducts a fixed number of credits and is logged.

Heartbeat

The server sends WebSocket pings and expects pong, which standard clients answer automatically. You can also send op ping at any time.

Introduction

Trades & Activity

Signals & Detection

Holdings & Position

Signal Stream

Endpoint

Authentication

Chains and wallet types

Unsubscribe and other operations

Event

Billing

Heartbeat

​Endpoint

​Authentication

​Chains and wallet types

​Subscribe

​Unsubscribe and other operations

​Event

​Billing

​Heartbeat

Endpoint

Authentication

Chains and wallet types

Subscribe

Unsubscribe and other operations

Event

Billing

Heartbeat