How the Multi-Chain Whale Tracking Module Monitors Solana, Ethereum, and Polygon

The Crypto Whale Tracker in CloddsBot unifies real-time WebSocket streams and periodic RPC polling across Solana, Ethereum, and Polygon into a single event-driven service that normalizes large transfers and wallet updates through a common transaction processing pipeline.

The multi-chain whale tracking module in the CloddsBot repository aggregates high-value cryptocurrency movements across disparate blockchain networks. By abstracting chain-specific APIs—such as Birdeye for Solana and Alchemy for EVM networks—into a generic WhaleTransaction model, the system provides real-time alerts and wallet monitoring through a unified TypeScript interface defined in src/feeds/crypto/whale-tracker.ts.

Configuration and Chain Registry

The module establishes chain-agnostic operations through a strict type system and configuration object. It defines a Chain union type that restricts supported networks to 'solana' | 'ethereum' | 'polygon' | 'arbitrum' | 'base' | 'optimism', ensuring type safety throughout the codebase.

The CHAIN_CONFIG object stores each chain’s native token metadata, decimals, and explorer URLs. This registry allows the multi-chain whale tracking logic to remain agnostic to specific chain implementations while still accessing network-specific details when rendering alerts or building transaction links.

export type Chain = 'solana' | 'ethereum' | 'polygon' | 'arbitrum' | 'base' | 'optimism';
export const CHAIN_CONFIG = {
  solana: { nativeToken: 'SOL', symbol: 'SOL', decimals: 9, explorer: 'https://solscan.io' },
  ethereum: { nativeToken: 'ETH', symbol: 'ETH', decimals: 18, explorer: 'https://etherscan.io' },
  polygon: { nativeToken: 'MATIC', symbol: 'MATIC', decimals: 18, explorer: 'https://polygonscan.com' }
};

Solana Monitoring via Birdeye and Helius

For Solana specifically, the tracker implements a hybrid approach combining WebSocket-driven real-time data with periodic REST polling. This dual strategy ensures immediate detection of large trades while maintaining accurate wallet balance states.

Real-Time Trade WebSocket

When a Birdeye API key is provided, the tracker initializes a WebSocket connection to wss://public-api.birdeye.so/socket. It immediately subscribes to two critical channels: SUBSCRIBE_LARGE_TRADE_TXS for market-wide large transfers exceeding the configured minimum USD threshold, and SUBSCRIBE_WALLET_TXS for transactions involving specifically watched wallets.

Incoming WebSocket messages are parsed by the parseSolanaTransaction helper and injected into the generic processTransaction pipeline, ensuring Solana events undergo the same normalization and alerting logic as EVM chains.

const ws = new WebSocket(BIRDEYE_WS, { headers: { 'X-API-KEY': apiKey } });

ws.send(JSON.stringify({
  type: 'SUBSCRIBE_LARGE_TRADE_TXS',
  data: { minUsd: cfg.minTxValueUsd }
}));

ws.send(JSON.stringify({
  type: 'SUBSCRIBE_WALLET_TXS',
  data: { wallet: address }
}));

Periodic Wallet Polling

Complementing the WebSocket stream, the pollSolanaWallets function executes every cfg.pollIntervalMs (defaulting to 30 seconds). This routine queries Birdeye’s /v1/wallet/token_list endpoint to fetch current token holdings for each watched address, computes total USD value, and updates the internal watchedWallets Map.

const response = await fetchWithRetry(
  `${BIRDEYE_API}/v1/wallet/token_list?wallet=${wallet.address}`,
  { headers: { 'X-API-KEY': apiKey } }
);

EVM Chain Monitoring via Alchemy

For Ethereum, Polygon, and other EVM-compatible chains, the multi-chain whale tracking module relies entirely on Alchemy’s enhanced RPC endpoints. The startEvmTracking function initializes independent polling loops for each configured chain via setInterval triggers.

Wallet Balance Tracking

The fetchEvmWallet function retrieves comprehensive portfolio data by calling Alchemy’s alchemy_getTokenBalances method for ERC-20 tokens and eth_getBalance for native gas tokens. These results are normalized into TokenHolding objects and cached in the watchedWallets registry, enabling accurate net-worth calculations for whale rankings.

const baseUrl = getAlchemyUrl(chain, alchemyKey);

const tokenResponse = await fetchWithRetry(baseUrl, {
  method: 'POST',
  body: JSON.stringify({
    jsonrpc: '2.0',
    method: 'alchemy_getTokenBalances',
    params: [walletAddress, 'erc20']
  })
});

const nativeResponse = await fetchWithRetry(baseUrl, {
  method: 'POST',
  body: JSON.stringify({
    jsonrpc: '2.0',
    method: 'eth_getBalance',
    params: [walletAddress, 'latest']
  })
});

Large Transaction Detection

To detect whale movements across Ethereum and Polygon, the tracker utilizes Alchemy’s alchemy_getAssetTransfers RPC method. The pollEvmChain function fetches transfer history from the most recent 100 blocks, filters for transactions exceeding the minTxValueUsd threshold, constructs standardized WhaleTransaction objects, and forwards them to the unified processing pipeline.

const transferResponse = await fetchWithRetry(baseUrl, {
  method: 'POST',
  body: JSON.stringify({
    jsonrpc: '2.0',
    method: 'alchemy_getAssetTransfers',
    params: [{
      fromBlock: 'latest',
      toAddress: watchedWallets.keys(),
      category: ['external', 'erc20', 'erc721']
    }]
  })
});

Unified Transaction Processing Pipeline

All data sources—Solana WebSocket events, Solana polling results, and EVM transfer logs—converge in the processTransaction function. This central handler maintains a bounded recentTransactions array to prevent memory leaks, emits normalized events through an EventEmitter interface, and triggers alert generation based on USD value thresholds.

When processing a transaction, the system evaluates whether the transferred amount constitutes a sizable fraction of the configured whale threshold. If so, it automatically adds the wallet to the tracking registry via auto-tracking logic. The function also categorizes transactions into types such as large_transfer, whale_buy, or whale_sell for downstream consumers.

recentTransactions.unshift(tx);
if (recentTransactions.length > 1000) recentTransactions.pop();

emitter.emit('transaction', tx);

if (tx.usdValue > cfg.alertThreshold) {
  generateAlert('large_transfer', tx);
}

Public API and Event Interface

The createCryptoWhaleTracker factory function, located in src/feeds/crypto/whale-tracker.ts, exposes a programmatic interface for integrating the multi-chain whale tracking module into external services such as the REST gateway defined in src/gateway/whale-routes.ts.

The returned object extends EventEmitter and provides methods including start(), stop(), watchWallet(address, chain), getWallet(address), getRecentTransactions(), and getStats(). Consumers subscribe to three primary event types:

• transaction – Emitted for every processed large transfer across any chain
• alert – High-priority notifications exceeding configured thresholds
• walletUpdate – Periodic balance recalculations for tracked addresses

import { createCryptoWhaleTracker } from './feeds/crypto/whale-tracker';

const tracker = createCryptoWhaleTracker({
  chains: ['solana', 'ethereum', 'polygon'],
  minTxValueUsd: 75_000,
  apiKeys: {
    birdeye: process.env.BIRDEYE_KEY,
    alchemy: process.env.ALCHEMY_KEY
  },
  watchedAddresses: ['8Z9kR…', '0xAbC123…']
});

tracker.on('alert', (alert) => console.log('🐋', alert.message));
tracker.start();

Summary

• Chain Abstraction – The Chain union type and CHAIN_CONFIG registry enable the multi-chain whale tracking module to support Solana, Ethereum, Polygon, and other networks through a unified interface.
• Hybrid Solana Strategy – Combines Birdeye WebSocket subscriptions for real-time large trades with periodic REST polling for accurate wallet balance tracking.
• EVM Polling Architecture – Uses Alchemy’s alchemy_getTokenBalances and alchemy_getAssetTransfers RPC methods to monitor Ethereum and Polygon via consistent polling intervals.
• Normalized Processing – The processTransaction function standardizes inputs from all chains into WhaleTransaction objects, manages a bounded history buffer, and emits categorized alerts.
• Auto-Tracking – Automatically identifies and monitors new whale wallets when transaction values exceed fractional thresholds of the alert limit.

Frequently Asked Questions

How does the tracker handle different blockchain APIs uniformly?

The multi-chain whale tracking module abstracts chain-specific implementations behind the processTransaction function and WhaleTransaction model. While Solana uses Birdeye WebSockets and REST endpoints, and EVM chains use Alchemy JSON-RPC calls, both feed into the same normalization pipeline. The Chain type system ensures that chain-specific metadata (such as explorer URLs and decimal places) is available when formatting alerts, but the core detection logic remains agnostic to the underlying network protocol.

What triggers a whale alert in the system?

A whale alert generates when a transaction's usdValue exceeds the configurable alertThreshold parameter. The generateAlert function categorizes the event as large_transfer, whale_buy, or whale_sell based on transaction direction and wallet holdings. Additionally, the system auto-tracks new wallets when a transfer represents a significant fraction of the whale threshold, automatically adding the address to the watchedWallets registry for continuous monitoring.

How are Solana and EVM monitoring strategies different?

Solana monitoring employs a push-based WebSocket architecture via Birdeye for immediate trade notifications, supplemented by periodic polling for balance accuracy. In contrast, the Ethereum and Polygon implementation uses purely pull-based architecture, repeatedly querying Alchemy’s alchemy_getAssetTransfers and alchemy_getTokenBalances RPC methods at fixed intervals. This distinction reflects the differing availability of real-time streaming APIs across these blockchain ecosystems.

Can the module track custom wallet addresses across multiple chains simultaneously?

Yes. The createCryptoWhaleTracker factory accepts a watchedAddresses array and chain-specific configurations. The watchWallet(address, chain) method allows runtime addition of addresses to specific chain registries. The internal watchedWallets Map maintains separate entries for each chain, enabling simultaneous tracking of the same address across Solana, Ethereum, and Polygon if that address exists on multiple networks.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}