Mirror a target trader's Polymarket activity from your own account — TypeScript/Node, poll-based, with size caps and safety rails.
Portfolio, performance, and history — the kind of activity this bot watches and mirrors.
| Watch | A target user (address or username → proxy) on Polymarket |
| Poll | On your schedule (COPY_POLL_INTERVAL_MS) |
| Copy | Similar orders from your wallet, with multiplier & max size limits |
If you've been looking for polymarket bot, polymarket copy trading, polymarket trading bot typescript, or clob client bot — you're in the right repo.
In the Polymarket app you'll see Activity (recent trades and claims) — the stream the bot polls — and Positions (how outcomes show up in your portfolio after execution), plus portfolio stats. The bot automates the follow-the-leader part so you don't have to chase every fill by hand.
- Watches a target user (address or username → proxy) on Polymarket
- Polls periodically and fetches recent activity
- Copies trades to your account with optional risk controls (multiplier, max order size, trades-only mode)
- No profit guarantees. If the target trader jumps off a cliff, the bot will politely ask if you'd like to join them.
- Not a "magic arbitrage printer." It's copy-trading. (If you want true arbitrage, you'll likely need additional routing, pricing, and latency work.)
| Requirement | Notes |
|---|---|
| Git | So you can clone the repo (install Git if needed). |
| Node.js | v20 or newer — check with node -v. Download from nodejs.org if required. |
| npm | Ships with Node; confirm with npm -v. |
| Polymarket account | Funded account you control. |
| Secrets | Your EOA private key and Polymarket proxy / funder address from the Polymarket UI (never share these). |
Pick a parent folder on your machine, open a terminal there, then:
HTTPS (works everywhere, no SSH setup):
clone the repo
cd polymarket-copy-trading-botSSH (if you use SSH keys with GitHub):
You should see package.json, src/, and .env.example in the project root.
From the project root (polymarket-copy-trading-bot/):
npm installThis installs everything listed in package.json (including dev tooling used by npm run dev).
The bot reads configuration from a .env file in the project root. Start from the template:
Windows (Command Prompt or PowerShell):
copy .env.example .envmacOS / Linux:
cp .env.example .envOpen .env in your editor and set at least:
COPY_TARGET_USER— Polymarket proxy address (0x…) or username of the trader to mirror.POLYMARKET_PRIVATE_KEY— your wallet private key (64 hex characters, with or without0x).POLYMARKET_ADDRESS— your Polymarket proxy / funder address from the Polymarket UI (not necessarily the same as your raw EOA address).
Optional variables (poll interval, size multiplier, caps, etc.) are documented in Configuration and in .env.example.
Security: Never commit .env or paste keys into issues or chat. .gitignore should keep .env local; if you fork the repo, double-check before pushing.
Development (TypeScript with watch / typical local workflow):
npm run devProduction-style (compiles TypeScript with npm run build, then runs node dist/index.js):
npm startLeave the terminal open while the bot runs. Stop with Ctrl+C.
- If the process exits immediately, read the error: missing
POLYMARKET_PRIVATE_KEY, bad hex, or unresolvedCOPY_TARGET_USERare common fixes (see Troubleshooting below). - For first tests, use a small
COPY_SIZE_MULTIPLIERand a non-zeroCOPY_MAX_ORDER_USDcap (see Safety below).
| Step | Command |
|---|---|
| Clone the repo | |
| Enter folder | cd polymarket-copy-trading-bot |
| Install | npm install |
| Env file | copy .env.example .env (Windows) or cp .env.example .env (macOS/Linux) |
| Run (dev) | npm run dev |
| Run (start) | npm start |
All config is via environment variables (see .env.example).
Pick one:
COPY_TARGET_USER: target proxy address or username (the bot will try to resolve username → proxy)
| Variable | What it controls | Example |
|---|---|---|
COPY_POLL_INTERVAL_MS |
How often to poll for new activity | 15000 |
COPY_ACTIVITY_LIMIT |
How many recent activities to consider per poll | 100 |
COPY_SIZE_MULTIPLIER |
Multiply copied trade size | 1 |
COPY_MAX_ORDER_USD |
Hard cap per copied order (0 = no cap) | 25 |
COPY_TRADES_ONLY |
If true, avoids copying non-trade activity |
true |
| Variable | Required | Notes |
|---|---|---|
POLYMARKET_PRIVATE_KEY |
✅ | 64 hex chars (with or without 0x) |
POLYMARKET_ADDRESS |
✅ | Your Polymarket proxy/funder address (from UI) |
POLYMARKET_SIGNATURE_TYPE |
❌ | Usually auto-detected; override only if needed |
POLYMARKET_CHAIN_ID |
❌ | Defaults to Polygon in most setups |
- Never commit your
.env. If you do, the internet will treat it like free samples at Costco. - Consider running on a fresh wallet with limited funds while testing.
- Start with
COPY_SIZE_MULTIPLIER=0.1and a smallCOPY_MAX_ORDER_USD.
-
POLYMARKET_PRIVATE_KEY is required...
Your key is missing or not valid hex. The bot accepts 64 hex chars with optional0x. -
"Could not resolve username to proxy"
Use a proxy address (0x…) forCOPY_TARGET_USERor set the correct target.
It can be part of an arbitrage workflow, but by itself it's primarily copy trading. If you're building true arbitrage, you'll probably add market scanning, price diff logic, and execution routing.
It's poll-based (COPY_POLL_INTERVAL_MS). If you need low-latency mirroring, you'll want a streaming approach.
Doc pass: Q1 2026.
PRs welcome. If you add a feature, please also add:
- a sensible default
- a safe guardrail (limits > YOLO)
- and a short explanation in this README
This software is for educational purposes. You are responsible for how you use it. Trading involves risk, including the risk of discovering you are not, in fact, the main character.