DEV Community

diogenicious
diogenicious

Posted on Fully Autonomous

Flag whale-sized trades and net flow per coin from a list of swaps, in TypeScript

You have a list of swaps: who traded, which coin, buy or sell, how many dollars, and when. You want to answer three questions about the last hour. Which trades are unusually large? For each coin, did the large trades add up to net buying or net selling? And how many different wallets were behind the large buys?

None of this needs a library. It is a filter, a time window and a group by. This post builds it in TypeScript, runs it on a small made-up sample, and then spends a section on everything this kind of number cannot tell you.

Disclosure: I am the founder of copy.top. We publish a free whale tracker page that lists coins which top traders from our leaderboard bought in the last 24 hours, with the number of buyers and the dollars bought. It takes no input. The code below is a separate, minimal version written for this article, and it only processes an array you already have.

The input

Where the swaps come from is up to you. This post starts from the array and nothing else. The code runs on Node 22.6 or newer with type stripping (tested here on Node 24):

node --experimental-strip-types run.ts
Enter fullscreen mode Exit fullscreen mode

Imports between files need the .ts extension, and I use import type for types, which this mode requires.

// trades.ts
export type Side = "buy" | "sell";

export interface Trade {
  wallet: string;
  coin: string;
  side: Side;
  usd: number; // size of the trade in dollars
  ts: number;  // unix time in milliseconds
}

const NOW = 1_700_000_000_000;
const ago = (minutes: number) => NOW - minutes * 60_000;

export const now = NOW;

export const trades: Trade[] = [
  { wallet: "w1", coin: "COIN_A", side: "buy",  usd: 8000,  ts: ago(10) },
  { wallet: "w2", coin: "COIN_A", side: "buy",  usd: 6000,  ts: ago(25) },
  { wallet: "w3", coin: "COIN_A", side: "sell", usd: 5500,  ts: ago(40) },
  { wallet: "w1", coin: "COIN_A", side: "buy",  usd: 300,   ts: ago(5) },
  { wallet: "w4", coin: "COIN_B", side: "buy",  usd: 12000, ts: ago(50) },
  { wallet: "w4", coin: "COIN_B", side: "sell", usd: 9000,  ts: ago(15) },
  { wallet: "w5", coin: "COIN_B", side: "buy",  usd: 400,   ts: ago(20) },
  { wallet: "w3", coin: "COIN_B", side: "sell", usd: 6500,  ts: ago(35) },
  { wallet: "w2", coin: "COIN_C", side: "buy",  usd: 7000,  ts: ago(90) },
  { wallet: "w6", coin: "COIN_C", side: "buy",  usd: 5000,  ts: ago(30) },
  { wallet: "w7", coin: "COIN_C", side: "buy",  usd: 5200,  ts: ago(12) },
  { wallet: "w1", coin: "COIN_C", side: "buy",  usd: 5100,  ts: ago(8) },
];
Enter fullscreen mode Exit fullscreen mode

The wallets and coins are invented, and the sample is fixed so you get the same output as below. In real use, now would be Date.now().

Step 1: a threshold filter

"Large" is a number you choose. Here it is 5000 dollars, and a trade of exactly 5000 counts.

// whales.ts
import type { Trade } from "./trades.ts";

export function largeTrades(trades: Trade[], minUsd: number): Trade[] {
  if (!(minUsd > 0)) throw new RangeError("minUsd must be positive");
  return trades.filter((t) => Number.isFinite(t.usd) && t.usd >= minUsd);
}
Enter fullscreen mode Exit fullscreen mode

Number.isFinite drops rows where usd is NaN or missing, instead of letting them poison a sum later.

// step1.ts
import { trades } from "./trades.ts";
import { largeTrades } from "./whales.ts";

const big = largeTrades(trades, 5000);
console.log(`${big.length} of ${trades.length} trades are 5000 or more`);
console.table(big);
Enter fullscreen mode Exit fullscreen mode

Output:

10 of 12 trades are 5000 or more
┌─────────┬────────┬──────────┬────────┬───────┬───────────────┐
│ (index) │ wallet │ coin     │ side   │ usd   │ ts            │
├─────────┼────────┼──────────┼────────┼───────┼───────────────┤
│ 0       │ 'w1'   │ 'COIN_A' │ 'buy'  │ 8000  │ 1699999400000 │
│ 1       │ 'w2'   │ 'COIN_A' │ 'buy'  │ 6000  │ 1699998500000 │
│ 2       │ 'w3'   │ 'COIN_A' │ 'sell' │ 5500  │ 1699997600000 │
│ 3       │ 'w4'   │ 'COIN_B' │ 'buy'  │ 12000 │ 1699997000000 │
│ 4       │ 'w4'   │ 'COIN_B' │ 'sell' │ 9000  │ 1699999100000 │
│ 5       │ 'w3'   │ 'COIN_B' │ 'sell' │ 6500  │ 1699997900000 │
│ 6       │ 'w2'   │ 'COIN_C' │ 'buy'  │ 7000  │ 1699994600000 │
│ 7       │ 'w6'   │ 'COIN_C' │ 'buy'  │ 5000  │ 1699998200000 │
│ 8       │ 'w7'   │ 'COIN_C' │ 'buy'  │ 5200  │ 1699999280000 │
│ 9       │ 'w1'   │ 'COIN_C' │ 'buy'  │ 5100  │ 1699999520000 │
└─────────┴────────┴──────────┴────────┴───────┴───────────────┘
Enter fullscreen mode Exit fullscreen mode

The two small trades (300 and 400) are gone, and the 5000 one stayed.

Step 2: a rolling window and net flow

A window keeps only trades from the last N minutes. The start is exclusive and the end is inclusive, so a trade exactly 60 minutes old is out.

Net flow per coin is buy dollars minus sell dollars. A positive number means the large trades in the window leaned toward buying. I count only large trades here, so the figure describes large-trade flow, not all flow.

// whales.ts (continued)
export function inWindow(trades: Trade[], now: number, windowMinutes: number): Trade[] {
  const start = now - windowMinutes * 60_000;
  return trades.filter((t) => t.ts > start && t.ts <= now);
}

export interface CoinFlow {
  coin: string;
  buyUsd: number;
  sellUsd: number;
  netUsd: number;
  largeBuyers: number;
  largeTrades: number;
}
Enter fullscreen mode Exit fullscreen mode

Step 3: distinct large buyers

Net flow can come from one big trade or from many. A Set of wallets per coin tells you which one it is, so the same loop also counts distinct large buyers.

// whales.ts (continued)
export function flowByCoin(trades: Trade[]): CoinFlow[] {
  const map = new Map<string, { buyUsd: number; sellUsd: number; buyers: Set<string>; n: number }>();
  for (const t of trades) {
    let c = map.get(t.coin);
    if (!c) {
      c = { buyUsd: 0, sellUsd: 0, buyers: new Set(), n: 0 };
      map.set(t.coin, c);
    }
    c.n += 1;
    if (t.side === "buy") {
      c.buyUsd += t.usd;
      c.buyers.add(t.wallet);
    } else {
      c.sellUsd += t.usd;
    }
  }
  return [...map].map(([coin, c]) => ({
    coin,
    buyUsd: c.buyUsd,
    sellUsd: c.sellUsd,
    netUsd: c.buyUsd - c.sellUsd,
    largeBuyers: c.buyers.size,
    largeTrades: c.n,
  }));
}
Enter fullscreen mode Exit fullscreen mode

Chaining the three pieces for the last 60 minutes:

// step2.ts
import { trades, now } from "./trades.ts";
import { largeTrades, inWindow, flowByCoin } from "./whales.ts";

const recent = inWindow(largeTrades(trades, 5000), now, 60);
console.table(flowByCoin(recent));
Enter fullscreen mode Exit fullscreen mode
┌─────────┬──────────┬────────┬─────────┬────────┬─────────────┬─────────────┐
│ (index) │ coin     │ buyUsd │ sellUsd │ netUsd │ largeBuyers │ largeTrades │
├─────────┼──────────┼────────┼─────────┼────────┼─────────────┼─────────────┤
│ 0       │ 'COIN_A' │ 14000  │ 5500    │ 8500   │ 2           │ 3           │
│ 1       │ 'COIN_B' │ 12000  │ 15500   │ -3500  │ 1           │ 3           │
│ 2       │ 'COIN_C' │ 15300  │ 0       │ 15300  │ 3           │ 3           │
└─────────┴──────────┴────────┴─────────┴────────┴─────────────┴─────────────┘
Enter fullscreen mode Exit fullscreen mode

The 7000 buy of COIN_C from 90 minutes ago is outside the window, so it does not count. COIN_B has the single biggest buy of the sample (12000), but its two large sells add up to 15500, so its net flow is negative.

Step 4: a small ranking

Sort by the number of distinct large buyers first, then by net flow, then by name so that ties always come out in the same order.

// whales.ts (continued)
export function rank(flows: CoinFlow[]): CoinFlow[] {
  return [...flows].sort(
    (a, b) => b.largeBuyers - a.largeBuyers || b.netUsd - a.netUsd || a.coin.localeCompare(b.coin),
  );
}
Enter fullscreen mode Exit fullscreen mode
// run.ts
import { trades, now } from "./trades.ts";
import { largeTrades, inWindow, flowByCoin, rank } from "./whales.ts";

const MIN_USD = 5000;
const WINDOW_MIN = 60;

const recent = inWindow(largeTrades(trades, MIN_USD), now, WINDOW_MIN);
const ranking = rank(flowByCoin(recent));

console.log(`large trades (>= ${MIN_USD} USD), last ${WINDOW_MIN} minutes`);
console.table(ranking);
Enter fullscreen mode Exit fullscreen mode
large trades (>= 5000 USD), last 60 minutes
┌─────────┬──────────┬────────┬─────────┬────────┬─────────────┬─────────────┐
│ (index) │ coin     │ buyUsd │ sellUsd │ netUsd │ largeBuyers │ largeTrades │
├─────────┼──────────┼────────┼─────────┼────────┼─────────────┼─────────────┤
│ 0       │ 'COIN_C' │ 15300  │ 0       │ 15300  │ 3           │ 3           │
│ 1       │ 'COIN_A' │ 14000  │ 5500    │ 8500   │ 2           │ 3           │
│ 2       │ 'COIN_B' │ 12000  │ 15500   │ -3500  │ 1           │ 3           │
└─────────┴──────────┴────────┴─────────┴────────┴─────────────┴─────────────┘
Enter fullscreen mode Exit fullscreen mode

Ranking by distinct buyers is a choice, not a law. Three wallets each buying 5000 is a different picture from one wallet buying 15000, and this ordering prefers the first. Change the sort if you prefer the second.

What this does not tell you

This is where most "whale alert" posts stop being honest, so here is the list.

  • One wallet is not one person. A single person or team can split a position across many wallets, and one wallet can be shared by several people. "Three large buyers" may be one actor. Treat largeBuyers as a count of addresses.
  • Size alone says nothing about skill. A large trade means a large balance, not a good decision. Big wallets lose money too, and a whale can be wrong on a coin for weeks.
  • Wash trading and self-trades. In the sample, w4 buys 12000 of COIN_B and sells 9000 of it in the same hour. A wallet moving size back and forth with itself or a partner inflates both buy and sell totals. Looking at net flow per wallet before summing per coin is a cheap first check.
  • Thin liquidity. On a coin with a small pool, 5000 dollars can be most of the day's volume. A fixed dollar threshold is too low for a deep market and too high for a tiny one. A threshold relative to the coin's volume is often more useful.
  • Delayed and incomplete data. Your source may lag, miss swaps, or revise them later. A window that ends at Date.now() is already stale by the time you read it, and ts may be the time the swap was indexed, not when it happened.
  • Flow is not direction. Net buying in the last hour does not say what the next hour will do. This is a description of what already happened.

If you want a ready made view of the same idea, the whale tracker page shows coins that tracked traders bought, with the numbers behind each one, and copy.top also has a crypto wallet tracker. copy.top is independent from fomo and pump.fun. Nothing here is financial advice. Trading memecoins is risky, you can lose everything you put in.

diogenicious

Top comments (0)