Live Wallet Count Badge

Learn how to show a simple, powerful number next to any token, how many tracked KOL wallets are in it. It makes a great activity badge, a heat indicator, or a cheap trigger before you pull heavier data. This guide covers both ways to get it in TypeScript, with no CSS, so you can style the badge yourself.

Two numbers, two sources

Before any code, know which number you want, because the two sources answer slightly different questions.

Source	What it counts	Best for
REST /v1/transactions/count	How many trades tracked wallets made in a time window	Activity over the last hour, a quick on-demand number
WSS count stream	How many distinct KOL wallets hold the token right now	A live holder count badge that updates as wallets buy

If your badge says how many KOLs are in this token, you want the stream and its kol_count. If it says how active has this token been lately, you want the REST count.

Option A, a number on demand over REST

The REST counter is one call. You give it a chain, a wallet type and a time window built from seconds, minutes and hours, up to 24 hours back, and it returns just the count. No transactions, so it is fast and cheap.

Step 1, the fetch

src/count-rest.ts

const API_BASE = 'https://api.cabalspy.xyz/v1';

export async function fetchTradeCount(mint: string, hours = 1): Promise<number> {
  const params = new URLSearchParams({
    blockchain: 'solana',
    type: 'kol',
    hours: String(hours),
    mint,
    api_key: import.meta.env.VITE_CABALSPY_KEY as string,
  });
  const res = await fetch(`${API_BASE}/transactions/count?${params}`);
  const body = await res.json();
  if (!body.success) throw new Error(body.error?.message || 'count failed');
  return body.data.count as number;
}

Step 2, show it, and refresh on an interval

Since REST gives you a snapshot, poll it on a timer if you want it to stay current. A 30 second interval is plenty for an activity badge.

src/badge-rest.ts

import { fetchTradeCount } from './count-rest';

export function mountRestBadge(el: HTMLElement, mint: string): () => void {
  const update = async () => {
    try { el.textContent = `${await fetchTradeCount(mint)} trades (1h)`; }
    catch { el.textContent = '-'; }
  };
  update();
  const timer = setInterval(update, 30_000);
  return () => clearInterval(timer); // call to stop polling
}

That is the whole REST path. One call, one number, refreshed on a timer.

Option B, a live badge over WebSocket

The stream is better when you want the badge to update the moment a KOL buys. You subscribe once, and every time the KOL wallet count for a token changes, you get the new number pushed to you. Subscribe with the wildcard to watch every token, or pass a single mint to watch one. The stream always reports the KOL wallet count, it is not split by wallet type.

src/count-stream.ts

export interface CountUpdate { mint: string; kol_count: number; }

export function connectCountStream(
  onUpdate: (u: CountUpdate) => void,
  token: string = '*',
): () => void {
  const key = import.meta.env.VITE_CABALSPY_KEY as string;
  const ws = new WebSocket(`wss://stream.cabalspy.xyz?apiKey=${encodeURIComponent(key)}`);

  ws.onopen = () => {
    ws.send(JSON.stringify({ op: 'subscribe', stream: 'count', blockchain: 'solana', token }));
  };
  ws.onmessage = (e) => {
    const msg = JSON.parse(e.data);
    if (msg.event === 'wallet_count') {
      onUpdate({ mint: msg.data.mint, kol_count: msg.data.kol_count });
    }
  };
  return () => { try { ws.close(); } catch { /* already closing */ } };
}

Step 2, keep a count per token and render

Hold the latest count per mint in a Map, and update the matching badge whenever an event arrives. This scales to a whole list of tokens on one connection.

src/badges-live.ts

import { connectCountStream } from './count-stream';

const counts = new Map<string, number>();

export function startLiveBadges(): () => void {
  return connectCountStream(({ mint, kol_count }) => {
    counts.set(mint, kol_count);
    // Update the badge for this token if it is on the page.
    const badge = document.querySelector(`[data-mint="${mint}"] .kol-badge`);
    if (badge) badge.textContent = `${kol_count} KOLs`;
  });
}

Your markup just needs the mint on each row and a badge element to fill in.

index.html

<div data-mint="3Pkrq4MmLvDXyn1fa3sz5MekKRkZkc1iLDcz5AzWpump">
  invisibull <span class="kol-badge">0 KOLs</span>
</div>

Which one should you use

A simple rule. If you are decorating a static list and a number that is a little stale is fine, poll the REST count, it is one call and needs no connection. If the freshness is the point, a live count that ticks up as KOLs pile in, use the stream. You can also combine them. Seed each badge with a REST count on first paint so it is never empty, then let the stream take over for live updates.

Billing note

The REST count is one request per call, cheap because it returns only a number. On the stream, each delivered wallet_count event counts against your plan, so a wildcard subscription on a busy chain can add up, filter to the tokens you actually show.

Two numbers, two sources

Option A, a number on demand over REST

Step 1, the fetch

Step 2, show it, and refresh on an interval

Option B, a live badge over WebSocket

Step 2, keep a count per token and render

Which one should you use

Billing note

Reference

GET /v1/transactions/count

WSS count stream

​Two numbers, two sources

​Option A, a number on demand over REST

​Step 1, the fetch

​Step 2, show it, and refresh on an interval

​Option B, a live badge over WebSocket

​Step 1, connect and subscribe

​Step 2, keep a count per token and render

​Which one should you use

​Billing note

​Reference

GET /v1/transactions/count

WSS count stream

Two numbers, two sources

Option A, a number on demand over REST

Step 1, the fetch

Step 2, show it, and refresh on an interval

Option B, a live badge over WebSocket

Step 1, connect and subscribe

Step 2, keep a count per token and render

Which one should you use

Billing note

Reference