📋 Project Overview
A production-ready Node.js application that monitors the Ethereum blockchain in real-time, detecting and alerting on large transactions (whale movements). Built with WebSocket connections for instant block updates and comprehensive analytics tracking.
✨ Key Features
⚡ Real-Time Monitoring
Instant block scanning every ~12 seconds via Ethereum mainnet WebSocket connection
🐋 Whale Detection
Configurable threshold-based alerts for large ETH transfers (100+ ETH default)
📊 Live Analytics
Real-time statistics tracking with automatic reporting every 5 minutes
💰 USD Conversion
Automatic ETH to USD conversion for easy value assessment
🔔 Smart Alerts
Immediate console notifications with transaction details and addresses
⚙️ Environment Config
Secure API key management and customizable whale thresholds via .env
🛠️ Tech Stack
💻 Code Implementation
class WhaleTracker {
constructor() {
// Connect to Ethereum mainnet via Infura
this.provider = new ethers.JsonRpcProvider(
`https://mainnet.infura.io/v3/${process.env.INFURA_API_KEY}`
);
this.whaleThreshold = process.env.WHALE_THRESHOLD || 100; // ETH
this.stats = {
blocksScanned: 0,
whalesDetected: 0,
totalVolume: 0,
startTime: new Date()
};
}
// Check if transaction is whale-sized
isWhaleTransaction(valueWei) {
const valueEth = parseFloat(ethers.formatEther(valueWei));
return valueEth >= this.whaleThreshold;
}
// Display whale alert
displayWhale(tx, valueEth) {
console.log('\n' + '='.repeat(70));
console.log('🐋 WHALE DETECTED!');
console.log('='.repeat(70));
console.log(`💰 Amount: ${valueEth.toFixed(4)} ETH`);
console.log(`📤 From: ${tx.from || 'N/A'}`);
console.log(`📥 To: ${tx.to || 'N/A'}`);
console.log(`🔗 Hash: ${tx.hash}`);
console.log('='.repeat(70) + '\n');
this.stats.whalesDetected++;
this.stats.totalVolume += valueEth;
}
// Main monitoring function with WebSocket events
async start() {
this.log('🔍 Starting Crypto Whale Tracker...');
this.log('⏱️ Ethereum block time: ~12 seconds');
// Listen for new blocks
this.provider.on('block', async (blockNumber) => {
this.log(`📦 Scanning block #${blockNumber}...`);
this.stats.blocksScanned++;
const block = await this.provider.getBlock(blockNumber, true);
if (block && block.transactions) {
for (const tx of block.transactions) {
if (tx.value && this.isWhaleTransaction(tx.value)) {
const valueEth = parseFloat(ethers.formatEther(tx.value));
this.displayWhale(tx, valueEth);
}
}
}
});
}
}
🖥️ Live Terminal Output
🏗️ System Architecture
Event-Driven WebSocket Architecture
┌─────────────┐
│ User │
│ (Terminal) │
└──────┬──────┘
│
│ node index.js
▼
┌─────────────────────────────────┐
│ WhaleTracker Class │
│ ┌───────────────────────────┐ │
│ │ WebSocket Connection │ │
│ │ (ethers.JsonRpcProvider) │ │
│ └───────────┬───────────────┘ │
└──────────────┼──────────────────┘
│
│ wss://mainnet.infura.io
▼
┌──────────────────────────────────┐
│ Ethereum Mainnet (Infura) │
│ - New block every ~12 seconds │
│ - Full transaction data │
└──────────────┬───────────────────┘
│
│ Event: 'block'
▼
┌──────────────────────────────────┐
│ Block Processor │
│ - Fetch block details │
│ - Parse transactions │
│ - Check whale threshold │
└──────────────┬───────────────────┘
│
▼
Whale Found?
┌────┴────┐
YES NO
│ │
▼ ▼
┌─────────┐ Continue
│ ALERT! │ Monitoring
│ Console │
│ Output │
└─────────┘
Why WebSocket over REST API?
- ⚡ Real-time: Instant notifications vs polling delays
- 💰 Cost-effective: 1 connection vs 5 requests/minute
- 🎯 Efficient: Server pushes data vs client pulling
📊 Project Statistics
115
Lines of Code
~12s
Block Time
24M+
Ethereum Blocks
100%
Uptime Capable
🎯 Real-World Use Cases
- 📈 Trading Signals: Track whale movements to predict market trends and make informed trading decisions
- 🎨 NFT Research: Monitor high-value NFT purchases and marketplace activity for investment insights
- 🔍 DeFi Analytics: Analyze large liquidity movements across decentralized exchanges
- 🤖 Bot Development: Foundation for automated trading bots with whale detection triggers
- 📊 Market Intelligence: Build dashboards showing real-time blockchain activity patterns
🚧 Technical Challenges Solved
- Problem: Windows PowerShell output buffering causing delayed console logs
Solution: Implemented explicit stdout flushing and real-time logging helper methods - Problem: High-volume transaction data overwhelming the system
Solution: Efficient filtering at the block level before detailed transaction parsing - Problem: Infura API rate limiting on free tier
Solution: WebSocket persistent connection eliminates polling, stays within limits
⚙️ Quick Start
# Clone repository
git clone https://github.com/rahulkhunte/crypto-whale-tracker.git
cd crypto-whale-tracker
# Install dependencies
npm install
# Configure environment
# Create .env file with:
# INFURA_API_KEY=your_infura_api_key
# WHALE_THRESHOLD=100
# Run the tracker
node index.js