Build a Real-Time Holders Tab like Axiom

Learn how to build a real-time token holder table, a live view of who holds a token, with each holder position, bag percentage and unrealized PnL updating as trades happen. This guide walks the frontend logic end to end in TypeScript, with no CSS, so you can drop it into any framework and style it yourself.

CabalSpy/kol-realtime-holder-table

The full styled demo is open source. This guide rebuilds its core logic from scratch.

What you will build

By the end you will have a holder table with an initial snapshot fetched over the holder stream, live updates as wallets trade, live price driven updates as the market cap moves, and a small store that keeps it all in sync.

How CabalSpy differs from a raw swap feed

If you have built a holder table on a raw swap feed before, you had to track each wallet balance yourself, apply every buy and sell, and guard against drift. The CabalSpy holder stream does that work server side. It sends you a full position per holder, already computed, then keeps sending the updated position. You never add up trades by hand, you just replace a holder position with the latest one you receive. That makes the whole thing simpler. The three events you handle are init for the starting snapshot, holder_update when a single holder trades, and position_update when the market cap moves and the unrealized numbers change.

Architecture overview

One WebSocket connection carries everything. A small store holds the holder list keyed by wallet, and three event handlers write into it.

  holder stream (wss://stream.cabalspy.xyz)
    |
    |  init            -> replace the whole list with the snapshot
    |  holder_update   -> upsert one holder (they just traded)
    |  position_update -> refresh the list (market cap moved)
    v
  HolderStore  (Map keyed by wallet address)
    |
    v
  renderTable(holders[])   your UI, styled however you like

Step 1, project setup

Any bundler works. Starting from scratch with Vite and TypeScript is enough, there are no dependencies beyond the browser WebSocket.

Terminal

npm create vite@latest holder-table -- --template vanilla-ts
cd holder-table
npm install

Get your API key at apidashboard.cabalspy.xyz. The key is passed when you open the connection, so keep it out of source control and load it from an environment variable in production.

Step 2, type the data

Type the two shapes you receive, a holder and the position it carries. These mirror the fields the holder stream sends.

src/types.ts

export interface Profile {
  name: string;
  image_url: string;
  twitter: string;
  telegram: string;
  type: string;
}

export interface Position {
  held: number;
  bag_pct: number;
  supply_pct: number;
  invested: number;
  invested_usd: number;
  remaining_sol: number;
  remaining_usd: number;
  realized_pnl_usd: number;
  unrealized_pnl_usd: number;
  unrealized_pnl_pct: number;
  entry_market_cap_usd: number;
  first_buy_at: string;
  last_activity_at: string;
}

export interface Holder {
  wallet: string;
  wallet_type: string;
  win_rate: number | null;
  profile: Profile;
  position: Position;
}

Step 3, the holder store

The store keeps holders in a Map keyed by wallet address, so an update is a single replace. Keeping a Map, rather than an array, means an update from a trade is O(1) and never duplicates a wallet.

src/store.ts

import type { Holder } from './types';

export class HolderStore {
  private byWallet = new Map<string, Holder>();

  /** Replace the whole set from an init snapshot. */
  setAll(holders: Holder[]): void {
    this.byWallet.clear();
    for (const h of holders) this.byWallet.set(h.wallet, h);
  }

  /** Insert or replace a single holder (they just traded). */
  upsert(holder: Holder): void {
    this.byWallet.set(holder.wallet, holder);
  }

  /** Current holders as an array, sorted by remaining value. */
  list(): Holder[] {
    return [...this.byWallet.values()].sort(
      (a, b) => b.position.remaining_usd - a.position.remaining_usd,
    );
  }

  get count(): number {
    return this.byWallet.size;
  }
}

Open one WebSocket, authenticate with the key in the query string, and subscribe to a token. Subscribing to a single mint returns a starting snapshot, so you get the whole table on connect and live updates after.

src/stream.ts

export interface SubscribeOptions {
  apiKey: string;
  mint: string;
  walletTypes?: string[];
  mode?: 'full' | 'events';
  mcInterval?: number;
  onMessage: (msg: any) => void;
  onStatus?: (status: 'open' | 'closed') => void;
}

export function connectHolderStream(opts: SubscribeOptions): () => void {
  const ws = new WebSocket(`wss://stream.cabalspy.xyz?apiKey=${encodeURIComponent(opts.apiKey)}`);

  ws.onopen = () => {
    opts.onStatus?.('open');
    ws.send(JSON.stringify({
      op: 'subscribe',
      stream: 'holder',
      token: opts.mint,
      wallet_types: opts.walletTypes ?? ['kol', 'smart', 'whale'],
      mode: opts.mode ?? 'full',
      ...(opts.mcInterval ? { mc_interval: opts.mcInterval } : {}),
    }));
  };

  ws.onmessage = (e) => {
    try { opts.onMessage(JSON.parse(e.data)); } catch { /* ignore malformed frames */ }
  };

  ws.onclose = () => opts.onStatus?.('closed');

  // Return an unsubscribe/close function for cleanup.
  return () => { try { ws.close(); } catch { /* already closing */ } };
}

Step 5, handle the three events

This is the heart of it. Route each event to the store. init replaces the list, holder_update upserts the one holder that traded, and position_update refreshes the list when the market cap moves.

src/holders.ts

import { HolderStore } from './store';
import { connectHolderStream } from './stream';
import type { Holder } from './types';

export function startHolderTable(
  apiKey: string,
  mint: string,
  render: (holders: Holder[], count: number) => void,
): () => void {
  const store = new HolderStore();

  const close = connectHolderStream({
    apiKey,
    mint,
    mode: 'full',
    onMessage: (msg) => {
      switch (msg.event) {
        case 'init':
          // Full snapshot of every tracked holder.
          store.setAll(msg.data.holders ?? []);
          break;

        case 'holder_update':
          // One holder traded, replace just that holder.
          if (msg.data.holder) store.upsert(msg.data.holder);
          break;

        case 'position_update':
          // Market cap moved, the server resends the current holders with fresh
          // unrealized numbers. Replace the set so PnL stays accurate.
          if (Array.isArray(msg.data.holders)) store.setAll(msg.data.holders);
          break;

        default:
          return; // welcome / subscribed / pong frames, nothing to render
      }
      render(store.list(), store.count);
    },
  });

  return close;
}

Step 6, render the table

The store hands you a plain array, so rendering is up to you and your framework. Here is a dependency free version that writes rows into a table body. No CSS, style it later.

src/render.ts

import type { Holder } from './types';

const usd = (v: number) => '$' + (Number(v) || 0).toLocaleString('en-US', { maximumFractionDigits: 2 });
const pct = (v: number) => (Number(v) || 0).toFixed(2) + '%';

export function renderTable(holders: Holder[], count: number): void {
  const countEl = document.querySelector('#holder-count');
  if (countEl) countEl.textContent = String(count);

  const body = document.querySelector('#holder-body');
  if (!body) return;

  body.innerHTML = holders.map((h) => {
    const p = h.position;
    const pnlUp = p.unrealized_pnl_usd >= 0;
    return `
      <tr>
        <td>${h.profile.name || h.wallet.slice(0, 4)}</td>
        <td>${h.wallet_type}</td>
        <td>${usd(p.remaining_usd)}</td>
        <td>${pct(p.bag_pct)}</td>
        <td>${pct(p.supply_pct)}</td>
        <td style="color:${pnlUp ? 'green' : 'red'}">${usd(p.unrealized_pnl_usd)} (${pct(p.unrealized_pnl_pct)})</td>
      </tr>`;
  }).join('');
}

Step 7, wire it together

A minimal entry point. Give it an API key and a mint, and the table fills in and stays live. The returned function closes the connection when you are done, for example on a route change.

src/main.ts

import { startHolderTable } from './holders';
import { renderTable } from './render';

const API_KEY = import.meta.env.VITE_CABALSPY_KEY as string;
const MINT = '3Pkrq4MmLvDXyn1fa3sz5MekKRkZkc1iLDcz5AzWpump';

const stop = startHolderTable(API_KEY, MINT, renderTable);

// Later, when leaving the page:
// stop();

And the markup it writes into, the only HTML you need.

index.html

<h2>Holders (<span id="holder-count">0</span>)</h2>
<table>
  <thead>
    <tr><th>Trader</th><th>Type</th><th>Value</th><th>Bag</th><th>Supply</th><th>Unrealized PnL</th></tr>
  </thead>
  <tbody id="holder-body"></tbody>
</table>

Choosing a mode

The mode you pass on subscribe controls how much you receive, and how many credits you spend.

mode	What you receive	mc_interval
full	Trades plus live position updates every time the market cap moves. Default.	Supported
events	Only real trade events. Unrealized PnL will not tick between trades. Cheapest.	Ignored

With mode full you can pass mc_interval, a number of seconds from 1 to 30, to receive at most one market cap update per token in that window. It is the simplest way to keep a busy token from using credits quickly while still staying live.

Lessons worth knowing

A few things that save you time. The snapshot arrives for free. Because you subscribe to a single mint, the init event gives you the whole current table before any live update, so there is no separate REST call to seed the list. You never compute balances. Unlike a raw swap feed, every holder_update and position_update carries the full, server computed position. Always replace, never add up trades yourself, and you cannot drift. Reconnect cleanly. If the socket closes, reopen and resubscribe. The next init gives you a fresh snapshot, so you recover the correct state automatically without patching up missed messages.

Reference

WSS holder stream

The full holder stream reference, every field on init, holder_update and position_update.

CabalSpy/kol-realtime-holder-table

​What you will build

​How CabalSpy differs from a raw swap feed

​Architecture overview

​Step 1, project setup

​Step 2, type the data

​Step 3, the holder store

​Step 4, connect and subscribe

​Step 5, handle the three events

​Step 6, render the table

​Step 7, wire it together

​Choosing a mode

​Lessons worth knowing

​Reference