Polymarket Copy Trading Bot

Copy the best, automate success. Mirror trades from top Polymarket traders with intelligent position sizing and real-time execution.

Example trader: Check performance on Predictfolio

---

🎉 NEW: User-Friendly Updates!

This bot is now much easier to use! New features include:

• 🧙 Interactive Setup Wizard - No more manual config editing
• 🏥 Enhanced Health Check - Diagnose issues instantly
• 📚 Complete Getting Started Guide - Step-by-step for beginners
• ✨ Better Error Messages - Know exactly what's wrong and how to fix it
• 🆘 Help Command - See all available commands

Never used this bot before? You can set it up in under 10 minutes! See what's new →

---

📖 Table of Contents

• Quick Start
• What You Need
• Installation
• How It Works
• Features
• Configuration
• Safety & Risk Management
• Troubleshooting
• Documentation

---

🚀 Quick Start

🎯 First time here? Start with the 📖 GETTING STARTED GUIDE

It covers everything step-by-step: wallet setup, funding, configuration, and more!

Already know what you're doing?

# 1. Clone and install
git clone <repository-url>
cd polymarket-copytrading-bot
npm install

# 2. Run interactive setup wizard
npm run setup

# 3. Build and start
npm run build
npm run health-check  # Verify everything works
npm start             # Start trading!

Alternative guides:

• 📚 Detailed Getting Started - Complete beginner-friendly guide
• ⚡ Quick Start Guide - 5-minute setup for experienced users
• 🐳 Docker Deployment - Deploy with containers

Overview

The Polymarket Copy Trading Bot automatically replicates trades from successful Polymarket traders to your wallet. Instead of manually tracking top performers, the bot monitors their activity 24/7 and executes proportionally sized trades on your behalf.

How It Works

1. Select Traders - Choose top performers from Polymarket leaderboard or Predictfolio
2. Monitor Trades - Bot continuously watches for new positions opened by your selected traders
3. Calculate Position Size - Automatically scales trades based on your balance vs. trader's balance
4. Execute Orders - Places matching orders on Polymarket using your wallet
5. Track Performance - Logs all activity and maintains trade history in MongoDB

Position Sizing Example

If you're tracking a trader with $10,000 and they buy $500 worth of shares:

• Your balance: $1,000
• Position ratio: $1,000 / ($10,000 + $500) = 9.5%
• Base trade size: $500 × 9.5% = $47.50
• With 2x multiplier: $47.50 × 2 = $95.00

The bot ensures you maintain proportional exposure relative to the traders you follow, and you can amplify positions using the multiplier.

---

Features

• Multi-Trader Support - Track and copy trades from multiple traders simultaneously
• Smart Position Sizing - Automatically adjusts trade sizes based on your capital
• Tiered Trade Multipliers - Apply different multipliers based on trade size - perfect for copying large traders (NEW!)
• Position Tracking - Accurately tracks purchases and sells proportionally even after balance changes
• Trade Aggregation - Combine multiple small trades into larger executable orders
• Real-time Execution - Monitors trades every second and executes instantly
• Beautiful Logging - Clean, colorful console output with structured trade information
• MongoDB Integration - Persistent storage of all trades and positions
• Flexible Configuration - Support comma-separated or JSON array of trader addresses
• Secure - No credential exposure in logs, wallet addresses masked with ****, private keys stay local
• Price Protection - Built-in slippage checks to avoid unfavorable fills

📋 What You Need

Before you start, make sure you have:

Requirement	Where to Get It	Cost
Node.js v18+	nodejs.org	Free
MongoDB Database	MongoDB Atlas	Free tier available
Polygon Wallet	MetaMask or any Web3 wallet	Free
USDC on Polygon	Bridge from Ethereum or buy on exchange	Your trading capital
POL/MATIC	Any crypto exchange	~$5-10 for gas fees
RPC Endpoint	Infura or Alchemy	Free tier available

💡 Tip: Use the interactive setup wizard (npm run setup) - it will guide you through getting all of these!

🛠️ Installation

Option 1: Interactive Setup (Recommended)

The easiest way to get started:

# 1. Clone the repository
git clone <repository-url>
cd polymarket-copytrading-bot

# 2. Install dependencies
npm install

# 3. Run the interactive setup wizard
npm run setup

# 4. Build and start
npm run build
npm start

The setup wizard will ask you simple questions and create your configuration automatically.

Option 2: Manual Setup

If you prefer to configure manually:

# 1. Clone and install
git clone <repository-url>
cd polymarket-copytrading-bot
npm install

# 2. Create configuration file
# Note: Create a file named .env with the following content:

USER_ADDRESSES='0x7c3db723f1d4d8cb9c550095203b686cb11e5c6b'
PROXY_WALLET='your_polygon_wallet_address'
PRIVATE_KEY='your_private_key_without_0x_prefix'
MONGO_URI='mongodb+srv://user:pass@cluster.mongodb.net/database'
RPC_URL='https://polygon-mainnet.infura.io/v3/YOUR_PROJECT_ID'
CLOB_HTTP_URL='https://clob.polymarket.com/'
CLOB_WS_URL='wss://ws-subscriptions-clob.polymarket.com/ws'
USDC_CONTRACT_ADDRESS='0x2791Bca1f2de4661ED88A30C99A7a9449Aa84174'

# 3. Build and run
npm run build
npm start

📖 For step-by-step manual setup, see the Quick Start Guide.

---

🐳 Docker Deployment

Prefer Docker? Deploy the bot with Docker Compose for a production-ready setup with MongoDB and optional VPN included.

Quick Start with Docker

# 1. Clone and configure
git clone <repository-url>
cd polymarket-copy-trading-bot
cp .env.example .env
cp .env.docker.example .env.docker

# 2. Edit configuration files
nano .env              # Configure bot settings (wallet, traders, etc.)
nano .env.docker       # Configure Docker infrastructure (MongoDB, VPN)

# 3. Export Docker env vars and start
export $(cat .env.docker | grep -v '^#' | xargs)
docker-compose up -d

# 4. View logs
docker-compose logs -f polymarket

What's Included

• 🐳 Isolated Environment - Bot runs in containerized environment
• 🗄️ MongoDB Container - Database included, no separate installation needed
• 🔒 Optional VPN - WireGuard VPN support for geographic restrictions
• ♻️ Auto-restart - Containers restart automatically on failure
• 📊 Health Checks - Ensures services are healthy before starting bot

Learn More

📖 Complete Docker Guide →

The comprehensive guide covers:

• Detailed configuration (MongoDB, VPN)
• Container management commands
• Troubleshooting common issues
• Security best practices
• Advanced configuration options

---

Configuration

Finding Traders to Copy

1. Visit Polymarket Leaderboard

2. Look for traders with:

   • Positive P&L (green)
   • Win rate above 55%
   • Active trading history
   • Position sizes you can afford to copy proportionally

3. Check their detailed stats on Predictfolio

4. Copy their wallet address and add to USER_ADDRESSES

Environment Variables

Variable	Description	Example
USER_ADDRESSES	Traders to copy (comma-separated or JSON)	'0xABC..., 0xDEF...'
PROXY_WALLET	Your Polygon wallet address	'0x123...'
PRIVATE_KEY	Your wallet private key (no 0x prefix)	'abc123...'
FETCH_INTERVAL	Check interval in seconds	1
TRADE_MULTIPLIER	Position size multiplier (default: 1.0)	2.0
RETRY_LIMIT	Maximum retry attempts for failed orders	3
TRADE_AGGREGATION_ENABLED	Enable trade aggregation (default: false)	true
TRADE_AGGREGATION_WINDOW_SECONDS	Time window for aggregation in seconds	300
MONGO_URI	MongoDB connection string	'mongodb+srv://...'
RPC_URL	Polygon RPC endpoint	'https://polygon...'

Trading Logic

Buy Strategy:

• Calculates position ratio: your_balance / (trader_balance + trade_size)
• Scales trade size proportionally to your capital
• Applies multiplier to final trade size
• Checks minimum order size ($1 minimum required by Polymarket)
• Checks price slippage (max $0.05 difference)
• Executes market order at best available price

Sell Strategy:

• Mirrors trader's sell percentage
• Applies multiplier to position sizing
• If trader sells 20% of position, bot sells 20% of yours (× multiplier)
• If trader closes entire position, bot closes yours completely

Trade Multiplier:

The TRADE_MULTIPLIER allows you to amplify or reduce your position sizes relative to the calculated ratio:

• 1.0 (default) - Exact proportional copying
• 2.0 - Double the position size (more aggressive)
• 0.5 - Half the position size (more conservative)

Example:

Trader (Balance: $50,000) buys $5,000 (10% of capital)
You (Balance: $1,000, Multiplier: 2.0)

Position ratio: 1,000 / 55,000 = 0.0182 (1.82%)
Base trade: $5,000 × 0.0182 = $91
With 2x multiplier: $91 × 2.0 = $182 (actual trade size)

⚠️ Warning: Higher multipliers increase both potential gains and losses. Use with caution!

Trade Aggregation (NEW!):

Trade aggregation solves a common problem: traders often make multiple small trades that individually fall below Polymarket's $1 minimum, but together represent a meaningful position worth copying.

How it works:

• When enabled, the bot collects small BUY trades (below $1) in a buffer
• Trades are grouped by trader, market, and side (BUY/YES or BUY/NO)
• After the time window expires (default: 300 seconds / 5 minutes), aggregated trades are executed as one order
• The bot calculates a weighted average price based on all individual trades
• If the combined total is still below $1, the trades are skipped and logged

Configuration:

TRADE_AGGREGATION_ENABLED = true              # Enable the feature
TRADE_AGGREGATION_WINDOW_SECONDS = 300        # Wait 5 minutes (default)

Example scenario:

Trader makes 3 small BUY trades on "Will Trump meet with Putin?":
  Trade 1: $0.35 @ 52¢  (1:00 PM)
  Trade 2: $0.25 @ 51¢  (1:02 PM)
  Trade 3: $0.50 @ 53¢  (1:04 PM)

Without aggregation: All 3 trades skipped (below $1 minimum)

With aggregation enabled:
  - Trades collected in buffer for 5 minutes
  - At 1:05 PM window expires
  - Total: $1.10
  - Weighted average price: $52.27¢
  - ✓ Executed as single $1.10 order

This feature is especially useful when copying traders who:

• "Scale into" positions with multiple small entries
• Test markets with small trades before committing larger capital
• Trade across many markets with small position sizes

---

Safety and Risk Management

⚠️ Important Disclaimers:

• Use at your own risk - This bot executes real trades with real money
• Start small - Test with minimal funds before scaling up
• Diversify - Don't copy just one trader; track 3-5 different strategies
• Monitor regularly - Check bot logs daily to ensure proper execution
• Set limits - The current version has no built-in stop-loss or position limits
• No guarantees - Past performance of copied traders doesn't guarantee future results

Best Practices

1. Dedicated Wallet - Use a separate wallet just for the bot, not your main funds
2. Limited Capital - Only allocate what you can afford to lose
3. Research Traders - Verify trader history and strategy before copying
4. Active Monitoring - Set up alerts and check the bot at least once daily
5. Emergency Stop - Know how to stop the bot quickly (Ctrl+C)

---

📚 Documentation

Getting Started

• 🚀 Getting Started Guide - START HERE - Complete beginner's guide
• ⚡ Quick Start - 5-minute setup for experienced users
• 🎉 What's New - Recent user-friendly improvements

Advanced Guides

• 🐳 Docker Deployment - Deploy with containers
• 👥 Multi-Trader Guide - Copy multiple traders
• 📍 Position Tracking - How position tracking works
• 💰 Funding Guide - How to fund your wallet

Testing & Analysis

• 🧪 Simulation Guide - Backtest strategies
• 🔬 Simulation Runner - Advanced backtesting
• 📊 Logging Preview - Console output examples

---

🆘 Troubleshooting

Common Issues

❌ "Missing required environment variables"

Solution: Run npm run setup to create your .env file, or manually create one with all required fields.

❌ "MongoDB connection failed"

Solutions:

• Check your MONGO_URI is correct
• Whitelist your IP in MongoDB Atlas (or allow 0.0.0.0/0 for testing)
• Verify database user has read/write permissions

❌ "Bot not detecting trades"

Solutions:

• Verify trader addresses are correct (check on Polymarket)
• Ensure traders are actively trading (check their recent activity)
• Check bot logs for API errors

❌ "Insufficient balance" when executing trades

Solutions:

• Add USDC to your PROXY_WALLET on Polygon network
• Get POL (MATIC) for gas fees (~$5-10 worth)
• Check your balance: npm run check-proxy

❌ "Price slippage too high"

Solutions:

• Market moved too fast between detection and execution
• Try increasing FETCH_INTERVAL from 1 to 2-3 seconds
• Current tolerance is $0.05 - you can modify this in code if needed

💡 Still having issues?

1. Run health check: npm run health-check
2. Check documentation: Quick Start Guide
3. Open an issue: Include error messages (remove private keys!) and steps to reproduce

Getting Help

• 📖 Quick Start Guide - Detailed setup instructions
• 🐳 Docker Guide - Alternative deployment method
• 💬 GitHub Issues - Report bugs or ask questions

---

Contributing

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

If you find this project helpful, please consider giving it a star ✨

---

License

This project is provided as-is for educational and research purposes. Users are responsible for compliance with local laws and Polymarket's terms of service.

---

Acknowledgments

• Built on Polymarket CLOB Client
• Uses Predictfolio for trader analytics
• Powered by Polygon network

---

Disclaimer: This software is for educational purposes only. Trading involves risk of loss. The developers are not responsible for any financial losses incurred while using this bot.

for support, find me on telegram (moooncity)