Paper trading against the real order book
A paper trade should be judged against prices you could actually have traded at, not the midpoint. That means:
- A simulated buy fills at the current best ask, a simulated sell at the best bid.
- If your size is larger than the quantity at that price, "walk the book": fill what the best level holds, then the next level, and average the prices you would have paid.
- Charge the taker fee for the market's category on every simulated taker fill. See the fee guide.
- Record the time, the book you saw, the price you assumed and why the bot traded. You will need this to find out why a strategy that looked good did not work.
The paper-trading script in the API guide follows these rules using only public endpoints. It needs no account and cannot place an order.
How long to paper trade
Long enough to see the conditions the bot will meet: quiet hours, fast news, a market resolving, and an API error. For a bot trading daily markets that usually means weeks, not an afternoon. A strategy with a handful of simulated trades has not been tested; it has been tried.
What paper trading cannot show
Your own orders change the market. A resting order can be filled by someone who knows more than you, and a large order moves the price. Start live trading at a size small enough that these effects do not matter, then increase slowly while comparing live fills with the paper results.
Risk limits every bot needs
| Limit | What it stops | A sensible starting point |
|---|---|---|
| Maximum order size | One bad signal taking a large position | Smaller than the depth at the best price |
| Maximum position per market | Piling into one outcome as the price moves against you | A fixed dollar amount you could lose entirely |
| Daily loss limit | A broken loop trading all day | Stop trading for the day when reached, and alert you |
| Orders per minute | Runaway loops and rate-limit bans | Well under the API's published limits |
| Stale data check | Trading on a frozen feed | Pause if the book has not updated for longer than you expect |
| Price sanity check | Trading on a bad quote | Refuse prices off the market's tick grid, outside 0 to 1, or far from the last trade |
Put these limits in code that runs before every order, not in a note you hope to remember. Log every time a limit blocks an order; it is the cheapest way to find bugs.
The kill switch
You need one action that cancels all open orders and stops the bot from placing new ones, and you need to have tested it. Polymarket's CLOB API supports cancelling all of an account's open orders in one request. Wire that to a command you can run from your phone, and make the bot call it on its own when a loss limit or stale-data check trips.
Keeping keys and credentials safe
Polymarket International trading uses two kinds of secret:
- Your wallet's private key signs orders and controls your funds. Anyone who has it can take everything in the wallet, so never share it.
- API credentials (a key, secret and passphrase) are derived from the wallet and authenticate trading requests. They can be revoked and recreated.
Practical rules:
- Use a separate wallet for the bot, funded with only what the bot may lose.
- Keep secrets in environment variables or a secrets manager, never in code, a repository or a chat.
- Never paste a private key or seed phrase into a website, Telegram bot or form. No legitimate tool needs your seed phrase.
- Make sure logs never print secrets. Search your logs for them.
Checking third-party bot code
Open-source Polymarket bots are useful to learn from and risky to run unread. Before installing one:
- Check identity. Install official SDKs only from the links in Polymarket's documentation. Lookalike package names exist in every ecosystem.
- Read the install steps. Look for install scripts, downloaded binaries and dependencies you do not recognise.
- Find where secrets go. Search the code for the variable that holds your key and follow it. It should only ever reach the signing library.
- Check network calls. A trading bot should talk to Polymarket's APIs and your own services. Anything else needs a reason.
- Run it on paper first, with a new wallet that holds nothing.
If a key may have leaked
Stop the bot. If only API credentials were exposed, revoke them and create new ones. If the wallet's private key or seed phrase was exposed, assume the wallet is lost: move the funds to a new wallet you created yourself, from a clean device, as fast as you can. Do not follow recovery instructions from the tool you suspect.
Rewritten November 15, 2026 from our earlier paper-mode and code-security guides. Sources: API authentication, order and cancel limits.
Part of the Polymarket trading bots handbook.