Whale Tracking Bot Development

Whale Tracking Bot Development

"Whale" in on-chain analytics context — address with significant position volume or transaction amount relative to liquidity of specific protocol or token. Whale tracking useful in several scenarios: trading signals (large address started accumulating — interesting), protocol risk management (one holder accumulated >10% supply — dump risk), compliance (tracking OFAC sanctioned list addresses).

Key technical complexity — not monitoring itself, but classification: distinguishing real whale fund movement from internal transfers between own wallets, from wash trading, from technical operations (LP rebalancing).

Data Sources

On-chain (primary):

• Ethereum: eth_getLogs + eth_subscribe(logs) for ERC-20 Transfer events
• Solana: Helius webhooks with program ID filtering and instruction type
• DEX events: Uniswap V3 Swap, Curve TokenExchange, dYdX order fills

Analytical (secondary, for enrichment):

• Nansen API — address labelling (Smart Money, CEX hot wallets, known DeFi whales)
• Arkham Intelligence API — entity-level attribution
• Etherscan labels API — exchange wallets, protocols
• DeBank API — current address portfolio

Bot Architecture

Block Producer (WebSocket/Helius webhook)
        │
        ▼
Event Queue (Redis Streams or BullMQ)
        │
        ▼
Transaction Classifier
   ├── Filter: whale threshold check (>$X USD)
   ├── Label resolver (CEX deposit? Internal transfer? DEX swap?)
   └── Dedup (one transaction may trigger N events)
        │
        ▼
Signal Generator
   ├── Accumulation pattern detector
   ├── Large withdrawal from CEX (bullish signal)
   └── Large deposit to CEX (potential sell)
        │
        ▼
Notification Dispatcher
   ├── Telegram Bot API
   ├── Discord Webhooks
   └── WebSocket push (for dashboard)

Significant Transaction Detector

interface WhaleTx {
  txHash: string;
  from: string;
  to: string;
  tokenAddress: string;
  amountUSD: number;
  labels: {
    from: string | null; // "Binance Hot Wallet", "Smart Money #42"
    to: string | null;
  };
  txType: "cex_deposit" | "cex_withdraw" | "dex_swap" | "wallet_transfer" | "unknown";
}

async function classifyTransaction(tx: RawTransferEvent): Promise<WhaleTx | null> {
  // Threshold: minimum $500k for top tokens, $50k for long-tail
  const amountUSD = await priceService.toUSD(tx.token, tx.amount);
  if (amountUSD < WHALE_THRESHOLD_USD) return null;

  const [fromLabel, toLabel] = await Promise.all([
    labelResolver.resolve(tx.from),
    labelResolver.resolve(tx.to),
  ]);

  const txType = inferTxType(fromLabel, toLabel);

  return { txHash: tx.hash, from: tx.from, to: tx.to,
           tokenAddress: tx.token, amountUSD, labels: { from: fromLabel, to: toLabel }, txType };
}

function inferTxType(fromLabel: string | null, toLabel: string | null): WhaleTx["txType"] {
  if (CEX_LABELS.some((l) => toLabel?.includes(l))) return "cex_deposit";
  if (CEX_LABELS.some((l) => fromLabel?.includes(l))) return "cex_withdraw";
  if (DEX_LABELS.some((l) => fromLabel?.includes(l) || toLabel?.includes(l))) return "dex_swap";
  return "unknown";
}

Address Cluster Definition

One of complex tasks — understand that multiple addresses belong to one entity. Heuristics:

• Dust attack / common input ownership (for UTXO chains)
• Nonce-based clustering: addresses funded from single source
• Temporal correlation: addresses always moving funds in same block or with small lag

For EVM: if address A often sends gas to address B before B's transactions — probably A and B one owner.

Telegram Notification

async function sendWhaleAlert(tx: WhaleTx, bot: TelegramBot) {
  const emoji = tx.txType === "cex_deposit" ? "🔴" : tx.txType === "cex_withdraw" ? "🟢" : "🔵";
  const fromStr = tx.labels.from ?? shortenAddress(tx.from);
  const toStr = tx.labels.to ?? shortenAddress(tx.to);

  const message = [
    `${emoji} <b>Whale Alert</b>`,
    ``,
    `<b>Amount:</b> $${formatUSD(tx.amountUSD)}`,
    `<b>From:</b> ${fromStr}`,
    `<b>To:</b> ${toStr}`,
    `<b>Type:</b> ${tx.txType}`,
    ``,
    `<a href="https://etherscan.io/tx/${tx.txHash}">View on Etherscan</a>`,
  ].join("\n");

  await bot.sendMessage(CHANNEL_ID, message, { parse_mode: "HTML" });
}

Noise Filtering

Without filtering bot will spam. Rules:

• Deduplication: one transaction → one notification (by txHash)
• Address cooldown: if address A already alerted 5 min ago — skip
• Blacklist technical addresses: protocol treasury multisigs, staking contracts
• Aggregation: if 10+ alerts same type come in 60 sec — send summary

What's Included in Development

• Event listener with reconnect support and catch-up of missed blocks
• Label cache with TTL (Nansen/Arkham data changes rarely, cache for 24h)
• Transaction classifier with extensible rules
• Telegram/Discord notification with formatting and deduplication
• Dashboard with alert history and threshold settings
• Support for watchlist of specific addresses (VIP tracking)