Build and Configure a Polymarket Copy-Trading Bot with TypeScript

What the Polymarket CodeX CopyTrading Bot Does

The Polymarket CodeX CopyTrading Bot is a TypeScript application that monitors activity from one or more followed wallets and creates corresponding Polymarket orders. It reads wallet activity through the public Data API and uses @polymarket/clob-client-v2 for live trading through Polymarket's central limit order book.

The bot can copy buys and sells using either fixed USD amounts or percentage-based sizing. It also keeps a local record of seen trades, generated orders, executed or simulated orders, and approximate token positions.

Risk warning: This is trading software. Profit is not guaranteed. Always run the simulation first, review every configuration value, and use very small amounts before considering live execution.

Key Features

• Monitors multiple followed wallets.
• Supports fixed-amount and percentage-based copy modes.
• Provides simulated execution through npm run test.
• Provides live market execution through npm start.
• Can follow sell activity using the bot's locally tracked position.
• Applies minimum order, maximum order, position, and daily notional limits.
• Supports fill-and-kill and fill-or-kill order behavior.
• Offers optional price protection relative to the followed trade's fill price.
• Stores state in a local JSON file.

Requirements

Before configuring the bot, install the following software:

• Node.js version 20.10 or newer.
• npm.

Obtain the project source, open a terminal in its directory, and install the package dependencies:

npm install

The bot relies on the non-beta @polymarket/clob-client-v2 package for order execution and the public Polymarket Data API for wallet activity polling.

Configure Live Trading Credentials

Create or edit the project's .env file. Add the CLOB host, Polygon chain ID, signature type, private key, and deposit wallet:

POLYMARKET_CLOB_HOST=https://clob.polymarket.com
POLYMARKET_CHAIN_ID=137
POLYMARKET_SIGNATURE_TYPE=POLY_1271
POLYMARKET_PRIVATE_KEY=0x...
POLYMARKET_DEPOSIT_WALLET=0x...

Never commit a real private key or credential file to version control. Treat the private key and any CLOB credentials as secrets.

Choose the Correct Signature Type

POLYMARKET_SIGNATURE_TYPE accepts the following values:

• EOA
• POLY_PROXY
• POLY_GNOSIS_SAFE
• POLY_1271

According to the project documentation, POLY_1271 is usually appropriate for new deposit-wallet users. When trading directly through an externally owned account, select EOA; in that case, POLYMARKET_DEPOSIT_WALLET may be omitted.

Use Existing L2 Credentials

The bot can derive credentials during startup. To avoid that step, supply existing L2 credentials in .env:

CLOB_API_KEY=...
CLOB_SECRET=...
CLOB_PASS_PHRASE=...

Live execution uses createAndPostMarketOrder. Before starting live trading, make sure the trading wallet is funded and has the required Polymarket approvals. The bot does not deploy wallets or automatically approve token spending.

Configure Copy Sizing

The application supports two copy modes. Select the mode that matches the amount of exposure you want the bot to take.

Fixed Mode

Fixed mode assigns a predefined USD amount to copied buy and sell activity:

COPY_MODE=fixed
FIXED_BUY_AMOUNT_USD=5
FIXED_SELL_AMOUNT_USD=5

In this example, eligible copied buys and sells are sized using a configured value of five US dollars.

Percentage Mode

Percentage mode calculates order sizes from the followed wallet's activity:

COPY_MODE=percentage
COPY_PERCENTAGE=0.10

For buys, the bot copies the configured percentage of the followed trade's USD notional. For sells, it copies the configured percentage of the followed wallet's sold shares. A sell is capped by the position currently tracked in the bot's local state.

For example, 0.10 represents ten percent. The actual order must still pass the configured risk controls.

Set Risk Controls

Define order and exposure limits in .env before running either simulated or live trading:

MIN_ORDER_USD=1
MAX_ORDER_USD=25
MAX_POSITION_USD_PER_TOKEN=100
DAILY_MAX_NOTIONAL_USD=250
ORDER_TYPE=FAK
PRICE_PROTECTION_BPS=0

• MIN_ORDER_USD establishes the minimum permitted order value.
• MAX_ORDER_USD caps the value of an individual order.
• MAX_POSITION_USD_PER_TOKEN limits approximate exposure for each token.
• DAILY_MAX_NOTIONAL_USD limits total daily notional activity.
• ORDER_TYPE controls fill behavior.
• PRICE_PROTECTION_BPS optionally constrains execution relative to the followed fill price.

Understand FAK and FOK Orders

With ORDER_TYPE=FAK, the order may fill partially, after which the unfilled remainder is canceled. With ORDER_TYPE=FOK, the entire order must fill; otherwise, the order fails.

FAK may be suitable when partial execution is acceptable. FOK is stricter, but it may cause more orders to fail when full liquidity is unavailable.

Apply Price Protection

When PRICE_PROTECTION_BPS=0, the CLOB client estimates the marketable worst price. When a nonzero value is configured, the bot calculates a worst-price limit above the followed fill price for buys and below it for sells.

Price protection can limit tolerated price movement, but the README does not guarantee that an order will fill when this setting is enabled.

Run a Simulation First

Start with the project's test command:

npm run test

This mode produces simulated orders rather than live market orders. Use it to validate wallet monitoring, sizing behavior, risk limits, and environment settings without immediately submitting live trades.

During testing, verify that:

1. The intended wallets are being monitored.
2. Buy and sell events are normalized correctly.
3. The selected copy mode generates the expected sizes.
4. Orders respect minimum, maximum, position, and daily limits.
5. Sell sizes do not exceed the locally tracked position.
6. State is recorded under ./data/state.json.

Start Live Trading

After reviewing the simulation results, wallet funding, approvals, credentials, and all risk settings, start live execution with:

npm start

This command enables live market orders. Begin with tiny sizes and monitor both the terminal output and the Polymarket account. Do not assume that simulated outcomes will exactly match live fills, liquidity, or price movement.

Understand Local State

The bot stores its local state at:

./data/state.json

This file tracks seen trades, simulated or executed orders, and approximate positions. It helps prevent previously processed activity from being treated as new and gives sell-following logic a local view of available positions.

Positions are only approximate because market orders may fill partially. Local state can therefore diverge from actual account holdings.

Advanced Operational Tips

Add Position Reconciliation

For production use, the README recommends adding a periodic reconciliation job. The job should query the Data API's /positions endpoint for POLYMARKET_DEPOSIT_WALLET and compare the returned positions with the local state.

This is especially important after partial fills, failed orders, manual trades, restarts, or any activity performed outside the bot.

Protect the State File

Back up ./data/state.json before upgrades or operational changes. Avoid editing it while the bot is running. Because it records seen activity and approximate positions, deleting or corrupting it may affect duplicate detection and sell sizing.

Use Conservative Limits

Start with a low MAX_ORDER_USD, MAX_POSITION_USD_PER_TOKEN, and DAILY_MAX_NOTIONAL_USD. Increase them only after observing the bot under realistic market conditions. Risk limits constrain exposure, but they do not eliminate execution, liquidity, market, or software risk.

Review the Relevant Source Files

The repository separates configuration, polling, strategy, execution, and state responsibilities:

• src/config.ts handles environment parsing and safety checks.
• src/index.ts contains the main polling loop.
• src/polymarket/dataApi.ts performs public Data API reads.
• src/watchers/walletWatcher.ts polls activity for multiple wallets.
• src/polymarket/tradeParser.ts normalizes activity events.
• src/strategy/copyStrategy.ts implements fixed and percentage sizing.
• src/strategy/riskManager.ts enforces order, daily, and position limits.
• src/polymarket/orderExecutor.ts handles simulated and live execution.
• src/storage/stateStore.ts manages local JSON state.

Reviewing these files is useful before live deployment, particularly if you need to understand polling behavior, safety checks, event normalization, or order sizing.

Conclusion

The Polymarket CodeX CopyTrading Bot provides a TypeScript workflow for monitoring multiple wallets and copying eligible buys and sells with fixed or percentage-based sizing. Configure credentials carefully, enforce conservative risk limits, validate behavior through npm run test, and reconcile local positions before relying on npm start for live trading.