PMWallets copy-trading bot

Polymarket copy-trading bot (Node.js / TypeScript)

A ready-to-run Polymarket copy-trading bot built on PMWallets: it follows the traders you subscribe to and mirrors their fills on the Polymarket CLOB with your own account, inside the limits you set.

pmwallets-copytrade on npm · 中文说明 · Python version: polymarket-copy-trading-bot-python · SDK: pmwallets-node

What the bot does

1. You pick the traders on pmwallets.com: filter the board by the lower bound of the win-rate confidence interval, profit without the single best market, activity and style, then subscribe.
2. The bot receives every fill of those traders over the PMWallets WebSocket, typically within a second of the block (measured latency). Missed frames are detected (session/seq) and replayed from the last fill handled, including everything that happened while the bot was down.
3. It mirrors them on Polymarket with your own account, inside the limits you set. Your keys never leave your machine; PMWallets never sees them and never places orders.

Quick start

# Node.js ≥ 20

npm install -g pmwallets-copytrade pmwallets-copytrade init # writes config.yaml export PMW_API_KEY=pmw_... # https://pmwallets.com/keys pmwallets-copytrade run # dry-run: logs every decision, trades nothing

When the dry-run log looks right, switch to live:

mode: live

polymarket: privateKey: ${POLY_PRIVATE_KEY} # signs your orders signatureType: 3 # see "Set up a Polymarket account for the bot" funderAddress: ${POLY_FUNDER_ADDRESS} # your Polymarket profile address (holds the USDC)

pmwallets-copytrade status prints open positions, today's spend and any order still being confirmed. If the bot cannot establish by itself whether an order filled, it keeps the order's reservation (no further BUY can exceed your limits because of it) and asks you: check polymarket.com and run pmwallets-copytrade reconcile --none or --filled --usdc with the bot stopped. Every decision — including each skip and its reason — is appended to pmw-data/decisions. .jsonl, and everything the bot prints also goes to pmw-data/bot. .log.

Something went wrong? Run pmwallets-copytrade diagnose and email the pmw-diagnose- .json.gz it writes to support@pmwallets.com, with a line about what happened. The file has the bot's version, the check result, your config with the keys removed, the state files and the newest logs and decisions. It contains no private key or API key (they are removed by name, then by value from the whole file), but it does show your wallet addresses, the traders you copy, your trades and your machine's IP. Never send `config.yaml` or `.env` themselves.

How it decides

The rules come from a copy-trading bot that ran live on Polymarket; each one is there because of a lost trade or a rejected order.

BUY (the trader bought)

• skip fills older than maxFillAgeSec (a replay after downtime must not buy history), below minTargetNotionalUsdc, or from a role you excluded;
• one copy per trader transaction, one position per (trader, outcome), at most maxBuysPerOutcome buys into it (DCA), maxOpenPositionsPerTarget / maxOpenPositions / maxDailySpendUsdc caps;
• the market must be open, accepting orders and not settle within minSecondsToEndDate;
• the best ask must sit in [minPrice, maxPrice], be at most maxSlippage above what the trader paid, and the book must hold minBookDepthUsdc;
• order: fill-or-kill for an exact number of shares at the best ask (orderSizeUsdc / ask), rounded so the CLOB accepts it. Share-denominated on purpose — a USDC-budget market order can overfill.

SELL (the trader sold)

• sellMode: all exits everything the bot bought following that trader in that outcome. Shares booked to another trader in the same outcome are never sold: the most it sells is your token balance minus what the other traders hold. If that comes to nothing, it stops and asks you to reconcile;
• the exit is saved and retried (with backoff, across restarts) until the position is gone. Freshness does not apply: if the trader left while the bot was down, it still gets out;
• order: fill-and-kill at the best bid — a partial exit beats none, and the rest is retried.

Polymarket V2 markets (canary markets now; every new market from 2026-11-02)

• the same rules, on Polymarket's new exchange (ExchangeV3, with the shares held in PositionManager instead of Conditional Tokens). Which exchange a market trades on comes from the CLOB market's version, and it must agree with the shape of the outcome id (a V2 position id is not a hash). If they disagree — or the CLOB does not say for an id shaped like a V2 position — the BUY is skipped (skipped_market_version) and an exit is kept and retried: the bot never guesses which exchange to sign for;
• combos (multi-leg parlays) are quoted by RFQ and never trade on the order book: always skipped (skipped_combo);
• they need approvals of their own — see the account section below.

Safety

• dry-run by default; live needs an explicit mode: live;
• at most once: a fill is marked decided in the state file *before* any order is sent, so a crash can miss a copy but never place it twice. One bot per data directory: a second instance refuses to start;
• no lost fills: every order is saved as *pending* before it is sent. An order the exchange reports as killed (such replies have carried real partial fills) is looked up again by its order id with backoff until its fill — or its absence — is certain, even across restarts. One that got no answer at all has no id to look up: if a matching trade appears, the bot does not guess whose it is (it could be yours by hand, or another trader's copy) and hands it to you to reconcile;
• resolved markets are swept every 10 minutes so they stop counting against the caps.

Where to run it. PMWallets' servers are in the United Kingdom, but Polymarket does not accept new API orders from the UK, the US, Germany, France and several other countries (Polymarket: geographic restrictions). Ireland (AWS eu-west-1) is the nearest region where it does — close to our servers and to Polymarket's in London. check reports whether your machine's region is allowed. Measured latency: https://pmwallets.com/latency.

One stream per account, and the bot comes first. PMWallets keeps one WebSocket per account. A connection made with an API key (the bot) takes priority: the live-feed page on pmwallets.com never takes the stream from it — while the bot is connected the page says so and stays off. Between two API connections the first one keeps the stream: a second bot on the same account (another key, or the same bot started twice) is refused and stops with a clear error. To move the stream to a new bot on purpose, set pmwallets.takeover: true on the new one — the old one is told it was replaced and stops. A bot's own reconnects after a network drop never need this. When PMWallets restarts its stream service the bot reconnects at once and replays anything it missed.

Follow smart-money signals (optional, off by default)

On a Pro or Max account the bot can buy when a PMWallets signal fires: several tracked wallets buying the same side in a short time. Turn on signals in the config:

signals:

enabled: true source: official # official = the PMWallets list; mine = your own rule on pmwallets.com orderSizeUsdc: 10 # USDC spent on each signal minWallets: 3 # skip signals backed by fewer wallets minTotalUsdc: 5000 # skip signals whose wallets bought less than this in total maxAgeSec: 120 # don't buy a signal older than this maxSlippage: 0.05 # skip if the best ask is this far above the wallets' average entry maxOpenPositions: 5 # outcomes held from signals at once categories: [] # e.g. [sports, politics]; empty = all exitOnFading: false # true = sell when the wallets have sold half (seen for 6 hours after the signal); false = hold to settlement

In `live` mode this places real orders. Run it in dry-run first and read the decision log. risk.maxDailySpendUsdc, copy.maxOpenPositions, copy.minPrice/maxPrice, copy.minBookDepthUsdc and the settlement limits all still apply. A signal is handled once and an outcome is bought once. Signals are read every pollSec seconds, so the price may have moved.

For AI agents and scripts

Besides run, the bot has one-off commands that print JSON, so an AI agent (or a script) can decide and trade by itself — for example on the fills pmwallets watch --exec hands it. They use the same config; its mode decides: dry-run simulates each order against the live order book and sends nothing, live trades.

pmwallets-copytrade market <tokenId>       # question, outcomes, prices, order book

pmwallets-copytrade balance # USDC to trade, approvals pmwallets-copytrade positions # open positions, value, PnL pmwallets-copytrade trades --limit 20 pmwallets-copytrade order buy --usdc 5 --max-price 0.45 --key pmwallets-copytrade order sell --all --min-price 0.40 --key :exit pmwallets-copytrade mcp --config /abs/path/config.yaml # the same as MCP tools

• BUY is fill-or-kill; --usdc is a ceiling (sized at the limit, so the order cannot cost more). SELL is fill-and-kill, capped at what the account holds.
• --key makes retries safe: the key is written to dataDir before the order is sent, and the same key never sends a second order. Use the fill's eventId.
• status: unknown (or verify: true) means the order may have filled — check trades before sending another. Exit code 0 = filled or dry_run, 2 = not traded, 3 = unknown.
• These orders are your own trades: the bot's books (positions, daily cap) do not count them. Don't sell with them what a running bot is holding for a target.

Configuration

pmwallets-copytrade init writes a commented config.yaml. ${NAME} in the file is replaced by the environment variable NAME; a missing variable stops the bot at start-up. Invalid values are rejected at start-up, never silently ignored.

Set up a Polymarket account for the bot (recommended)

Give the bot an account of its own, holding only what you are willing to let it trade. This is the setup we recommend and document; follow it step by step:

This setup has been tested with real money — a MetaMask (or other browser-wallet) account connected

on polymarket.com, signing with that wallet's own private key. Accounts made with email or Google, the older

Safe / Proxy accounts and plain wallets are supported by the code, but we have not run them live. If you can,

make a new account as below rather than reusing one of those.

1. Create a new wallet account in MetaMask (or Rabby): account menu → *Add account*. Use it for nothing but this.
2. Sign up on [polymarket.com](https://polymarket.com) by connecting that wallet (choose MetaMask in the sign-in dialog). Every account created on polymarket.com since 2026-05-04 gets a **Deposit W