Transactions WebSocket Stream - Live Trades and Positions

The core realtime stream. Every time a tracked wallet buys or sells, you receive a position_update event with the trade and the wallet running position on that token, including held amount, bag percentage and supply percentage. All CabalSpy streams share one WebSocket endpoint. You open a single connection, authenticate, then subscribe to as many channels as you like. This page covers the transactions channel.

Endpoint

Connect to wss://stream.cabalspy.xyz. Pass your API key either as a query parameter or as a Bearer header.

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);
  if (msg.event === "position_update") {
    const d = msg.data;
    console.log(d.profile.name, d.transaction.action, d.token.symbol, d.position.bag_pct);
  }
};

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)
    if msg.get("event") == "position_update":
        d = msg["data"]
        print(d["profile"]["name"], d["transaction"]["action"], 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 one of two ways when opening the connection. As a query parameter, wss://stream.cabalspy.xyz?apiKey=YOUR_KEY. Or as a header, Authorization: Bearer YOUR_KEY. A connection without a valid key is closed immediately with code 1008. On connect you receive a welcome message listing the available streams and example subscriptions. After that you drive everything with subscribe messages.

Chains and wallet types

Each chain tracks a different set of wallet categories, and reports values in its own native currency.

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

Asking for a wallet type a chain does not track is rejected with an error naming the types it does track. On EVM chains, contract addresses are matched case-insensitively. To start receiving trades, send a subscribe message after the connection opens. You choose a chain, a wallet type, and optionally one token to narrow to.

Subscribe to all KOL trades on Solana

{
  "op": "subscribe",
  "stream": "tx",
  "blockchain": "solana",
  "type": "kol",
  "token": "*"
}

The token field decides how much you get. Use the value ”*” to receive trades on every token, or a token mint address (Solana) or contract address (BNB, Base, ETH, Robinhood) to receive only trades on that one token.

Subscribe to one token only

{
  "op": "subscribe",
  "stream": "tx",
  "blockchain": "base",
  "type": "smart",
  "token": "0xYourTokenContractAddress"
}

string

required

The operation. Use subscribe to start.

string

required

Set to tx for this stream.

string

required

Chain. One of solana, bnb, base, eth, rh.

string

required

Wallet category. See the table above. Solana has kol, smart, whale. BNB, Base and Robinhood have kol, smart. ETH has kol.

string

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

Unsubscribe and other operations

To stop a subscription, send the same fields with op unsubscribe.

Unsubscribe

{
  "op": "unsubscribe",
  "stream": "tx",
  "blockchain": "solana",
  "type": "kol",
  "token": "*"
}

To see what you are currently subscribed to, send op subscriptions. To check the connection is alive, send op ping and you get a pong back.

List your subscriptions

{ "op": "subscriptions" }

Event

Each matching trade delivers a position_update event.

boolean

Always true for stream events.

string

The channel that produced the event, for example tx.solana.kol.

string

position_update.

object

Show data

string

The trading wallet address.

object

Wallet profile (name, image_url, twitter, telegram, blockchain, currency, type, active_hours).

object

Show transaction

string

Transaction signature on Solana, transaction hash on EVM chains.

integer

Slot of the transaction on Solana, block number on EVM chains, or null.

string

buy or sell.

string

Same as action.

string

Timestamp of the trade, or null.

number

Raw fee as reported by the source.

number

Fee in native currency, or null.

string

Fee payer address.

object

Show token

string

Token mint on Solana, contract address on EVM chains.

string

Token symbol.

string

Token name.

integer

Token decimals, or null.

number

Total supply.

string

Token logo URL, or null.

object

Show value

string

Native currency of the chain. SOL, BNB or ETH.

number

Trade value in native currency.

number

Trade value in USD.

number

Native currency price in USD used for the conversion.

number

Peak invested value on this position (native).

number

Current invested value on this position (native).

object

Show position

number

Tokens moved in this trade.

number

Tokens held after this trade.

number

Peak tokens held.

number

Percent of supply held after this trade.

number

Percent of peak holding still held.

number

Percent of supply held before this trade.

number

Bag percent before this trade.

number

Change in supply percent from this trade.

number

Change in bag percent from this trade.

integer

Change in tokens held from this trade.

boolean

True when the bag percent was derived from value rather than token counts.

{
  "success": true,
  "channel": "tx.solana.kol",
  "event": "position_update",
  "data": {
    "wallet": "7j7AA3HZR2zEjwAQEKPFh2qucLY4fqZpB9iodf39w8xW",
    "profile": {
      "name": "Maze",
      "image_url": "https://cabalspy.xyz/images/7j7AA3HZR2zEjwAQEKPFh2qucLY4fqZpB9iodf39w8xW.png",
      "twitter": "https://x.com/MazeCCC",
      "telegram": "",
      "blockchain": "solana",
      "currency": "SOL",
      "type": "kol",
      "active_hours": [13, 14, 15]
    },
    "transaction": {
      "signature": "5xr8abc...",
      "slot": 301948220,
      "action": "buy",
      "transaction_type": "buy",
      "created_at": "2026-07-04T16:25:34Z",
      "fee": 5000,
      "fee_native": 0.000005,
      "fee_payer": "7j7AA3HZR2zEjwAQEKPFh2qucLY4fqZpB9iodf39w8xW"
    },
    "token": {
      "mint": "3Pkrq4MmLvDXyn1fa3sz5MekKRkZkc1iLDcz5AzWpump",
      "symbol": "invisibull",
      "name": "invisibull",
      "decimals": 6,
      "supply": 1000000000,
      "logo": null
    },
    "value": {
      "currency": "SOL",
      "amount": 1.66,
      "amount_usd": 137.44,
      "price_usd": 82.36,
      "peak": 1.66,
      "current": 1.66
    },
    "position": {
      "token_amount": 22113972.03,
      "held": 22113972.03,
      "peak": 22113972.03,
      "supply_pct": 2.2114,
      "bag_pct": 100.0,
      "prev_supply_pct": 0.0,
      "prev_bag_pct": 0.0,
      "delta_supply_pct": 2.2114,
      "delta_bag_pct": 100.0,
      "delta_held": 22113972,
      "used_fallback": false
    }
  },
  "meta": {
    "request_id": "req_5162c7cf7f87",
    "version": "2.0.0",
    "timestamp": "2026-07-06T11:01:57Z"
  }
}

Billing

Each delivered event counts against your plan, the same way a request does. A subscribe to a busy wildcard channel can produce many events, so scope your token filter when you can.

Heartbeat

The server sends WebSocket pings on an interval and expects your client to answer with pong, which browsers and standard clients do automatically. A connection that stops answering is closed. You can also send op ping at any time to check liveness.

Introduction

Trades & Activity

Signals & Detection

Holdings & Position

Transactions 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