polymarket-copy-trading-bot

# Polymarket Copy Trading Bot > Skill by [ara.so](https://ara.so) — Daily 2026 Skills collection. A TypeScript bot that continuously monitors a target Polymarket wallet, detects trades in real time via REST polling and/or WebSocket, and mirrors BUY orders to your own account using the Polymarket CLOB SDK on Polygon mainnet. --- ## What It Does - **Monitors** a target wallet via Polymarket Data API (REST polling every ~2s) and optionally WebSocket - **Mirrors BUY trades only** — SELL trades are detected but skipped by default - **Sizes copies** using a configurable `POSITION_MULTIPLIER` (default 10%) with min/max caps - **Submits orders** as FOK, FAK, or LIMIT via the Polymarket CLOB client - **Enforces risk limits** — per-session and per-market notional caps - **Supports three auth modes** — EOA (`SIG_TYPE=0`), Poly Proxy (`SIG_TYPE=1`), Poly Polymorphic (`SIG_TYPE=2`) --- ## Installation ```bash git clone https://github.com/Neron888/Polymarket-copy-trading-bot.git cd Polymarket-copy-trading-bot npm install ``` Requires Node.js v18+. The CLOB SDK requires **ethers v5** (already pinned in `package.json`). --- ## Configuration ```bash cp .env.example .env ``` Edit `.env`: ```env # Required TARGET_WALLET=0xTargetWalletAddressToMonitor WALLET_PRIVATE_KEY=0xYourPrivateKey RPC_URL=https://your-quicknode-polygon-endpoint.quiknode.pro/your-key/ # Auth mode (0=EOA default, 1=Poly Proxy, 2=Poly Polymorphic) SIG_TYPE=0 # Required only for SIG_TYPE=1 or 2 PROXY_WALLET_ADDRESS= # Sizing POSITION_MULTIPLIER=0.1 # 10% of target's trade size MAX_TRADE_SIZE=100 # Max USDC per copied trade MIN_TRADE_SIZE=1 # Min USDC per copied trade # Order behavior ORDER_TYPE=FOK # FOK | FAK | LIMIT SLIPPAGE_TOLERANCE=0.02 # 2% # Risk caps (0 = disabled) MAX_SESSION_NOTIONAL=500 # Total USDC for entire session MAX_PER_MARKET_NOTIONAL=100 # Per market USDC cap # Monitoring USE_WEBSOCKET=true POLL_INTERVAL=2000 # ms between REST polls USE_USER_CHANNEL=false # true = user WS channel, false = market channel # Optional POLYMARKET_GEO_TOKEN= WS_ASSET_IDS= # comma-separated asset IDs for market WS WS_MARKET_IDS= # comma-separated condition IDs for user channel MIN_PRIORITY_FEE_GWEI=30 MIN_MAX_FEE_GWEI=60 ``` --- ## Key Commands ```bash # Start the bot (development mode with ts-node) npm start # Generate and persist API credentials to .polymarket-api-creds npm run generate-api-creds # Validate existing API credentials npm run test-api-creds # Compile TypeScript to dist/ npm run build # Run compiled production build npm run start:prod ``` --- ## Architecture Overview ``` index.ts └── TradeMonitor — REST polls Polymarket Data API for new target trades └── WebSocketMonitor — Optional low-latency WS subscription (market or user channel) └── TradeExecutor — Sizes trade, checks balance/allowance, submits CLOB order └── PositionTracker — In-memory positions updated on fills └── RiskManager — Session + per-market notional enforcement ``` Execution flow: ``` detect trade → BUY? → subscribe WS if needed → compute copy size → risk check → execute order (FOK/FAK/LIMIT) → record fill → update stats ``` --- ## Code Examples ### Starting the bot programmatically ```typescript import { startBot } from './src/index'; // The bot reads all config from process.env / .env startBot(); ``` ### TradeMonitor — polling pattern ```typescript import { TradeMonitor } from './src/TradeMonitor'; const monitor = new TradeMonitor({ targetWallet: process.env.TARGET_WALLET!, pollInterval: Number(process.env.POLL_INTERVAL ?? 2000), }); monitor.on('trade', (trade) => { console.log('New trade detected:', trade); // trade.side: 'BUY' | 'SELL' // trade.asset: token ID (outcome token address) // trade.size: USDC size // trade.price: fill price (0–1) }); monitor.start(); ``` ### TradeExecutor — placing a copy order ```typescript import { TradeExecutor } from './src/TradeExecutor'; import { ClobClient } from '@polymarket/clob-client'; import { ethers } from 'ethers'; const provider = new ethers.providers.JsonRpcProvider(process.env.RPC_URL); const signer = new ethers.Wallet(process.env.WALLET_PRIVATE_KEY!, provider); const clobClient = new ClobClient( 'https://clob.polymarket.com', 137, // Polygon chainId signer, apiCreds, // loaded from .polymarket-api-creds Number(process.env.SIG_TYPE ?? 0), process.env.PROXY_WALLET_ADDRESS || undefined, ); const executor = new TradeExecutor({ client: clobClient, positionMultiplier: Number(process.env.POSITION_MULTIPLIER ?? 0.1), maxTradeSize: Number(process.env.MAX_TRADE_SIZE ?? 100), minTradeSize: Number(process.env.MIN_TRADE_SIZE ?? 1), orderType: (process.env.ORDER_TYPE ?? 'FOK') as 'FOK' | 'FAK' | 'LIMIT', slippageTolerance: Number(process.env.SLIPPAGE_TOLERANCE ?? 0.02), }); // Copy a detected trade await executor.copyTrade({ side: 'BUY', tokenId: '0xAssetId...', originalSize: 12.5, // USDC from target's trade price: 0.62, }); ``` ### RiskManager — checking before execution ```typescript import { RiskManager } from './src/RiskManager'; const riskManager = new RiskManager({ maxSessionNotional: Number(process.env.MAX_SESSION_NOTIONAL ?? 0), maxPerMarketNotional: Number(process.env.MAX_PER_MARKET_NOTIONAL ?? 0), }); const allowed = riskManager.checkTrade({ marketId: '0xConditionId...', notional: copySize, }); if (!allowed) { console.log('Trade blocked by risk limits'); } ``` ### WebSocket monitor — low-latency subscription ```typescript import { WebSocketMonitor } from './src/WebSocketMonitor'; const wsMonitor = new WebSocketMonitor({ useUserChannel: process.env.USE_USER_CHANNEL === 'true', assetIds: process.env.WS_ASSET_IDS?.split(',').filter(Boolean) ?? [], marketIds: process.env.WS_MARKET_IDS?.split(',').filter(Boolean) ?? [], }); wsMonitor.on('orderFilled', (fill) => { console.log('Fill received via WS:', fill); }); wsMonitor.connect(); ``` --- ## Authentication Modes ### EOA (default — `SIG_TYPE=0`) ```env SIG_TYPE=0 WALLET_PRIVATE_KEY=0xYourKey # PROXY_WALLET_ADDRESS — leave empty ``` On first run, the bot auto-submits USDC.e/CTF approval transactions. Wallet needs POL for gas. ### Poly Proxy (`SIG_TYPE=1`) ```env SIG_TYPE=1 WALLET_PRIVATE_KEY=0xSignerKey PROXY_WALLET_ADDRESS=0xYourPolymarketProxyAddress ``` ### Poly Polymorphic (`SIG_TYPE=2`) ```env SIG_TYPE=2 WALLET_PRIVATE_KEY=0xSignerKey PROXY_WALLET_ADDRESS=0xYourPolymorphicSafeAddress ``` --- ## Generating API Credentials ```bash npm run generate-api-creds ``` This derives API keys from your wallet signature and writes them to `.polymarket-api-creds`. Run once before `npm start` if you want to pre-generate credentials. The bot also auto-generates them on first start in EOA mode. Validate credentials: ```bash npm run test-api-creds ``` --- ## Common Patterns ### Conservative testing setup ```env POSITION_MULTIPLIER=0.05 MAX_TRADE_SIZE=5 MIN_TRADE_SIZE=1 MAX_SESSION_NOTIONAL=20 ORDER_TYPE=FOK USE_WEBSOCKET=false ``` ### WebSocket-only market channel (lower latency) ```env USE_WEBSOCKET=true USE_USER_CHANNEL=false WS_ASSET_IDS=0xTokenId1,0xTokenId2 ``` ### LIMIT orders with slippage buffer ```env ORDER_TYPE=LIMIT SLIPPAGE_TOLERANCE=0.03 ``` --- ## Troubleshooting **Bot starts but no trades detected** - Verify `TARGET_WALLET` is a valid Polymarket wallet with recent activity - Check `POLL_INTERVAL` — default 2000ms; lower means more API calls - Confirm the target wallet trades on Polymarket (not just holds positions) **`ethers` version conflicts** - The project pins ethers v5. Do not upgrade to v6 — the CLOB SDK requires v5 - Run `npm ls ethers` to check for duplicate versions **Approval transactions failing** - Ensure the wallet has sufficient POL (MATIC) for gas on Polygon mainnet - Try increasing `MIN_PRIORITY_FEE_GWEI` and `MIN_MAX_FEE_GWEI` if transactions stall **`generate-api-creds` fails** - Confirm `WALLET_PRIVATE_KEY` is correct and 0x-prefixed - For `SIG_TYPE=1/2`, ensure `PROXY_WALLET_ADDRESS` matches your Polymarket account **Orders rejected by CLOB** - FOK orders fail if insufficient liquidity — try `ORDER_TYPE=FAK` or `LIMIT` - Check `SLIPPAGE_TOLERANCE` isn't too tight for illiquid markets **Session notional cap hit immediately** - `MAX_SESSION_NOTIONAL` resets per process run; restart the bot to reset - Set `MAX_SESSION_NOTIONAL=0` to disable the cap entirely --- ## Wallet Requirements - **USDC.e** on Polygon mainnet (collateral for trades) - **POL** (formerly MATIC) for gas fees - Approve USDC.e for Polymarket CTF Exchange and CLOB contracts (bot does this automatically on first EOA run) --- ## References - [QuickNode Guide — Building a Polymarket Copy Trading Bot](https://www.quicknode.com/guides/defi/polymarket-copy-trading-bot) - [Polymarket CLOB Client SDK](https://github.com/Polymarket/clob-client) - [Polymarket](https://polymarket.com/) - [Polymarket CLOB API Docs](https://docs.polymarket.com/)