4. Trader Leaderboard

A leaderboard ranks traders against each other. The approach here is watchlist-based: you define the set of addresses to track (traders you’ve discovered from the fill tape, a curated list, addresses your users follow) and rank them with a single batched read per refresh, plus live volume from the stream you already have open. This scales cleanly and costs one request per cycle rather than one per trader.

1. Batch the portfolio reads

batchPortfolioStates takes a users array and returns one result slot per address, in request order.

const watchlist = [
  "0xaaa...",
  "0xbbb...",
  // …up to 50
];

const slots = await info({ type: "batchPortfolioStates", users: watchlist });

[
  {
    "user": "0xaaa...",
    "result": {
      "type": "portfolioState",
      "address": "0xaaa...",
      "chainId": 999,
      "perpetuals": { "marginSummary": { "accountValue": "125043.10", "...": "…" } },
      "spot": { "balances": [] }
    },
    "error": null
  },
  {
    "user": "0xbbb...",
    "result": null,
    "error": "upstream timeout"
  }
]

Two properties of that response shape matter: Failure is isolated per user. A slot that failed has result: null and a populated error; the rest of the batch still succeeds. One bad address never takes down the board, but you must handle the null, or your ranking will throw on the first slot that didn’t resolve. Slots come back in request order, with user echoed on each, so you can either zip by index or key by user. Keying by user is the more robust of the two.

The limit is 50 users per request. Beyond that the request fails; it does not silently truncate. Chunk larger watchlists, and remember that each chunk is a separate billed request.

function chunk(arr, size) {
  const out = [];
  for (let i = 0; i < arr.length; i += size) out.push(arr.slice(i, i + size));
  return out;
}

async function fetchWatchlist(addresses) {
  const batches = await Promise.all(
    chunk(addresses, 50).map((users) => info({ type: "batchPortfolioStates", users })),
  );

  return batches.flat().map((slot) => {
    const perps = slot.result?.perpetuals;
    return {
      address: slot.user,
      error: slot.error,
      accountValue: perps ? Number(perps.marginSummary.accountValue) : null,
      positions: (perps?.assetPositions ?? []).map((a) => a.position),
      unrealizedPnl: (perps?.assetPositions ?? []).reduce(
        (sum, a) => sum + Number(a.position.unrealizedPnl),
        0,
      ),
    };
  });
}

2. Rank

Account value is the headline metric and comes straight from the batch:

const ranked = rows
  .filter((r) => r.accountValue !== null)
  .sort((a, b) => b.accountValue - a.accountValue)
  .map((r, i) => ({ rank: i + 1, ...r }));

Keep the failed rows rather than dropping them silently. Render them unranked with a “data unavailable” state. A trader vanishing from the board because of one timed-out request looks like a bug to anyone watching a specific address.

3. Keep it live between polls

Refetching the batch every few seconds is the expensive way to make a leaderboard feel live. The cheap way is to poll slowly and recompute unrealized PnL locally against live mids in between. You already have the positions from the batch, and the price store from the wallet tracker. That’s everything needed:

function liveAccountValue(row) {
  if (row.accountValue === null) return null;

  // Replace each position's snapshot uPnL with one computed off the live mid.
  const liveUpnl = row.positions.reduce((sum, p) => {
    const mid = prices.get(p.coin);
    if (mid === undefined) return sum + Number(p.unrealizedPnl);
    return sum + Number(p.szi) * (mid - Number(p.entryPx));
  }, 0);

  return row.accountValue - row.unrealizedPnl + liveUpnl;
}

A 60-second poll with live uPnL in between gives a board that ticks continuously at 1/30th the request cost of a 2-second poll.

Pause polling when the tab is hidden. A leaderboard left open in a background tab overnight is hundreds of requests nobody looked at.

document.addEventListener("visibilitychange", () => {
  document.hidden ? stopPolling() : startPolling();
});

4. Rank by live volume

Account value ranks wealth. To rank activity, accumulate traded notional per address from the allFills stream, the same subscription already powering prices and the tape.

const volumeByAddress = new Map();

ws.on("message", (raw) => {
  const msg = JSON.parse(raw.toString());
  if (msg.channel !== "allFills" || !Array.isArray(msg.fills)) return;

  for (const [address, fill] of msg.fills) {
    if (!fill?.coin || !fill.px) continue;
    const notional = Math.abs(Number(fill.px) * Number(fill.sz));
    volumeByAddress.set(address, (volumeByAddress.get(address) ?? 0) + notional);
  }
});

Because allFills is venue-wide, this observes every trader, not just your watchlist, which makes it a discovery mechanism as much as a ranking one:

// Rank the watchlist by session volume…
const byVolume = watchlist
  .map((address) => ({ address, volume: volumeByAddress.get(address) ?? 0 }))
  .sort((a, b) => b.volume - a.volume);

// …or surface active traders you aren't tracking yet.
const candidates = [...volumeByAddress.entries()]
  .filter(([address]) => !watchlist.includes(address))
  .sort((a, b) => b[1] - a[1])
  .slice(0, 20);

This volume is session-scoped: it counts from when your stream connected, and resets on reconnect. Label it accordingly (“volume this session”, not “24h volume”). If you need a persistent figure, accumulate into a datastore server-side with one long-lived connection shared across all users, rather than one per browser tab.

5. Assemble the surface

async function refreshLeaderboard(watchlist) {
  const rows = (await fetchWatchlist(watchlist)).map((row) => ({
    ...row,
    liveValue: liveAccountValue(row),
    sessionVolume: volumeByAddress.get(row.address) ?? 0,
    openPositions: row.positions.length,
  }));

  // Rank only the rows that have a value to rank. A slot that failed upstream is
  // not "last". It is unknown, and numbering it as last states something false.
  const ranked = rows
    .filter((r) => r.liveValue !== null)
    .sort((a, b) => b.liveValue - a.liveValue)
    .map((row, i) => ({ ...row, rank: i + 1 }));

  const unavailable = rows
    .filter((r) => r.liveValue === null)
    .map((row) => ({ ...row, rank: null }));

  // Unranked rows go after the ranked ones, still visible, still identifiable.
  return [...ranked, ...unavailable];
}

startPolling(() => refreshLeaderboard(watchlist), 60_000);

Sensible columns: rank, address, account value (live), unrealized PnL, open position count, and session volume, with the address linking through to the wallet tracker and PnL surfaces for a full history on whoever’s at the top. Render a rank: null row with a dash and a “data unavailable” state rather than a number. A trader whose batch slot timed out on this cycle will be ranked normally on the next one, and showing them in last place in the meantime reads as a real ranking change to anyone watching that address.

Cost summary

Putting the whole dashboard together, the steady-state cost of a running instance is small and, importantly, flat in the number of traders you display:

Source	Cost
`batchPortfolioStates`, 50 traders @ 60s	50 lookups/min
`allFills` subscription	1/min, powers prices, tape, and volume
`l2Book`, one coin	0.5/min
`webData2` + `meta` @ 60s	2 requests/min

The single allFills subscription doing triple duty is the load-bearing design decision across this series. Adding traders to the watchlist grows only the batch; adding surfaces to the dashboard costs nothing extra at all.

Where to go next

Info API overview lists every supported Info type.
Rate limits, caching & polling covers poll intervals and backoff.
Hyperliquid WebSockets documents every available channel and its payload.

Quickstart

Guides

Hyperliquid API

1. Batch the portfolio reads

2. Rank

3. Keep it live between polls

4. Rank by live volume

5. Assemble the surface

Cost summary

Where to go next

​1. Batch the portfolio reads

​2. Rank

​3. Keep it live between polls

​4. Rank by live volume

​5. Assemble the surface

​Cost summary

​Where to go next

1. Batch the portfolio reads

2. Rank

3. Keep it live between polls

4. Rank by live volume

5. Assemble the surface

Cost summary

Where to go next