Skip to content

README.md

Latest commit

 

History

History
151 lines (109 loc) · 5.75 KB

README.md

File metadata and controls

151 lines (109 loc) · 5.75 KB

Polymarket Copy Trading Bot

Automated copy trading for Polymarket: mirror a target wallet’s BUY / SELL activity with configurable sizing, slippage, and risk caps via Polymarket’s CLOB on Polygon.

Contents

Overview · Repository structure · Flow · Prerequisites · Setup & run · Configuration · Notes · Security & disclaimer

Overview

Why automate copying

Benefit Description
Time No manual order entry every time the target trades.
Signal You pick which wallet to follow; rules stay in config.
Discipline Fixed multipliers, caps, and slippage reduce ad-hoc decisions.
Latency REST polling plus optional WebSocket narrows the gap vs manual copy-paste.

Copy trading does not guarantee profit. The target can lose; fees and slippage apply; fills can differ. Use at your own risk.

Stack: TypeScript (Node ESM), @polymarket/clob-client, ethers, axios, ws, dotenv.

Repository structure

src/
├── index.ts                    # Wires monitors → risk → trader
├── config/
│   └── config.ts               # Env + Polygon contract addresses + defaults
├── lib/
│   └── logger.ts
├── monitoring/
│   ├── monitor.ts              # Data API polling (activity)
│   └── websocket-monitor.ts    # Optional CLOB WebSocket
├── trading/
│   └── trader.ts               # Orders, balances, approvals
├── risk/
│   ├── risk-manager.ts         # Notional caps
│   └── positions.ts            # Position state for sells / caps
└── cli/
    ├── generate-api-creds.ts
    └── test-api-creds.ts

Why this layout: ingestion (monitoring/) is isolated from execution (trading/); risk/ owns caps and position math; cli/ keeps one-off tasks off the hot path—easier to test and extend without entangling the main loop.

Flow

  1. Detect — Data API (and optionally WebSocket) observes the target wallet.
  2. Filter — Only trades after startup; dedupe; optional COPY_SELLS and position checks.
  3. Size — POSITION_MULTIPLIER, MAX_TRADE_SIZE, session/per-market caps.
  4. Execute — @polymarket/clob-client; user API creds derived from PRIVATE_KEY.
  5. On-chain — USDC.e / CTF approvals for EOA mode as required.

Features (summary): configurable POLL_INTERVAL; WS with REST fallback; LIMIT / FOK / FAK; slippage + tick rounding; optional exit after first copied sell (EXIT_AFTER_FIRST_SELL_COPY).

Prerequisites

  • Node.js 18+, npm
  • Polygon EOA with USDC.e and POL (gas); same EOA as PRIVATE_KEY
  • Stable RPC_URL (dedicated endpoint recommended)
  • Polymarket may block some regions—use a reachable network path per their terms.

Auth: CLOB user credentials are created/derived from PRIVATE_KEY at startup. Builder dashboard keys are not a substitute for user trading auth. Optional: npm run generate-api-creds → .polymarket-api-creds (mode 0600, gitignored).

Setup & run

npm install
cp .env.example .env
# Edit .env: TARGET_WALLET, PRIVATE_KEY, RPC_URL
npm start                 # production-style via tsx
npm run dev               # watch mode
npm run build && npm run start:prod
npm run start:until-sell  # exit after first copied SELL
npm run generate-api-creds  # optional export
npm run test-api-creds      # validate saved creds
npm script What it does
start Run the bot (tsx src/index.ts)
dev Watch mode (tsx watch)
build tsc → dist/
start:prod node dist/index.js after build
start:until-sell Sets EXIT_AFTER_FIRST_SELL_COPY and runs once
generate-api-creds / test-api-creds CLI helpers under src/cli/

Configuration

Variable Purpose
TARGET_WALLET Wallet to copy
PRIVATE_KEY Signer + CLOB auth
RPC_URL Polygon JSON-RPC
USE_WEBSOCKET, USE_USER_CHANNEL WS; user channel needs WS auth
POSITION_MULTIPLIER, MAX_TRADE_SIZE, MIN_TRADE_SIZE Sizing
SLIPPAGE_TOLERANCE, ORDER_TYPE Price / order style (LIMIT, FOK, FAK)
COPY_SELLS Mirror sells (needs position)
MAX_SESSION_NOTIONAL, MAX_PER_MARKET_NOTIONAL 0 = off
EXIT_AFTER_FIRST_SELL_COPY One-shot validation mode
POLL_INTERVAL REST poll interval (ms)
POLYMARKET_GEO_TOKEN Optional if Polymarket requires it for your region/account
MIN_PRIORITY_FEE_GWEI, MIN_MAX_FEE_GWEI Polygon gas floors for approval txs

Full list: .env.example.

Notes

  • Only trades after bot start are copied.
  • WS can drop; REST keeps polling.
  • Start with small size and caps until behavior matches expectations.
  • If orders fail with balance/allowance errors, confirm USDC.e, CLOB collateral, and gas on the signing wallet.
  • Cloudflare or 403 responses often mean geo or IP restrictions—fix network path before tuning strategy.

Keywords: polymarket copy bot, prediction markets, CLOB, Polygon, automated trading.

Security & disclaimer

Do not commit .env or .polymarket-api-creds. Use a dedicated wallet and only capital you can lose; understand token approvals on Polygon.

Disclaimer: Provided as-is for education and automation. Not financial, legal, or tax advice. Markets involve risk of total loss. You are responsible for Polymarket’s terms, applicable law, and taxes. Past performance of a copied wallet does not predict future results.

License

ISC — see package.json.