How to Configure Thresholds and Copy-Trading Signals in the CloddsBot Whale Tracking Module

Configure thresholds and copy-trading signals in the CloddsBot whale tracking module by editing the whaleTracking and copyTrading sections in src/utils/config.ts, where you define minimum trade sizes, position thresholds, wallet addresses to mirror, and sizing strategies for automated replication.

The CloddsBot repository provides a sophisticated whale tracking system that monitors high-volume traders across platforms like Polymarket and on-chain markets. By configuring the whaleTracking and copyTrading sections in src/utils/config.ts, you can precisely control which trades qualify as whale activity and how the bot mirrors those positions in real time.

Configuring Whale Tracking Thresholds

The whale tracking subsystem uses a dedicated whaleTracking configuration object located in src/utils/config.ts (starting at L220) to filter market activity. These settings determine which trades generate signals for the copy-trading engine.

Enabling the Module and Platform Selection

To activate whale monitoring, set enabled to true in the whaleTracking block. By default, this value is false (L220). The platforms array (L224) specifies which market feeds to monitor, defaulting to ['polymarket']. You can extend this to include additional supported exchanges or blockchain feeds as implemented in src/feeds/polymarket/whale-tracker.ts and src/feeds/crypto/whale-tracker.ts.

The realtime boolean (L225) controls the data ingestion method. When set to true, the tracker uses live websocket updates. If disabled, the system falls back to polling every pollIntervalMs milliseconds (default 30000 at L226).

Setting Volume and Position Thresholds

Two critical thresholds filter incoming trades:

• minTradeSize (L222): The minimum USD volume for a single trade to be treated as a "whale" trade. The default is 10000 USD. Trades below this value are ignored entirely.
• minPositionSize (L223): The minimum USD size of an accumulated position before it is recorded for whale tracking. The default is 50000 USD.

Only trades that exceed both thresholds generate a whale-trade event that propagates to the copy-trading engine.

Copy-Trading Signal Configuration

Once a whale trade passes the threshold filters, the copyTrading configuration block (L28-37) and realtimeAlerts.copyTrading sub-section (L73-75) determine how the bot reacts and notifies you.

Sizing Modes and Position Management

The sizingMode parameter (L32) accepts either 'fixed' or 'proportional', determining how the bot calculates mirrored trade sizes:

• Fixed mode: Uses the fixedSize value (default 100 USD at L33) for every copy trade regardless of the whale's position size.
• Proportional mode: Multiplies the whale's trade size by the proportionalMultiplier (default 0.1 representing 10% at L34).

Risk management is enforced through portfolioPercentage (L35), which limits a single copy-trade to a percentage of total equity (default 1%), and maxPositionSize (L36), which caps any mirrored position at 500 USD by default.

Additional critical settings include:

• enabled (L28): Master switch for the copy-trading engine. Note that this still requires whaleTracking.enabled to be true.
• dryRun (L30): When true, the bot simulates trades without submitting real orders to the exchange.
• followedAddresses (L31): An array of specific wallet addresses to mirror. When empty, the system may copy any whale meeting threshold criteria depending on implementation details in src/trading/copy-trading.ts.
• copyDelayMs (L37): The minimum delay between detecting a whale signal and executing the copy order, defaulting to 5000 milliseconds.

Alert and Notification Settings

The realtimeAlerts.copyTrading object controls notification behavior:

• enabled (L73): Master toggle for copy-trading alerts.
• onCopied (L74): Emits a notification when a whale trade is successfully copied.
• onFailed (L75): Emits a notification when copying fails, such as due to insufficient balance.

These alerts are processed by src/alerts/realtime.ts.

Practical Configuration Example

Below is a complete configuration example that enables whale tracking for Polymarket with a $50,000 minimum trade size, enables proportional copy-trading at 5% of whale size, and restricts copying to specific whale wallets:

// src/utils/config.ts
export const config = {
  whaleTracking: {
    enabled: true,              // L220: Enable the subsystem
    minTradeSize: 50000,        // L222: Only trades > $50k
    minPositionSize: 100000,    // L223: Track positions > $100k
    platforms: ['polymarket'],  // L224: Monitor Polymarket only
    realtime: true,             // L225: Use websockets
    pollIntervalMs: 30000       // L226: Fallback poll interval
  },
  copyTrading: {
    enabled: true,              // L28: Enable copy-trading
    dryRun: false,              // L30: Execute real trades
    followedAddresses: [        // L31: Whitelist specific whales
      '0x1234...abcd',
      '0x5678...efgh'
    ],
    sizingMode: 'proportional', // L32: Mirror percentage of whale size
    fixedSize: 100,             // L33: Unused in proportional mode
    proportionalMultiplier: 0.05, // L34: Copy 5% of whale trade
    portfolioPercentage: 2,       // L35: Max 2% of portfolio per trade
    maxPositionSize: 1000,      // L36: Hard cap at $1000
    copyDelayMs: 5000           // L37: 5 second execution delay
  },
  realtimeAlerts: {
    copyTrading: {
      enabled: true,              // L73: Enable alerts
      onCopied: true,             // L74: Notify on success
      onFailed: true              // L75: Notify on failure
    }
  }
};

How the System Processes Thresholds and Signals

The whale tracking and copy-trading pipeline flows through four main components:

1. Detection: src/feeds/polymarket/whale-tracker.ts and src/feeds/crypto/whale-tracker.ts ingest market data from the platforms specified in whaleTracking.platforms.

2. Threshold Filtering: Each incoming trade is compared against minTradeSize and minPositionSize. Only trades exceeding both thresholds generate a whale-trade event.

3. Signal Generation: src/trading/copy-trading.ts receives validated whale events, checks the followedAddresses whitelist, applies the configured sizingMode calculation, and produces a copy-trading signal with calculated position size.

4. Alert Emission: Signals are forwarded to src/alerts/realtime.ts, which respects the realtimeAlerts.copyTrading flags to emit onCopied or onFailed notifications to the bot user.

Summary

• Configure whale tracking thresholds in the whaleTracking section of src/utils/config.ts to define minimum trade sizes, position requirements, and data source platforms.
• Set minTradeSize to filter which individual trades qualify as whale activity (default $10,000).
• Configure copy-trading behavior in the copyTrading block (L28-37) using sizingMode to choose between fixed amounts or proportional replication.
• Use followedAddresses to whitelist specific wallets and maxPositionSize to enforce hard caps on mirrored positions.
• Enable real-time alerts via realtimeAlerts.copyTrading (L73-75) to receive notifications on successful copies or execution failures.

Frequently Asked Questions

What is the minimum trade size required to trigger a whale signal?

By default, the minTradeSize parameter is set to 10000 USD (L222). Only trades with a notional value exceeding this threshold will generate a whale-trade event that propagates to the copy-trading engine. You can increase this value to filter for larger, more significant market participants.

How do I switch from fixed to proportional copy-trading sizing?

Change the sizingMode value from 'fixed' to 'proportional' in src/utils/config.ts at L32. In proportional mode, the bot multiplies the original whale's trade size by the proportionalMultiplier (default 0.1 or 10%) to determine your position size. Ensure you adjust proportionalMultiplier to match your risk tolerance.

Can I whitelist specific wallets to copy instead of all whales meeting the threshold?

Yes. Populate the followedAddresses array in the copyTrading configuration (L31) with the specific wallet addresses you want to mirror. When this array contains entries, src/trading/copy-trading.ts typically filters incoming whale events to process only those originating from addresses in your whitelist.

What happens when a copy trade fails to execute?

When a copy trade fails—due to insufficient balance, exchange errors, or position limits exceeding maxPositionSize—the system checks realtimeAlerts.copyTrading.onFailed (L75). If set to true, src/alerts/realtime.ts emits a notification detailing the failure reason, allowing you to monitor execution issues without checking exchange logs manually.

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