CtrlK
BlogDocsLog inGet started
Tessl Logo
SkillPublic

whale-tracking

Monitor whale trades on Polymarket and crypto chains (Solana, ETH, Polygon, ARB, Base, OP)

Quality

72%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide
SecuritybySnyk

Passed

No findings from the security scan

Fix and improve this skill with Tessl

tessl review fix ./src/skills/bundled/whale-tracking/SKILL.md
SKILL.md
Quality
Evals
Security

Whale Tracking - Complete API Reference

Monitor large trades and positions on Polymarket and crypto chains to identify market-moving activity.

Supported Platforms

Prediction Markets

  • Polymarket - WebSocket real-time trade monitoring

Crypto Chains

ChainProviderFeatures
SolanaBirdeye WebSocketToken transfers, swaps, NFTs
EthereumAlchemy WebSocketERC-20, ETH transfers
PolygonAlchemy WebSocketMATIC, tokens
ArbitrumAlchemy WebSocketL2 activity
BaseAlchemy WebSocketCoinbase L2
OptimismAlchemy WebSocketOP ecosystem

Chat Commands

General

/whale                                      # Active whale alerts summary
/whale start                                # Start whale monitoring
/whale stop                                 # Stop monitoring
/whale config                               # Tracking configuration
/whale list                                 # List tracked wallets

Tracking Wallets

/whale track <address>                      # Follow specific wallet
/whale untrack <address>                    # Stop following wallet
/whale watch <address> [--chain c]          # Track an address (same as track)
/whale unwatch <address>                    # Stop tracking (same as untrack)

Polymarket Whale Activity

/whale polymarket [n]                       # Recent Polymarket whale trades
/whale polymarket market <id>               # Whale activity for a market
/whale activity <market>                    # Whale activity for market
/whale recent [n] [--min-size N]            # Last N whale trades
/whale top [n]                              # Top Polymarket whales
/whale profitable [wr%] [min-n]             # Profitable whales
/whale profile <address>                    # Whale profile + positions
/whale positions [market-id]                # Active whale positions

Crypto Whale Tracking

/whale crypto [chain] [n]                   # On-chain whale txs
/whale top crypto [chain] [n]               # Top on-chain whales

Note: /whales also works as an alias for /whale.


TypeScript API Reference

Polymarket Whale Tracker

import { createWhaleTracker, isWhaleAddress, getMarketWhaleActivity } from 'clodds/feeds/polymarket/whale-tracker';

// Create tracker
const tracker = createWhaleTracker({
  minTradeSize: 10000,      // $10k+ trades
  minPositionSize: 50000,   // $50k+ positions
  enableRealtime: true,     // WebSocket streaming
});

// Event handlers
tracker.on('trade', (trade) => {
  console.log(`🐋 Whale ${trade.side} $${trade.usdValue.toLocaleString()}`);
  console.log(`   Market: ${trade.marketQuestion}`);
  console.log(`   Address: ${trade.address}`);
  console.log(`   Price: ${trade.price}`);
});

tracker.on('positionOpened', (position) => {
  console.log(`📈 New whale position`);
  console.log(`   Address: ${position.address}`);
  console.log(`   Market: ${position.market}`);
  console.log(`   Size: $${position.size.toLocaleString()}`);
});

tracker.on('positionClosed', (position) => {
  console.log(`📉 Whale exited position`);
  console.log(`   P&L: $${position.pnl.toLocaleString()}`);
});

// Start tracking
await tracker.start();

// Track specific wallet
await tracker.trackAddress('0x1234...');
await tracker.untrackAddress('0x1234...');

// Get tracked addresses
const tracked = tracker.getTrackedAddresses();

// Stop tracking
await tracker.stop();

Check Whale Status

// Check if address is a whale
const isWhale = await isWhaleAddress('0x1234...', 100000);  // $100k min volume

// Get whale activity for a market
const activity = await getMarketWhaleActivity('market-slug');

console.log(`Total whale volume: $${activity.totalVolume.toLocaleString()}`);
console.log(`Whale trades: ${activity.tradeCount}`);
console.log(`Net whale sentiment: ${activity.sentiment}`);  // 'bullish' | 'bearish' | 'neutral'
console.log(`Top whales:`);
for (const whale of activity.topWhales) {
  console.log(`  ${whale.address}: $${whale.volume.toLocaleString()}`);
}

Top Traders

// Get top traders
const topTraders = await tracker.getTopTraders({
  period: '7d',           // 24h, 7d, 30d, all
  limit: 10,
  minVolume: 50000,
  minWinRate: 0.5,
});

for (const trader of topTraders) {
  console.log(`${trader.rank}. ${trader.address}`);
  console.log(`   Volume: $${trader.volume.toLocaleString()}`);
  console.log(`   Win rate: ${(trader.winRate * 100).toFixed(1)}%`);
  console.log(`   P&L: $${trader.pnl.toLocaleString()}`);
}

Crypto Whale Tracker

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

// Create multi-chain tracker
const cryptoTracker = createCryptoWhaleTracker({
  chains: ['solana', 'ethereum', 'polygon', 'arbitrum', 'base', 'optimism'],

  thresholds: {
    solana: 10000,      // $10k+ on Solana
    ethereum: 50000,    // $50k+ on ETH
    polygon: 5000,      // $5k+ on Polygon
    arbitrum: 10000,    // $10k+ on Arbitrum
    base: 10000,        // $10k+ on Base
    optimism: 10000,    // $10k+ on Optimism
  },

  // API keys
  birdeyeApiKey: process.env.BIRDEYE_API_KEY,
  alchemyApiKey: process.env.ALCHEMY_API_KEY,
});

// Event handlers
cryptoTracker.on('transaction', (tx) => {
  console.log(`🐋 ${tx.chain.toUpperCase()}`);
  console.log(`   Type: ${tx.type}`);  // 'transfer', 'swap', 'nft', 'stake'
  console.log(`   Amount: $${tx.usdValue.toLocaleString()}`);
  console.log(`   From: ${tx.from}`);
  console.log(`   To: ${tx.to}`);
  console.log(`   Token: ${tx.token}`);
  console.log(`   TX: ${tx.hash}`);
});

cryptoTracker.on('largeTransfer', (tx) => {
  console.log(`🚨 LARGE TRANSFER: $${tx.usdValue.toLocaleString()}`);
});

// Start tracking
await cryptoTracker.start();

// Watch specific wallets
await cryptoTracker.watchWallet('solana', 'ABC123...');
await cryptoTracker.watchWallet('ethereum', '0x1234...');

// Unwatch
await cryptoTracker.unwatchWallet('solana', 'ABC123...');

// Get recent whale transactions
const recent = await cryptoTracker.getRecentTransactions('solana', {
  limit: 20,
  minValue: 50000,
});

// Get top whales by chain
const topSolana = await cryptoTracker.getTopWhales('solana', 10);
const topEth = await cryptoTracker.getTopWhales('ethereum', 10);

// Stop
await cryptoTracker.stop();

Alert Configuration

Polymarket Alerts

// Configure alerts
tracker.setAlertConfig({
  minTradeSize: 25000,      // Alert on $25k+ trades
  alertChannels: ['telegram', 'discord'],
  soundEnabled: true,
  markets: ['politics', 'crypto'],  // Filter by category
});

Crypto Alerts

// Configure per-chain alerts
cryptoTracker.setAlertConfig({
  solana: {
    minValue: 50000,
    tokens: ['SOL', 'JUP', 'BONK'],
  },
  ethereum: {
    minValue: 100000,
    tokens: ['ETH', 'USDC', 'PEPE'],
  },
});

Data Export

// Export whale data to CSV
await tracker.exportTrades({
  format: 'csv',
  path: './whale-trades.csv',
  period: '30d',
});

// Export top traders
await tracker.exportTopTraders({
  format: 'json',
  path: './top-traders.json',
  limit: 100,
});

Best Practices

  1. Set reasonable thresholds - Start with $10k for active markets
  2. Focus on specific markets - Filter by category to reduce noise
  3. Track known smart money - Follow wallets with proven track records
  4. Combine with copy trading - Use whale data to inform copy decisions
  5. Monitor sentiment shifts - Watch for net whale direction changes
  6. Check position sizes - Large positions signal conviction
Repository

alsk1992/CloddsBot

Path

src/skills/bundled/whale-tracking/SKILL.md

Last updated
First committed

Is this your skill?

If you maintain this skill, you can claim it as your own. Once claimed, you can manage eval scenarios, bundle related skills, attach documentation or rules, and ensure cross-agent compatibility.