Whale tracking on Base and Ethereum with the GoldRush Streaming API
Find the top trader wallets for any token on Base or Ethereum, stream their transactions live with GoldRush, and flag large transfers and exchange flows.
On this page
- What counts as a whale, and which signals to watch
- How the tracker works
- Set up the project
- Find the top trader wallets for a token
- Stream the whales' wallet activity
- Label exchange wallets to classify deposits and withdrawals
- Run it on Ethereum
- Add historical context to an alert
- Interpreting whale moves
- Frequently asked questions
- Next steps
Whale tracking means watching the wallets that hold or trade enough of a token to move its price, and reacting to what they do. This guide builds a whale tracker for Base and Ethereum in two steps. First it asks the GoldRush Streaming API for a token's top trader wallets over the last 30 days. Then it subscribes to those wallets' activity, so each transfer reaches you as it lands, sized in USD and tagged when it goes to or comes from an exchange you have labelled.
About the Streaming API docs. The GoldRush Streaming API's multi-chain reference is being rebuilt and returns in January 2027; Hyperliquid streaming is live today. The code here follows the types published in the GoldRush SDK (
@covalenthq/client-sdk3.0.9), which list Base and Ethereum for both calls it makes. Ask GoldRush support to confirm they are enabled for your key before you rely on them.
What counts as a whale, and which signals to watch
There's no fixed size that makes a wallet a whale. It depends on the token: a wallet that trades a few percent of a small token's daily volume can move it, while the same amount barely registers in ETH. A practical definition is relative: the wallets that hold or trade the most of a given token. That is what this tracker starts from.
Whales are not one group. Team and early-investor wallets often hold tokens on a vesting schedule, market makers move funds as part of inventory management, and individual traders take directional positions. The same transfer can mean different things depending on who sent it.
The signals worth watching:
- Large transfers. A single movement worth far more than the token's typical trade size. This is the alert the tracker raises.
- Exchange flows. Tokens sent to an exchange deposit address, or withdrawn from one into self-custody. You need labelled exchange addresses to see these.
- Accumulation, then distribution. A wallet that buys steadily over hours or days and later sends the position to an exchange or sells it into a price spike. Timing across both legs is the signal, not either one alone.
- Token unlocks. Vesting contracts release tokens on a schedule. A team or investor wallet that receives an unlock and then moves it is worth watching; check the project's published vesting schedule for the dates.
- Liquidity pool moves. Large adds to or withdrawals from a DEX pool change how much the price moves for a given trade.
- Coordinated wallets. Several wallets moving the same token with the same timing are often one actor.
How the tracker works
| Step | What it does | GoldRush call | Credit cost |
|---|---|---|---|
| Discover | Lists the wallets with the highest trading volume in a token, last 30 days | Top Trader Wallets for Token query | 1 per call |
| Watch | Streams every transaction those wallets make | Wallet Activity stream (beta) | 1 per minute |
| Classify | Sizes each transfer in USD, flags large ones, tags exchange deposits/withdrawals | none: your code | |
| Context | Pulls a wallet's current holdings and lifetime activity when an alert fires | Token balances, transaction summary | 1 per call and 1 per call |
The discover step answers "who should I watch?", and the watch step answers "what are they doing now?". Without the first, you're guessing at addresses; without the second, you only see what a wallet did after the fact.
Set up the project
You need Node.js 22 or later (it has a built-in WebSocket client, which the SDK uses) and a GoldRush API key.
mkdir whale-tracker && cd whale-trackernpm init -ynpm pkg set type=modulenpm install @covalenthq/client-sdknpm install --save-dev tsx typescript @types/nodemkdir srcSave the shared configuration as src/config.ts. It picks the chain from the CHAIN environment variable, so the same code runs on Base and Ethereum:
import { ChainName, GoldRushClient, StreamingChain } from "@covalenthq/client-sdk"; const apiKey = process.env.GOLDRUSH_API_KEY;if (!apiKey) throw new Error("Set GOLDRUSH_API_KEY in your environment"); // The two chains this tracker runs on. Streaming calls take the StreamingChain name, the// Foundational API (used for history) takes the ChainName. Each has a default token to track.const CHAINS = { BASE_MAINNET: { stream: StreamingChain.BASE_MAINNET, foundational: ChainName.BASE_MAINNET, defaultToken: "0x4ed4E862860beD51a9570b96d89aF5E1B0Efefed", // DEGEN on Base }, ETH_MAINNET: { stream: StreamingChain.ETH_MAINNET, foundational: ChainName.ETH_MAINNET, defaultToken: "0x1f9840a85d5aF5bf1D1762F925BDADdC4201F984", // UNI on Ethereum },} as const; type ChainKey = keyof typeof CHAINS;const chainKey = process.env.CHAIN ?? "BASE_MAINNET";if (!(chainKey in CHAINS)) throw new Error(`CHAIN must be one of: ${Object.keys(CHAINS).join(", ")}`); export const CHAIN = CHAINS[chainKey as ChainKey];export const TOKEN_ADDRESS = process.env.TOKEN_ADDRESS ?? CHAIN.defaultToken;export const TOP_N = Number(process.env.TOP_N ?? 10);// Transfers worth at least this many USD are flagged as whale alerts.export const ALERT_USD = Number(process.env.ALERT_USD ?? 100_000); export const client = new GoldRushClient( apiKey, {}, { onOpened: () => console.log("Connected to the GoldRush Streaming API."), onClosed: () => console.log("Disconnected."), onError: (err) => console.error("Connection error:", err), });Find the top trader wallets for a token
The Top Trader Wallets for Token query (upnlForToken) returns the wallets with the highest trading volume in a token over the last 30 days, with each wallet's transaction count, current balance, and realized and unrealized profit and loss in USD. It costs 1 per call and supports Base, Ethereum, BNB Smart Chain (BSC), Polygon, Gnosis, Optimism, MegaETH and Robinhood Chain. The SDK wraps it as StreamingService.getUPnLForToken, which returns a promise rather than a subscription.
Save this as src/discover.ts:
import { CHAIN, TOKEN_ADDRESS, TOP_N, client } from "./config";import { type UPnLForTokenResponse } from "@covalenthq/client-sdk"; export type Whale = { wallet: string; symbol: string; volume: number; // traded in the last 30 days, as the query reports it txCount: number; balance: string; // current balance, in whole tokens realizedUsd: number; unrealizedUsd: number;}; export function toWhale(row: UPnLForTokenResponse): Whale { return { wallet: row.wallet_address.toLowerCase(), symbol: row.contract_metadata?.contract_ticker_symbol ?? "?", volume: Number(row.volume), txCount: row.transactions_count, balance: row.balance_pretty, realizedUsd: row.pnl_realized_usd ?? 0, unrealizedUsd: row.pnl_unrealized_usd ?? 0, };} // Top trader wallets for a token over the last 30 days, highest volume first.export async function findWhales(token = TOKEN_ADDRESS, n = TOP_N): Promise<Whale[]> { const rows = await client.StreamingService.getUPnLForToken({ chain_name: CHAIN.stream, token_address: token, }); return rows .map(toWhale) .sort((a, b) => b.volume - a.volume) .slice(0, n);} const usd = (n: number) => n.toLocaleString("en-US", { style: "currency", currency: "USD", maximumFractionDigits: 0 }); export function printWhales(whales: Whale[]) { console.table( whales.map((w) => ({ wallet: w.wallet, txs: w.txCount, balance: `${w.balance} ${w.symbol}`, realized: usd(w.realizedUsd), unrealized: usd(w.unrealizedUsd), })) );} // Run on its own: `npx tsx src/discover.ts`if (import.meta.url === `file://${process.argv[1]}`) { const whales = await findWhales(); if (whales.length === 0) console.log(`No trading data for ${TOKEN_ADDRESS} on ${CHAIN.stream} in the last 30 days.`); else printWhales(whales); await client.StreamingService.disconnect();}Run it:
GOLDRUSH_API_KEY=your_key npx tsx src/discover.tsIt prints one row per wallet. An empty result means the token had no indexed trading in the last 30 days on that chain; pick a more actively traded token. These are the fields each row has:
| Field | What it is |
|---|---|
wallet_address |
The trader's wallet |
volume |
The wallet's trading volume in the token over the last 30 days |
transactions_count |
How many transactions it made in the token |
balance, balance_pretty |
Its current balance, raw and in whole tokens |
pnl_realized_usd, pnl_unrealized_usd |
Profit or loss in USD on what it sold, and on what it holds |
contract_metadata |
The token's name, ticker, decimals and address |
A wallet near the top of this list with a large balance and a large unrealized profit is the classic whale to watch: it has room to sell. One with a large realized profit and a small balance has already taken most of its gains.
Stream the whales' wallet activity
The Wallet Activity stream (walletTxs) pushes each transaction a set of wallets makes, decoded where GoldRush recognises it: token transfers, swaps, bridges, deposits, withdrawals and approvals. It's in beta, costs 1 per minute, and supports Base, Ethereum, BNB Smart Chain (BSC), Monad, HyperCore, HyperEVM, Polygon, MegaETH and Robinhood Chain. The SDK wraps it as StreamingService.subscribeToWalletActivity, and calls your next handler with an array of transactions.
The tracker subscribes with the wallets the discover step returned, normalises each event into one movement (which watched wallet, in or out, the counterparty, the token and its USD value) and flags movements at or above ALERT_USD. Events with no priced token movement, such as swaps, approvals and failed transactions, are skipped.
Save this as src/watch.ts:
import { ALERT_USD, CHAIN, client } from "./config";import { findWhales, printWhales } from "./discover";import { type Label, labelFor } from "./labels";import { type WalletActivityStreamResponse } from "@covalenthq/client-sdk"; export type WhaleMove = { whale: string; direction: "in" | "out"; counterparty: string; label?: Label; type: string; symbol: string; usd: number; tx: string; at: string;}; // One wallet-activity event -> one token movement of a watched wallet, or null for events with no// priced token movement (swaps, approvals, failed or undecoded transactions).export function toMove(tx: WalletActivityStreamResponse, watched: Set<string>): WhaleMove | null { const d = tx.decoded_details; if (!tx.successful || !d || !("from" in d)) return null; const from = d.from.toLowerCase(); const to = d.to.toLowerCase(); const whale = watched.has(from) ? from : watched.has(to) ? to : null; if (!whale) return null; const direction = whale === from ? "out" : "in"; const counterparty = direction === "out" ? to : from; return { whale, direction, counterparty, label: labelFor(counterparty), type: tx.decoded_type, symbol: d.contract_metadata?.contract_ticker_symbol ?? "?", usd: d.quote_usd ?? 0, tx: tx.tx_hash, at: tx.block_signed_at, };} // A heuristic reading of the move, not a prediction.export function describeMove(m: WhaleMove): string { if (m.label?.kind === "exchange") { return m.direction === "out" ? `deposit to ${m.label.name} (possible distribution)` : `withdrawal from ${m.label.name} (possible accumulation)`; } const who = m.label ? m.label.name : m.counterparty; return m.direction === "out" ? `sent to ${who}` : `received from ${who}`;} export function handleActivity(txs: WalletActivityStreamResponse[], watched: Set<string>): WhaleMove[] { const moves = txs.map((tx) => toMove(tx, watched)).filter((m): m is WhaleMove => m !== null); for (const m of moves) { const tag = m.usd >= ALERT_USD ? "WHALE ALERT" : "move"; const amount = m.usd.toLocaleString("en-US", { style: "currency", currency: "USD", maximumFractionDigits: 0 }); console.log(`[${tag}] ${m.at} ${m.whale} ${describeMove(m)}: ${amount} of ${m.symbol} (${m.type}) tx ${m.tx}`); } return moves;} if (import.meta.url === `file://${process.argv[1]}`) { // 1. Discover: the token's top traders over the last 30 days. const whales = await findWhales(); if (whales.length === 0) { console.log("No top traders found for this token. Try a more actively traded one."); await client.StreamingService.disconnect(); process.exit(0); } printWhales(whales); const watched = new Set(whales.map((w) => w.wallet)); // 2. Watch: stream their transactions as they land. let unsubscribe: () => void = () => {}; const subscribe = () => { unsubscribe = client.StreamingService.subscribeToWalletActivity( { chain_name: CHAIN.stream, wallet_addresses: [...watched] }, { next: (txs) => handleActivity(txs, watched), // The stream doesn't replay what you missed while disconnected, so reconnect quickly. error: (err) => { console.error("Stream error:", err); setTimeout(subscribe, 1000); }, complete: () => setTimeout(subscribe, 1000), } ); }; subscribe(); console.log(`Watching ${watched.size} wallets on ${CHAIN.stream}. Alerts at ${ALERT_USD} USD and above.`); process.on("SIGINT", async () => { unsubscribe(); await client.StreamingService.disconnect(); process.exit(0); });}Run the full loop, discover then watch:
GOLDRUSH_API_KEY=your_key ALERT_USD=50000 npx tsx src/watch.tsIt prints the whale table, then one line per movement as it happens, with WHALE ALERT on the large ones. Two design choices to keep:
- Reconnect quickly. The stream doesn't replay events you missed while disconnected, so the
errorandcompletehandlers resubscribe after a second. - Refresh the list. Top traders change. Rerun the discover step on a schedule, daily for example, and resubscribe with the new set of wallets.
Label exchange wallets to classify deposits and withdrawals
A transfer from a whale to an exchange's deposit address is a different signal from a transfer to another self-custody wallet, but the chain doesn't say which addresses belong to exchanges. You have to label them. Save this as src/labels.ts, which watch.ts already imports:
// Known counterparties, keyed by lowercase address. You maintain this list: add only addresses you// have checked yourself (on the exchange's own proof-of-reserves page or a block explorer's label),// and re-check them from time to time, because exchanges rotate wallets.export type Label = { name: string; kind: "exchange" | "bridge" | "other" }; export const LABELS: Record<string, Label> = { // "0x...": { name: "Exchange A hot wallet", kind: "exchange" },}; export function labelFor(address: string): Label | undefined { return LABELS[address.toLowerCase()];}The list ships empty on purpose. Add only addresses you have verified yourself, from an exchange's proof-of-reserves disclosure or an explorer's address label, and check them again from time to time: exchanges add and rotate wallets, and a stale label gives you a wrong signal. Once an address is labelled exchange, describeMove turns transfers to it into "deposit to ... (possible distribution)" and transfers from it into "withdrawal from ... (possible accumulation)". Label bridges too, so that tokens leaving for another chain aren't mistaken for a sale.
Run it on Ethereum
Both GoldRush calls support Ethereum mainnet as well as Base, so the same code runs with the chain switched. config.ts defaults to UNI on Ethereum; pass TOKEN_ADDRESS for any other ERC-20:
GOLDRUSH_API_KEY=your_key CHAIN=ETH_MAINNET npx tsx src/watch.tsGOLDRUSH_API_KEY=your_key CHAIN=ETH_MAINNET TOKEN_ADDRESS=0xYourToken npx tsx src/watch.tsKeep a separate label list per chain if you track both: an exchange's deposit addresses on Ethereum are not the same as its addresses on Base.
Add historical context to an alert
An alert tells you a wallet moved tokens. Before acting on it, you'll usually want to know what else the wallet holds and how long it has been active. The GoldRush Foundational API answers both through the same SDK client: token balances (credit cost: 1 per call) and the transaction summary (credit cost: 1 per call), with the first and latest transaction and the total count.
Save this as src/context.ts:
import { CHAIN, client } from "./config"; // Current holdings and lifetime activity for one wallet, from the Foundational API.export async function walletContext(address: string) { const [balances, summary] = await Promise.all([ client.BalanceService.getTokenBalancesForWalletAddress(CHAIN.foundational, address, { noSpam: true }), client.TransactionService.getTransactionSummary(CHAIN.foundational, address), ]); if (balances.error) throw new Error(`Balances: ${balances.error_message}`); if (summary.error) throw new Error(`Transaction summary: ${summary.error_message}`); const holdings = (balances.data.items ?? []) .filter((i) => (i.quote ?? 0) > 0) .sort((a, b) => (b.quote ?? 0) - (a.quote ?? 0)) .slice(0, 5) .map((i) => ({ token: i.contract_ticker_symbol, usd: i.quote })); const s = summary.data.items?.[0]; return { address, holdings, totalTransactions: s?.total_count ?? null, firstSeen: s?.earliest_transaction?.block_signed_at ?? null, lastSeen: s?.latest_transaction?.block_signed_at ?? null, };} // `npx tsx src/context.ts 0xWALLET`if (import.meta.url === `file://${process.argv[1]}`) { const address = process.argv[2]; if (!address) throw new Error("Usage: npx tsx src/context.ts <wallet address>"); console.dir(await walletContext(address), { depth: null }); await client.StreamingService.disconnect();}Run it for any wallet from the whale table:
GOLDRUSH_API_KEY=your_key npx tsx src/context.ts 0xWalletFromTheTableCall walletContext from handleActivity for alerts only, not for every movement, so a busy wallet doesn't turn into a stream of paid lookups.
Interpreting whale moves
The tracker reports what happened. What it means is a judgment call, and these are heuristics, not predictions:
- Exchange deposits can mean distribution. Tokens sent to an exchange are easier to sell, so a large deposit is often read as preparation to sell. It can also be collateral for a derivatives position or an internal move.
- Exchange withdrawals can mean accumulation. Tokens moved off an exchange into self-custody leave the exchange's tradable supply, which is often read as intent to hold.
- Impact depends on liquidity. The same USD amount matters far more in a token with thin order books and shallow DEX pools than in one with deep liquidity. Compare a move with the token's liquidity, not with a fixed threshold.
- Coordinated transfers across fresh wallets. Several new wallets receiving or sending the same token at the same time often belong to one actor splitting a position.
- Watch LP withdrawals. A large wallet pulling liquidity from a pool makes every later trade move the price more. A sudden withdrawal from a pool that holds most of a token's liquidity is a red flag.
- Concentration is a risk in itself. If a handful of wallets in the top-trader table hold most of a token's liquid supply, they can move its price at will. Treat price action in a token like that with more suspicion, and size positions accordingly.
- Context beats any single event. One transfer rarely means much. A pattern across several wallets and several days, read alongside price and volume, is more reliable.

Frequently asked questions
What is a crypto whale tracker?
A crypto whale tracker watches the wallets that hold or trade the most of a token and reports what they do, usually as alerts on large transfers and on deposits to and withdrawals from exchanges. This guide builds one for Base and Ethereum: it finds a token's top trader wallets with the GoldRush Streaming API and streams their transactions live.
How do I find whale wallets for a token on Base?
Use the GoldRush Top Trader Wallets for Token query (upnlForToken, wrapped by the SDK as getUPnLForToken) with chain_name set to BASE_MAINNET and the token's contract address. It returns the wallets with the highest trading volume in that token over the last 30 days, with their balances and realized and unrealized PnL.
Does this work on Ethereum?
Yes. Both the Top Trader Wallets for Token query and the Wallet Activity stream support Ethereum mainnet, so the same code runs with CHAIN=ETH_MAINNET and an Ethereum token address. Keep separate exchange labels per chain.
Can I track whales on Hyperliquid?
This guide covers EVM chains. For Hyperliquid, GoldRush has a dedicated Hyperliquid whale tracker that groups wallets with open perp positions into PnL cohorts and opens any address as a live trader profile.
Can whales hide from on-chain tracking?
Partly. Whales split positions across many wallets, route funds through exchanges and bridges, and trade over the counter, which breaks the trail a tracker follows. Labelling exchanges and bridges and watching for coordinated wallets helps, but no tracker sees everything. Tracking public addresses also doesn't tell you who owns them: an address is not an identity, so treat labels as your best guess and don't single out individuals.
Is whale tracking a reliable trading signal?
No single signal is. Exchange flows and large transfers are context: the same move can be a sale, collateral or an internal transfer. Combine them with price, liquidity and your own risk limits. Nothing in this guide is financial advice.
Next steps
- GoldRush Streaming API overview
- Build a real-time AI trading agent on Base: stream OHLCV candles and trade on a signal
- Base API and Ethereum API: GoldRush's coverage of each chain
- Hyperliquid whale tracker for Hyperliquid traders
- Get a GoldRush API key