KOL Position Updates

Get real-time position updates for tracked KOL wallets across any Solana token.

The POSITION_UPDATE feed broadcasts every buy/sell transaction enriched with position data: current holdings, bag percentage, supply percentage and SOL tracking.

---

Connection

javascript

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

Alternative — Authorization header:

javascript

const ws = new WebSocket("wss://kolstream.cabalspy.xyz");
// After connection:
// Send auth via header: Authorization: Bearer YOUR_API_KEY

Without a valid API key the connection is rejected immediately.

---

Subscriptions

You must subscribe before receiving any events.

Subscribe to a specific token

javascript

ws.send(JSON.stringify({
  type:  "subscribe",
  token: "DezXAZ8z7PnrnRJjz3wXBoRgixCa6xjnB7YaB1pPB263"
}));

Subscribe to all tokens

javascript

ws.send(JSON.stringify({
  type:  "subscribe",
  token: "*"
}));

Unsubscribe

javascript

ws.send(JSON.stringify({
  type:  "unsubscribe",
  token: "DezXAZ8z7PnrnRJjz3wXBoRgixCa6xjnB7YaB1pPB263"
}));

List active subscriptions

javascript

ws.send(JSON.stringify({ type: "subscriptions" }));

---

Connection Flow

javascript

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

ws.onopen = () => {
  ws.send(JSON.stringify({ type: "subscribe", token: "*" }));
};

ws.onmessage = (event) => {
  const message = JSON.parse(event.data);

  switch (message.type) {
    case "connected":
      console.log("Connected:", message.message);
      break;
    case "subscribed":
      console.log("Subscribed to:", message.token);
      break;
    case "unsubscribed":
      console.log("Unsubscribed from:", message.token);
      break;
    case "position_update":
      console.log("New trade:", message);
      break;
    case "error":
      console.error("Error:", message.message);
      break;
  }
};

---

System Messages

type	When	Fields
connected	On successful connect	message, docs
subscribed	After subscribe	token, subscriptions, message
unsubscribed	After unsubscribe	token, subscriptions, message
subscriptions	After requesting list	subscriptions, count
error	On invalid message or auth	message

---

Example Message — position_update

json

{
  "type": "position_update",
  "signature": "5fX9kJ...zABC123",
  "slot": 289145678,
  "timestamp": 1740404242,
  "blockchain": "solana",
  "action": "buy",
  "transaction_type": "buy",

  "wallet": "9WzDXmQ...8kQA",
  "wallet_name": "Whale #42",
  "wallet_image": "https://cabalspy.xyz/...",
  "telegram": null,
  "twitter": "https://x.com/Whale42",
  "wallet_data": {
    "name": "Whale #42",
    "wallet_address": "9WzDXmQ...8kQA",
    "telegram": null,
    "twitter": "https://x.com/Whale42",
    "image_url": "https://cabalspy.xyz/..."
  },

  "sol_value": 0.85,
  "sol_value_raw": 850000000,
  "sol_value_usd": 127.50,
  "sol_price_usd": 150.00,
  "sol_value_peak": 2.80,
  "sol_value_current": 2.15,

  "fee": 5000,
  "fee_sol": 0.000005,
  "fee_payer": "9WzDXmQ...8kQA",

  "mint": "pumpABC...xyz123",
  "symbol": "MOON",
  "token_name": "Moon Token",
  "token_logo": "https://...",
  "token_decimals": 6,
  "token_supply": 1000000000,
  "token_amount": 12450000,

  "held": 12450000,
  "peak": 15000000,
  "supply_pct": 1.2450,
  "bag_pct": 83.00,
  "prev_supply_pct": 0.0000,
  "prev_bag_pct": 100.00,
  "delta_supply_pct": 1.2450,
  "delta_bag_pct": -17.00,
  "delta_held": 12450000,
  "used_fallback": false
}

---

Field Reference

Transaction

Field	Type	Description
type	string	Always "position_update"
signature	string	Solana transaction signature
slot	number	Solana slot number
timestamp	number	Unix timestamp
blockchain	string	Always "solana"
action	string	"buy" or "sell"
transaction_type	string	Same as action — kept for compatibility

Wallet

Field	Type	Description
wallet	string	Public key of the trading wallet
wallet_name	string?	Human-readable name e.g. "Ansem"
wallet_image	string?	Profile picture URL
telegram	string?	Telegram link if available
twitter	string?	Twitter/X profile URL if available
wallet_data	object	Full wallet object containing all fields above

SOL

Field	Type	Description
sol_value	number	SOL amount of this transaction
sol_value_raw	number	SOL amount in Lamports
sol_value_usd	number	USD value of this transaction
sol_price_usd	number	SOL price in USD at time of broadcast
sol_value_peak	number	Total SOL ever spent buying this token by this wallet
sol_value_current	number	Remaining unrealized SOL value in this position

Fees

Field	Type	Description
fee	number	Transaction fee in Lamports
fee_sol	number	Transaction fee in SOL
fee_payer	string	Wallet that paid the fee

Token

Field	Type	Description
mint	string	Token mint address
symbol	string	Token ticker e.g. "BONK"
token_name	string?	Full token name
token_logo	string?	Token logo URL
token_decimals	number	Token decimal places
token_supply	number	Total on-chain token supply
token_amount	number	Amount of tokens traded in this specific transaction

Position

Field	Type	Description
held	number	Current token balance of this wallet for this mint
peak	number	All-time highest token balance this wallet held
bag_pct	number	How much of the peak position is still held (0–100%)
supply_pct	number	Percentage of total supply currently held
prev_supply_pct	number	Supply % before this transaction
prev_bag_pct	number	Bag % before this transaction
delta_supply_pct	number	Change in supply % from this transaction
delta_bag_pct	number	Change in bag % from this transaction
delta_held	number	Change in token amount from this transaction
used_fallback	boolean	true if supply was estimated (1B fallback) instead of on-chain value

---

Errors

json

{ "type": "error", "message": "Invalid or missing API key" }
{ "type": "error", "message": "Unknown type: xyz. Valid: subscribe, unsubscribe, subscriptions" }
{ "type": "error", "message": "Invalid JSON message" }

---

Notes

• You must subscribe before receiving any events. Without a subscription nothing is received.

• Use "token": "*" to receive all events across all tracked tokens.

• Multiple tokens can be subscribed simultaneously — send one subscribe message per token.

• token_supply falls back to 1,000,000,000 if the on-chain value is unavailable. Check used_fallback: true to detect this.

• bag_pct is calculated as held / peak * 100. A value of 0% means the position was fully closed.

• token_amount is the amount traded in this specific transaction. held is the cumulative position.

• sol_value_current tracks unrealized SOL based on buys minus sells — does not reflect real-time price.