copy-trading

# Copy Trading - Complete API Reference Automatically mirror trades from successful wallets with configurable sizing, delays, and risk controls. ## Features - **Follow whale wallets** on Polymarket and crypto chains - **Configurable sizing**: Fixed, proportional, or % of portfolio - **Trade delay** to avoid detection and front-running - **Risk limits**: Max position, daily loss limits - **Stop-loss / Take-profit** monitoring with auto-exit --- ## Chat Commands ### Following Wallets ``` /copy follow <address> # Start following a wallet /copy follow 0x1234... --size 100 # Follow with $100 fixed size /copy follow 0x1234... --size 50% # Follow with 50% of their size /copy follow 0x1234... --delay 30 # 30 second delay before copying /copy unfollow <address> # Stop following /copy list # List followed wallets /copy status # Show copy trading status ``` ### Sizing Modes ``` /copy size <address> fixed 100 # Always trade $100 /copy size <address> proportional 0.5 # 50% of their size /copy size <address> portfolio 5% # 5% of your portfolio ``` ### Risk Controls ``` /copy limits --max-position 1000 # Max $1000 per position /copy limits --daily-loss 500 # Stop after $500 daily loss /copy limits --max-trades 20 # Max 20 trades per day /copy sl <address> 10% # 10% stop-loss on copies /copy tp <address> 20% # 20% take-profit on copies ``` ### Discovery ``` /copy top 10 # Top 10 traders to copy /copy top 10 --min-winrate 60 # Min 60% win rate /copy top 10 --min-volume 100000 # Min $100k volume /copy analyze <address> # Analyze a trader's performance ``` --- ## TypeScript API Reference ### Create Copy Trading Service ```typescript import { createCopyTradingService } from 'clodds/trading/copy-trading'; const copyTrader = createCopyTradingService({ // Polymarket credentials polymarket: { apiKey: process.env.POLY_API_KEY, apiSecret: process.env.POLY_API_SECRET, passphrase: process.env.POLY_API_PASSPHRASE, privateKey: process.env.PRIVATE_KEY, }, // Default settings defaults: { sizingMode: 'proportional', sizingValue: 0.5, // 50% of their size delaySeconds: 15, // 15s delay maxPositionSize: 1000, // $1000 max stopLossPct: 10, // 10% stop-loss takeProfitPct: 25, // 25% take-profit }, // Risk limits limits: { maxDailyLoss: 500, maxDailyTrades: 20, maxTotalExposure: 5000, }, }); ``` ### Follow Wallets ```typescript // Follow a wallet with default settings await copyTrader.follow('0x1234...'); // Follow with custom settings await copyTrader.follow('0x1234...', { sizingMode: 'fixed', sizingValue: 100, // $100 per trade delaySeconds: 30, // 30s delay stopLossPct: 15, // 15% stop-loss takeProfitPct: 30, // 30% take-profit // Filters minTradeSize: 50, // Only copy trades > $50 maxTradeSize: 5000, // Skip trades > $5000 markets: ['politics'], // Only copy politics markets }); // Unfollow await copyTrader.unfollow('0x1234...'); // List followed const followed = await copyTrader.listFollowed(); ``` ### Sizing Modes ```typescript // Fixed: Always trade same dollar amount await copyTrader.follow(address, { sizingMode: 'fixed', sizingValue: 100, // Always $100 }); // Proportional: Percentage of their trade size await copyTrader.follow(address, { sizingMode: 'proportional', sizingValue: 0.5, // 50% of their size }); // Portfolio: Percentage of your portfolio await copyTrader.follow(address, { sizingMode: 'portfolio', sizingValue: 0.05, // 5% of portfolio per trade }); ``` ### Event Handling ```typescript copyTrader.on('trade_copied', (event) => { console.log(`Copied ${event.side} on ${event.market}`); console.log(`Original: $${event.originalSize}, Copied: $${event.copiedSize}`); }); copyTrader.on('stop_loss_triggered', (event) => { console.log(`Stop-loss hit on ${event.market}`); console.log(`Loss: $${event.loss}`); }); copyTrader.on('take_profit_triggered', (event) => { console.log(`Take-profit hit on ${event.market}`); console.log(`Profit: $${event.profit}`); }); copyTrader.on('limit_reached', (event) => { console.log(`Limit reached: ${event.type}`); }); ``` ### Start/Stop ```typescript // Start copy trading (monitors followed wallets) await copyTrader.start(); // Stop copy trading await copyTrader.stop(); // Get status const status = copyTrader.getStatus(); console.log(`Following: ${status.followedCount} wallets`); console.log(`Today's P&L: $${status.dailyPnl}`); console.log(`Active positions: ${status.activePositions}`); ``` ### Find Best Traders ```typescript import { findBestAddressesToCopy } from 'clodds/trading/copy-trading'; // Find top traders const topTraders = await findBestAddressesToCopy({ minWinRate: 0.6, // 60%+ win rate minVolume: 100000, // $100k+ volume minTrades: 50, // 50+ trades timeframeDays: 30, // Last 30 days limit: 10, // Top 10 }); for (const trader of topTraders) { console.log(`${trader.address}`); console.log(` Win rate: ${(trader.winRate * 100).toFixed(1)}%`); console.log(` Volume: $${trader.totalVolume.toLocaleString()}`); console.log(` P&L: $${trader.pnl.toLocaleString()}`); console.log(` Trades: ${trader.tradeCount}`); } ``` ### Analyze Trader ```typescript const analysis = await copyTrader.analyzeTrader('0x1234...'); console.log(`Win rate: ${analysis.winRate}%`); console.log(`Avg trade size: $${analysis.avgTradeSize}`); console.log(`Best market: ${analysis.bestMarket}`); console.log(`Worst market: ${analysis.worstMarket}`); console.log(`Avg hold time: ${analysis.avgHoldTime} hours`); console.log(`Sharpe ratio: ${analysis.sharpeRatio}`); ``` --- ## Risk Management ### Stop-Loss Monitoring Copy trading includes automatic stop-loss monitoring with 5-second price polling: ```typescript // Configure stop-loss per followed wallet await copyTrader.follow(address, { stopLossPct: 10, // Exit at 10% loss }); // Or set global stop-loss copyTrader.setGlobalStopLoss(15); // 15% for all positions ``` ### Take-Profit Monitoring ```typescript // Configure take-profit per followed wallet await copyTrader.follow(address, { takeProfitPct: 25, // Exit at 25% profit }); // Trailing take-profit await copyTrader.follow(address, { trailingTakeProfit: true, trailingPct: 5, // Trail by 5% }); ``` ### Daily Limits ```typescript const copyTrader = createCopyTradingService({ limits: { maxDailyLoss: 500, // Stop after $500 loss maxDailyTrades: 20, // Max 20 trades maxTotalExposure: 5000, // Max $5k total exposure }, }); ``` --- ## Best Practices 1. **Start with small sizes** - Test with 10-25% proportional sizing 2. **Use delays** - 15-30 second delays reduce front-running risk 3. **Set stop-losses** - Always use 10-15% stop-loss 4. **Diversify** - Follow 3-5 wallets, not just one 5. **Monitor regularly** - Check performance daily 6. **Filter markets** - Focus on categories you understand