KOL Position Updates (SOLANA)

Get updates about KOL transcations from any Token

Get enriched position updates for Solana token holdings (bag %, supply %, SOL tracking, fallback logic) from tracked KOLs. The POSITION_UPDATE feed broadcasts every relevant transaction (buy/sell) after enriching it with current token balance, peak position and bag percentage. How to UseConnect to WebSocket: javascript

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

Alternative (using Authorization header): javascript

const ws = new WebSocket('wss://kolstream.cabalspy.xyz', {
  headers: { 'Authorization': 'YOUR_API_KEY_HERE' }
});

Handle Connection: javascript

ws.onopen = () => {
  console.log('Connected to Position Update WebSocket');
};

ws.onclose = () => {
  console.log('Disconnected, reconnecting in 5s...');
  setTimeout(() => {
    // Reconnect logic here (or use a reconnecting library)
  }, 5000);
};

ws.onerror = (error) => {
  console.error('WebSocket error:', error);
};

Receive & Process Messages: No subscription needed – the server broadcasts to all authenticated clients automatically. javascript

ws.onmessage = (event) => {
  const message = JSON.parse(event.data);
  
  if (message.type === 'position_update') {
    console.log('Position update:', message);
    // Example: update dashboard, send alert, calculate pnl, etc.
  } else if (message.error) {
    console.error('Error from server:', message.error);
  }
};

Information Received Example message: json

{
  "type": "position_update",
  "signature": "5fX9kJ...zABC123",
  "wallet": "9WzDXmQ...8kQA",
  "mint": "pumpABC...xyz123",
  "symbol": "MOON",
  "transaction_type": "buy",
  "sol_value": 0.85,
  "slot": 289145678,
  "held": 12450000,
  "peak": 15000000,
  "supply_pct": 1.2450,
  "bag_pct": 83.00,
  "sol_value_peak": 2.80,
  "sol_value_current": 2.15,
  "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,
  "retry_success": false,
  "wallet_name": "Whale #42",
  "wallet_image": "https://...",
  "telegram": null,
  "twitter": "https://x.com/Whale42",
  "timestamp": "2026-02-24T14:37:22.123Z"
}

Important fields and explanation:

Field	Type	What it actually means / why it's useful
type	string	Always "position_update" – easy way to filter in onmessage
signature	string	The Solana tx signature – click it on Solscan/Explorer to see the raw transaction
wallet	string	The public key of the wallet that did the trade (the KOL/sniper/trader you're tracking)
mint	string	Token mint address – which coin this update is about
symbol	string	Token ticker/symbol (often short like "MOON", "DOG", "?" if unknown)
transaction_type	string	"buy", "sell", or "other" – tells you the direction of this particular tx
sol_value	number	SOL value of this single transaction (≈ SOL spent on buy / SOL received on sell)
slot	number	Solana slot number – roughly = block time, good for ordering if timestamps are delayed
held	number	Current token balance right now of this mint
peak	number	All-time highest token balance this wallet ever had for this mint
bag_pct	number	how much of their max position is still left (0–100%)
supply_pct	number	Current % of the tokens this wallet hold of the total supply of this mint.
sol_value_peak	number	Total SOL this wallet has ever put into buys for this mint (cumulative)
sol_value_current	number	Remaining unrealized SOL left in this mint
prev_supply_pct	number	Token supply % held before this transaction
prev_bag_pct	number	Bag % before this transaction
delta_supply_pct	number	Change in supply % caused by this tx
delta_bag_pct	number	Change in bag % caused by this tx
delta_held	number	Change in token amount caused by this tx
used_fallback	boolean	"false"/"true"
retry_success	boolean	"false"/"true"
wallet_name	string?	Human-readable name (e.g. "Ansem", "Whale #17")
wallet_image	string?	URL to profile picture/avatar if available
telegram	string?	Telegram link/handle if known
twitter	string?	X/Twitter profile URL if known
timestamp	string	ISO timestamp when we processed and broadcast this update (not the tx timestamp!)

Errors you might receive: json

{ "error": "Invalid or missing API key" }

NOTES: No subscribe/unsubscribe – everything is pushed automatically to connected clients with valid keys. Replace YOUR_API_KEY_HERE with a real key from your CabalSpy apidashboard account. Without a valid key the connection is rejected immediately.