/whale-tracking

name: whale-tracking
description: "Monitor whale trades on Polymarket and crypto chains (Solana, ETH, Polygon, ARB, Base, OP)"
emoji: "🐋"
gates:
  envs:
    anyOf:
      - POLY_API_KEY
      - BIRDEYE_API_KEY
      - ALCHEMY_API_KEY

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

| Chain | Provider | Features | |-------|----------|----------| | Solana | Birdeye WebSocket | Token transfers, swaps, NFTs | | Ethereum | Alchemy WebSocket | ERC-20, ETH transfers | | Polygon | Alchemy WebSocket | MATIC, tokens | | Arbitrum | Alchemy WebSocket | L2 activity | | Base | Alchemy WebSocket | Coinbase L2 | | Optimism | Alchemy WebSocket | OP 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.lo