// Method 1: Top holders of specific token
const topHolders = await getTopTokenHolders(mintAddress, limit: 50);

// Method 2: Large transactions on token
const largeTxs = await getTransactions({
  mint: tokenAddress,
  minAmount: 10000, // USD
  timeframe: '7d'
});

// Method 3: Known whale lists (curated)
const knownWhales = [
  'whale1...abc', // Known trader
  'whale2...def', // VC wallet
  // ...
];

// Method 4: Wallet clustering from token launches
const earlyBuyers = await getEarlyBuyers(tokenAddress, firstNMinutes: 30);

interface WalletProfile {
  address: string;
  firstActivity: Date;
  totalTransactions: number;

  // Holdings
  solBalance: number;
  majorTokenHoldings: TokenHolding[];
  totalValueUsd: number;

  // Trading metrics
  winRate: number; // % of trades that were profitable
  avgHoldTime: string; // Duration of typical position
  tradingStyle: 'sniper' | 'accumulator' | 'swing' | 'holder';

  // Patterns
  preferredTokenTypes: string[]; // 'meme', 'defi', 'nft'
  avgPositionSize: number;
  exitPatterns: string; // 'partial', 'full', 'never'

  // Relationships
  fundingSource: string; // CEX, other wallet, etc.
  relatedWallets: string[];
  clusterConfidence: number;
}

// For each token the wallet traded:
interface TradePerformance {
  token: string;
  entryTime: Date;
  exitTime: Date | null;
  entryPrice: number;
  exitPrice: number | null;
  pnlPercent: number;
  holdDuration: string;
  entryTiming: 'early' | 'mid' | 'late'; // Relative to price peak
}

// Aggregate metrics:
interface WalletPerformance {
  totalTrades: number;
  winRate: number;
  avgReturn: number;
  medianReturn: number;
  bestTrade: TradePerformance;
  worstTrade: TradePerformance;
  sharpeRatio: number; // Risk-adjusted return
  avgEntryTiming: string; // How early vs peak
}

// Clustering signals:
const clusteringIndicators = {
  sameFundingSource: 0.9,    // Very strong signal
  similarTiming: 0.6,        // Strong signal
  sameTokenPicks: 0.4,       // Moderate signal
  sameExitTiming: 0.7,       // Strong signal
  roundNumberTransfers: 0.8, // Between cluster wallets
};

// Algorithm:
// 1. Build funding graph (who funded whom)
// 2. Build timing graph (who buys within N seconds of whom)
// 3. Find connected components
// 4. Score confidence based on overlap

Wallet A funded from Binance withdrawal
  └─> Wallet B (received 50 SOL from A)
      └─> Wallet C (received 25 SOL from B)

All three buy $MEME within 2 minutes
Cluster confidence: 95%
Treat as single entity with 75 SOL exposure

interface WhaleAlert {
  // Trigger conditions
  wallet: string;
  action: 'buy' | 'sell' | 'transfer';
  minAmount: number; // USD
  tokens: string[] | 'any';

  // Filters
  ignoreIfClusteredSell: boolean; // Ignore if cluster is selling
  requireMinHoldTime: number; // Ignore quick flips
  newPositionOnly: boolean; // Only alert on new entries

  // Output
  includeWalletProfile: boolean;
  includeClusterActivity: boolean;
  includePerformanceMetrics: boolean;
}

undefined

undefined

undefined

undefined

🐋 WHALE ALERT

Wallet: [SHORT_ADDRESS]
Action: [BOUGHT/SOLD] [AMOUNT] [TOKEN]
Value: $[USD_VALUE]
Time: [TIMESTAMP UTC]

Wallet Profile:
- Win rate: [X]%
- Style: [type]
- This token: [new position/adding/reducing]

Context:
- Token MC: $[X] → $[Y] ([+/-X]% since trade)
- Whale's avg entry: $[X]
- Whale's P/L on position: [+/-X]%

Cluster Activity:
- [N] related wallets [also buying/holding/selling]

[Explorer Link]

undefined

undefined

undefined

undefined