Holder WebSocket Stream - Live Token Holders and PnL

{
  "success": true,
  "channel": "holder.solana",
  "event": "holder_update",
  "data": {
    "trigger": "transaction",
    "blockchain": "solana",
    "mint": "3Pkrq4MmLvDXyn1fa3sz5MekKRkZkc1iLDcz5AzWpump",
    "token": {
      "mint": "3Pkrq4MmLvDXyn1fa3sz5MekKRkZkc1iLDcz5AzWpump",
      "blockchain": "solana",
      "symbol": "invisibull",
      "name": "invisibull",
      "supply": 1000000000,
      "decimals": 6,
      "market_cap": 40.08,
      "market_cap_usd": 3301.2,
      "market_cap_currency": "SOL",
      "price": 4.008e-8,
      "price_usd": 3.3e-6,
      "sol_price_usd": 82.36,
      "native_price_usd": 82.36,
      "pool": "pump",
      "on_curve": true,
      "bonding_curve_progress": 42.5
    },
    "transaction": {
      "signature": "5xr8abc...",
      "slot": 301948220,
      "action": "buy",
      "transaction_type": "buy",
      "created_at": "2026-07-04T16:25:34Z",
      "token_amount": 22113972.03,
      "value": { "currency": "SOL", "amount": 1.66, "amount_usd": 137.44 }
    },
    "holder": {
      "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"
      },
      "position": {
        "held": 22113972.03,
        "peak": 22113972.03,
        "bought_tokens": 22113972.03,
        "sold_tokens": 0.0,
        "bag_pct": 100.0,
        "supply_pct": 2.2114,
        "remaining_sol": 0.886537,
        "remaining_usd": 73.02,
        "invested": 1.66,
        "invested_usd": 137.44,
        "max_single_buy": 1.66,
        "buy_txn": 1,
        "sell_txn": 0,
        "sold_value": 0.0,
        "sold_value_usd": 0.0,
        "sold": false,
        "realized_pnl_sol": -1.66,
        "realized_pnl_usd": -137.44,
        "entry_market_cap": 44.6,
        "entry_market_cap_usd": 3673.2,
        "unrealized_pnl_sol": -0.099817,
        "unrealized_pnl_usd": -8.22,
        "unrealized_pnl_pct": -10.12,
        "first_buy_at": "2026-07-04T16:25:34Z",
        "last_activity_at": "2026-07-04T16:40:10Z"
      }
    }
  },
  "meta": {
    "request_id": "req_5162c7cf7f87",
    "version": "2.0.0",
    "timestamp": "2026-07-06T11:01:57Z"
  }
}

{
  "success": true,
  "channel": "holder.bnb",
  "event": "holder_update",
  "data": {
    "trigger": "transaction",
    "blockchain": "bnb",
    "mint": "0x1a2b3c4d5e6f7890abcdef1234567890abcdef12",
    "token": {
      "mint": "0x1a2b3c4d5e6f7890abcdef1234567890abcdef12",
      "blockchain": "bnb",
      "symbol": "FOUR",
      "name": "Four Token",
      "supply": 1000000000,
      "decimals": 18,
      "market_cap": 1250.5,
      "market_cap_usd": 750300.0,
      "market_cap_currency": "BNB",
      "price": 0.00000125,
      "price_usd": 0.00075,
      "sol_price_usd": 600.0,
      "native_price_usd": 600.0,
      "pool": "0xpool1234567890abcdef1234567890abcdef1234",
      "on_curve": true,
      "bonding_curve_progress": null
    },
    "transaction": {
      "signature": "0xabc123...",
      "slot": 41255903,
      "action": "buy",
      "transaction_type": "buy",
      "created_at": "2026-07-17T09:12:04Z",
      "token_amount": 400000.0,
      "value": { "currency": "BNB", "amount": 0.5, "amount_usd": 300.0 }
    },
    "holder": {
      "wallet": "0x7a16ff8270133f063aab6c9977183d9e72835428",
      "wallet_type": "kol",
      "win_rate": 58.2,
      "profile": {
        "name": "BNB Whale",
        "image_url": null,
        "twitter": "",
        "telegram": "",
        "blockchain": "bnb",
        "currency": "BNB",
        "type": "kol"
      },
      "position": {
        "held": 400000.0,
        "peak": 400000.0,
        "bought_tokens": 400000.0,
        "sold_tokens": 0.0,
        "bag_pct": 100.0,
        "supply_pct": 0.04,
        "remaining_sol": 0.5,
        "remaining_usd": 300.0,
        "invested": 0.5,
        "invested_usd": 300.0,
        "max_single_buy": 0.5,
        "buy_txn": 1,
        "sell_txn": 0,
        "sold_value": 0.0,
        "sold_value_usd": 0.0,
        "sold": false,
        "realized_pnl_sol": -0.5,
        "realized_pnl_usd": -300.0,
        "entry_market_cap": 1250.5,
        "entry_market_cap_usd": 750300.0,
        "unrealized_pnl_sol": 0.0,
        "unrealized_pnl_usd": 0.0,
        "unrealized_pnl_pct": 0.0,
        "first_buy_at": "2026-07-17T09:12:04Z",
        "last_activity_at": "2026-07-17T09:12:04Z"
      }
    }
  },
  "meta": {
    "request_id": "req_9a1b2c3d4e5f",
    "version": "2.0.0",
    "timestamp": "2026-07-17T09:12:05Z"
  }
}

The live holder table for a token. On subscribe you get a snapshot of every tracked holder with a full position, then live updates as they trade and as the market cap moves. Positions carry bag percentage, unrealized PnL, remaining value and the market cap at entry. When you subscribe to a specific token, CabalSpy first seeds its history from the database so the initial snapshot is complete, then streams live. This stream runs on Solana, BNB, Base, Ethereum and Robinhood. The event shape is identical on every chain, only the native currency changes.

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: "holder", blockchain: "solana",
    token: "3Pkrq4MmLvDXyn1fa3sz5MekKRkZkc1iLDcz5AzWpump",
    wallet_types: ["kol", "smart", "whale"], mode: "full",
  }));
};

ws.onmessage = (e) => {
  const msg = JSON.parse(e.data);
  if (msg.event === "init") {
    console.log("holders", msg.data.holder_count);
  } else if (msg.event === "holder_update") {
    const h = msg.data.holder;
    console.log(h.profile.name, h.position.bag_pct, h.position.unrealized_pnl_usd);
  }
};

import json, websocket

def on_open(ws):
    ws.send(json.dumps({
        "op": "subscribe", "stream": "holder", "blockchain": "solana",
        "token": "3Pkrq4MmLvDXyn1fa3sz5MekKRkZkc1iLDcz5AzWpump",
        "wallet_types": ["kol", "smart", "whale"], "mode": "full",
    }))

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()

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

Each chain tracks a different set of holder types, 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

Leaving wallet_types out subscribes you to every type that chain supports. Asking for a type a chain does not track is rejected with an error naming the types it does track, so ETH accepts only kol. Leaving blockchain out defaults to solana, which keeps existing integrations working unchanged. On EVM chains, contract and wallet addresses are matched case-insensitively and are returned lowercased. To start receiving data, send a subscribe message after the connection opens. At a minimum you choose a token to watch and which holder types you care about.

Subscribe to one token on Solana

{
  "op": "subscribe",
  "stream": "holder",
  "blockchain": "solana",
  "token": "3Pkrq4MmLvDXyn1fa3sz5MekKRkZkc1iLDcz5AzWpump",
  "wallet_types": ["kol", "smart", "whale"],
  "mode": "full"
}

Subscribe to one token on BNB

{
  "op": "subscribe",
  "stream": "holder",
  "blockchain": "bnb",
  "token": "0xYourTokenContractAddress",
  "wallet_types": ["kol", "smart"],
  "mode": "full"
}

The token field decides what you watch. Use a token mint address (Solana) or contract address (EVM) to follow one token, or the value ”*” to follow every tracked token at once. Following one token also gives you an initial snapshot of its current holders, ”*” does not.

Follow every token

{
  "op": "subscribe",
  "stream": "holder",
  "blockchain": "base",
  "token": "*",
  "wallet_types": ["kol"]
}

string

required

The operation. Use subscribe to start.

string

required

Set to holder for this stream.

string

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

string

required

Which token to watch. Either a token mint or contract address for one token, or ”*” for all tracked tokens. A single address also returns a starting snapshot of its holders.

array

Which holder types to include. See the table above. Defaults to every type the chain supports.

string

default:"full"

How much you want to receive. See the modes below.

integer

Optional. Only used with mode full. See the modes below.

Choosing a mode

The mode decides whether you also receive live price driven updates, not just trades. This is the main control over how many messages, and how many credits, you use.

mode	What you receive	Can you set mc_interval
full	Trades plus live position updates every time the market cap moves. This is the default.	Yes
events	Only real trade events. No market cap updates, so unrealized PnL and remaining value do not tick between trades. Cheapest option.	No, it is ignored

With mode full you can slow down the market cap updates to save credits. Set mc_interval to a number of seconds from 1 to 30, and you get at most one price update per token in that window. Leave mc_interval out to get every update live.

Full, but at most one price update every 5 seconds

{
  "op": "subscribe",
  "stream": "holder",
  "blockchain": "solana",
  "token": "3Pkrq4MmLvDXyn1fa3sz5MekKRkZkc1iLDcz5AzWpump",
  "mode": "full",
  "mc_interval": 5
}

Events only, no price updates at all

{
  "op": "subscribe",
  "stream": "holder",
  "blockchain": "solana",
  "token": "3Pkrq4MmLvDXyn1fa3sz5MekKRkZkc1iLDcz5AzWpump",
  "mode": "events"
}

Setting mc_interval together with mode events does nothing, because events never sends price updates in the first place.

Unsubscribe and other operations

To stop receiving a token, send the same chain and token with op unsubscribe.

Unsubscribe

{
  "op": "unsubscribe",
  "stream": "holder",
  "blockchain": "solana",
  "token": "3Pkrq4MmLvDXyn1fa3sz5MekKRkZkc1iLDcz5AzWpump"
}

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", "stream": "holder" }

Events

The stream emits three event types. init on subscribe, holder_update on each trade, and position_update when the market cap moves (subject to mode and mc_interval).

string

init, holder_update or position_update.

object

Show data

string

The chain. solana, bnb, base, eth or rh.

string

The token mint or contract address.

object

Token block. See the token fields below.

object

Present on holder_update. The single holder that traded, with profile and position. See the position fields below.

array

Present on init and position_update. The list of holders, each with wallet, wallet_type, win_rate, profile and position.

integer

Present on init and position_update. Number of holders in the list.

object

Present on holder_update. The trade that triggered the update, with signature, slot, action, created_at, token_amount and a value object.

token

string

Token mint or contract address.

string

The chain this token lives on.

string

Token symbol.

string

Token name.

number

Total supply, or null.

integer

Token decimals, or null.

number

Market cap in the chain native currency, or null when no price is known yet.

number

Market cap in USD.

string

The native currency the market cap is denominated in. SOL, BNB or ETH.

number

Token price in the native currency.

number

Token price in USD.

number

Price of the chain native currency in USD, used for every conversion in this payload.

number

Same value as native_price_usd. Kept for backwards compatibility, despite the name it carries BNB or ETH on those chains. Prefer native_price_usd.

string

Pool or bonding curve address, or null.

boolean

True while the token still trades on a bonding curve, false once it has migrated to a regular AMM. Null when the launchpad is not recognised. Bonding curves exist on every chain, for example pump.fun on Solana, four.meme on BNB and moonshot on Base.

number

Bonding curve completion percentage. Solana only, null on EVM chains.

position

Every holder carries a position with these fields. The fields ending in _sol are named for historical reasons and carry the chain native currency, so BNB on BNB Chain and ETH on Base, Ethereum and Robinhood. Use market_cap_currency from the token block to label them.

number

Tokens currently held.

number

Peak tokens held.

number

Total tokens bought.

number

Total tokens sold.

number

Percent of peak holding still held.

number

Percent of supply held.

number

Current value of the remaining bag in the native currency.

number

Current value of the remaining bag in USD.

number

Total invested in the native currency.

number

Total invested in USD.

number

Largest single buy in the native currency.

integer

Number of buys.

integer

Number of sells.

number

Total sold value in the native currency.

number

Total sold value in USD.

boolean

Whether the wallet has sold any amount.

number

Realized PnL in the native currency, total sold minus total bought.

number

Realized PnL in USD.

number

Market cap in the native currency when the wallet first bought, frozen.

number

Entry market cap in USD, frozen.

number

Unrealized PnL on the remaining bag in the native currency.

number

Unrealized PnL in USD.

number

Unrealized PnL percentage.

string

Timestamp of the first buy.

string

ISO timestamp of the last activity.

unrealized_pnl and remaining 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": "holder.solana",
  "event": "holder_update",
  "data": {
    "trigger": "transaction",
    "blockchain": "solana",
    "mint": "3Pkrq4MmLvDXyn1fa3sz5MekKRkZkc1iLDcz5AzWpump",
    "token": {
      "mint": "3Pkrq4MmLvDXyn1fa3sz5MekKRkZkc1iLDcz5AzWpump",
      "blockchain": "solana",
      "symbol": "invisibull",
      "name": "invisibull",
      "supply": 1000000000,
      "decimals": 6,
      "market_cap": 40.08,
      "market_cap_usd": 3301.2,
      "market_cap_currency": "SOL",
      "price": 4.008e-8,
      "price_usd": 3.3e-6,
      "sol_price_usd": 82.36,
      "native_price_usd": 82.36,
      "pool": "pump",
      "on_curve": true,
      "bonding_curve_progress": 42.5
    },
    "transaction": {
      "signature": "5xr8abc...",
      "slot": 301948220,
      "action": "buy",
      "transaction_type": "buy",
      "created_at": "2026-07-04T16:25:34Z",
      "token_amount": 22113972.03,
      "value": { "currency": "SOL", "amount": 1.66, "amount_usd": 137.44 }
    },
    "holder": {
      "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"
      },
      "position": {
        "held": 22113972.03,
        "peak": 22113972.03,
        "bought_tokens": 22113972.03,
        "sold_tokens": 0.0,
        "bag_pct": 100.0,
        "supply_pct": 2.2114,
        "remaining_sol": 0.886537,
        "remaining_usd": 73.02,
        "invested": 1.66,
        "invested_usd": 137.44,
        "max_single_buy": 1.66,
        "buy_txn": 1,
        "sell_txn": 0,
        "sold_value": 0.0,
        "sold_value_usd": 0.0,
        "sold": false,
        "realized_pnl_sol": -1.66,
        "realized_pnl_usd": -137.44,
        "entry_market_cap": 44.6,
        "entry_market_cap_usd": 3673.2,
        "unrealized_pnl_sol": -0.099817,
        "unrealized_pnl_usd": -8.22,
        "unrealized_pnl_pct": -10.12,
        "first_buy_at": "2026-07-04T16:25:34Z",
        "last_activity_at": "2026-07-04T16:40:10Z"
      }
    }
  },
  "meta": {
    "request_id": "req_5162c7cf7f87",
    "version": "2.0.0",
    "timestamp": "2026-07-06T11:01:57Z"
  }
}

{
  "success": true,
  "channel": "holder.bnb",
  "event": "holder_update",
  "data": {
    "trigger": "transaction",
    "blockchain": "bnb",
    "mint": "0x1a2b3c4d5e6f7890abcdef1234567890abcdef12",
    "token": {
      "mint": "0x1a2b3c4d5e6f7890abcdef1234567890abcdef12",
      "blockchain": "bnb",
      "symbol": "FOUR",
      "name": "Four Token",
      "supply": 1000000000,
      "decimals": 18,
      "market_cap": 1250.5,
      "market_cap_usd": 750300.0,
      "market_cap_currency": "BNB",
      "price": 0.00000125,
      "price_usd": 0.00075,
      "sol_price_usd": 600.0,
      "native_price_usd": 600.0,
      "pool": "0xpool1234567890abcdef1234567890abcdef1234",
      "on_curve": true,
      "bonding_curve_progress": null
    },
    "transaction": {
      "signature": "0xabc123...",
      "slot": 41255903,
      "action": "buy",
      "transaction_type": "buy",
      "created_at": "2026-07-17T09:12:04Z",
      "token_amount": 400000.0,
      "value": { "currency": "BNB", "amount": 0.5, "amount_usd": 300.0 }
    },
    "holder": {
      "wallet": "0x7a16ff8270133f063aab6c9977183d9e72835428",
      "wallet_type": "kol",
      "win_rate": 58.2,
      "profile": {
        "name": "BNB Whale",
        "image_url": null,
        "twitter": "",
        "telegram": "",
        "blockchain": "bnb",
        "currency": "BNB",
        "type": "kol"
      },
      "position": {
        "held": 400000.0,
        "peak": 400000.0,
        "bought_tokens": 400000.0,
        "sold_tokens": 0.0,
        "bag_pct": 100.0,
        "supply_pct": 0.04,
        "remaining_sol": 0.5,
        "remaining_usd": 300.0,
        "invested": 0.5,
        "invested_usd": 300.0,
        "max_single_buy": 0.5,
        "buy_txn": 1,
        "sell_txn": 0,
        "sold_value": 0.0,
        "sold_value_usd": 0.0,
        "sold": false,
        "realized_pnl_sol": -0.5,
        "realized_pnl_usd": -300.0,
        "entry_market_cap": 1250.5,
        "entry_market_cap_usd": 750300.0,
        "unrealized_pnl_sol": 0.0,
        "unrealized_pnl_usd": 0.0,
        "unrealized_pnl_pct": 0.0,
        "first_buy_at": "2026-07-17T09:12:04Z",
        "last_activity_at": "2026-07-17T09:12:04Z"
      }
    }
  },
  "meta": {
    "request_id": "req_9a1b2c3d4e5f",
    "version": "2.0.0",
    "timestamp": "2026-07-17T09:12:05Z"
  }
}

Billing

Each delivered event counts against your plan. In mode full a busy token can produce frequent position_update events as the market cap moves, use mc_interval to throttle them or mode events to receive only trades.

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

Holder Stream

Endpoint

Authentication

Chains and wallet types

Choosing a mode

Unsubscribe and other operations

Events

token

position

Billing

Heartbeat

​Endpoint

​Authentication

​Chains and wallet types

​Subscribe

​Choosing a mode

​Unsubscribe and other operations

​Events

​token

​position

​Billing

​Heartbeat

Endpoint

Authentication

Chains and wallet types

Subscribe

Choosing a mode

Unsubscribe and other operations

Events

token

position

Billing

Heartbeat