Polymarket trading bot in Python vs Circuit
Updated by the Circuit team
Start with the right library
Most Polymarket bot tutorials use py-clob-client. That repository is now archived. Its README says the client "is no longer functional and should not be used for new or existing integrations". Its successor, py-clob-client-v2, is marked deprecated too.
Polymarket's current Python SDK is polymarket-client, from the Polymarket/py-sdk repository, installed with pip install polymarket-client. It has a PublicClient for market data and a SecureClient for trading, each in sync and async forms. The TypeScript equivalent is @polymarket/client. Polymarket's docs include a migration guide from the old CLOB, relayer and builder-signing clients.
Popular open-source bots on GitHub, with stars as of October 17, 2026:
| Repository | Stars | License | What it does |
|---|---|---|---|
| Polymarket/agents | 3,800 | MIT | Polymarket's AI agent framework, last updated November 2024 |
| warproxxx/poly-maker | 1,512 | MIT | Market making bot that quotes both sides of the book |
| Polymarket/py-clob-client | 1,227 | MIT | Archived CLOB client |
| sterlingcrispin/nothing-ever-happens | 981 | CC0-1.0 | Buys No on every non-sports market, "mostly a meme" per its author |
Check the last commit date and the client library before you copy a bot. Code built on the archived client will not run as written, per that client's README.
What a Python bot must handle
Each row is a step your code owns when you build on the SDK. The right column is what Circuit does for a bot written with its Polymarket SDK.
| Step | What Polymarket requires | How Circuit handles it |
|---|---|---|
| Account | A Deposit Wallet, the default for accounts deployed on or after May 4, 2026. Proxy and Safe wallets are legacy | Deploys the Deposit Wallet for wallets it created. Imported wallets need a deployed Deposit Wallet or an eligible EOA |
| Authentication | L1: an EIP-712 wallet signature to create or derive API keys. L2: HMAC headers on every order | The engine derives CLOB credentials and signs orders. Your bot code never holds a key |
| Collateral | pUSD, an ERC-20 on Polygon backed by USDC. Wrapping USDC.e needs an approval of the CollateralOnramp first | Prepares funding and wrapping as separate actions you review |
| Allowances and gas | EOAs set token allowances before trading. Gasless wallet actions need a Relayer API key | Approvals run as their own operations. Deposit Wallet actions go through the relayer, and EOAs pay Polygon gas |
| Order rules | Prices on the market's tick size, sizes above its minimum. GTC, GTD, FOK and FAK order types | Buys take a pUSD amount that includes fees, sells take shares and round down to venue precision |
| Settlement | Matches settle onchain asynchronously, so you wait for settlement before reading positions | Observes fills and keeps settlement receipts on each operation |
| Resolution | Winning shares redeem for $1, losing shares for $0. You call redemption yourself | positions.redeem redeems both outcomes of a resolved market in one action |
| Restricted keys | Session Keys, in beta, trade for up to 180 days and cannot withdraw. Authorizing one needs a Builder API key | Bots never hold a key. Circuit signs only under the permit you signed with your passkey when the bot started |
Worked example: fees and break-even
Polymarket charges takers a fee of C × feeRate × p × (1 − p), where C is shares and p is the price. Makers pay nothing, and geopolitics markets are fee-free. Rates in Polymarket's fee table range from 0.04 for politics, finance and tech to 0.07 for crypto.
Buy 100 YES shares in a sports market at $0.40, with a fee rate of 0.05:
- Cost of shares: 100 × $0.40 = $40.00
- Taker fee: 100 × 0.05 × 0.40 × 0.60 = $1.20
- Total paid: $41.20
- Payout if YES wins: $100.00, a profit of $58.80
- Break-even probability: $41.20 ÷ $100 = 41.2%, against the 40% the price implies
The same 100 shares at $0.50 in a crypto market cost $1.75 in fees, the highest point of that curve. A bot that takes liquidity on many cheap edges can lose its whole edge to fees. Circuit's orders.quote includes Polymarket's fees in the quoted price, so a bot can compare its estimate against the real cost before it buys.
Resolution is slower than you think
Per Polymarket's docs, most markets resolve through the UMA Optimistic Oracle. A proposer posts a bond, typically $750 pUSD, then a 2-hour challenge period runs. Undisputed markets resolve about 2 hours after the proposal. A disputed market takes 4 to 6 days, and a market judged unknown resolves 50/50 with each share redeeming for $0.50. Up-down crypto markets resolve from a Chainlink TWAP instead.
A DIY bot needs to track all of this: which markets it holds, which have resolved, and which need a redeem call. On Circuit, a Polymarket resolution trigger in circuit.toml wakes the bot on outcome resolution, and the bot calls positions.redeem for each resolved market it holds. See Polymarket trading bots for the full set of Circuit actions.
How Circuit runs the same bot
A Circuit bot is TypeScript. A minimal loop that buys longshots below a price looks like this in prose:
- Call agent.polymarket.markets.screen with endsWithinMs, a price band such as lowestPricePusd 0.03 and highestPricePusd 0.10, a minLiquidityPusd floor and the stake you plan to bet.
- For each candidate, call orders.quote with side BUY and spendPusd to get the price after fees.
- Call orders.create for the ones your rule accepts, sized from the bot's pUSD in agent.allocation.
- On each run, call positions.redeem for holdings marked redeemable.
The SDK also splits pUSD into both outcomes, merges them back, and converts No shares across a negRisk event. Redemption readiness comes from onchain resolution, and each operation keeps its fills and settlement receipts.
You can build the same bot without code. Describe it in Terminal and the Builder writes it, then paper trade it. In paper trading, Polymarket orders fill against the live order book and redemptions pay each market's real resolution. Circuit's backtester covers Hyperliquid and Lighter perps only, so Polymarket strategies are tested on paper. Read crypto paper trading for how simulated fills work, or Polymarket trading bot with Claude to build one in conversation.
Telegram bots and hosted services
Searches for a Polymarket Telegram bot lead to hosted services that trade for you from a chat. Any such service must hold a key that can sign for your Polymarket account. Ask which key. If it holds the owner key of your wallet, it can withdraw everything. If it holds a Polymarket Session Key, it can trade for up to 180 days but cannot withdraw, per Polymarket's docs. Never paste a private key or seed phrase into a chat.
Circuit is also hosted, and it holds a key. Circuit keeps the signing key in a hardware enclave, bots never see it, and Circuit signs only under a permit you sign with your passkey. You can export the key from Settings at any time.
When Python is the better choice
Write it yourself in Python if your edge comes from a model trained with scikit-learn or PyTorch, if you need to quote both sides of many books at once like poly-maker does, or if you want Polymarket's newest features on the day they ship, such as Combos or Polymarket Perps. You also avoid depending on any platform.
Use Circuit if you want the bot hosted, the key handling and redemption done for you, and the option to pair a prediction with a Hyperliquid perp in the same bot. Circuit charges no builder fee on Polymarket and no fees today. For a market making approach, see the market making bot guide.
Test before you risk money
Every bot starts in paper trading: simulated funds on live markets, with no real money moving. Hyperliquid, Lighter and Kraken orders fill against the live order book and one-minute bars with each venue's fees, funding and liquidation rules. Polymarket orders fill against the live book, and redemptions pay the market's real resolution. Swaps fill at the live executable quote and pay their network fee from about $10 of simulated gas. Paper sessions stay private and never count toward the leaderboard. Switch the same bot to real money when the results convince you.
What it costs
Circuit charges no fees today and adds no builder fee to Hyperliquid or Polymarket orders. You pay the venue's trading fees, network gas and any bridge or routing fees, and each prepared action's review shows the costs it reports before you confirm. Today's terms make no commitment about future fees.
FAQ
Is py-clob-client still supported?
No. Polymarket archived py-clob-client, and its README says it is no longer functional. py-clob-client-v2 is deprecated. Use polymarket-client from Polymarket/py-sdk, installed with pip install polymarket-client.
How do I get Polymarket API keys?
The CLOB uses two levels. An L1 EIP-712 signature from your wallet creates or derives API credentials, and L2 HMAC headers built from those credentials sign each order request. The unified SDK's SecureClient does both. Gasless wallet actions also need a Relayer API key from polymarket.com settings.
Does a Polymarket bot need USDC or pUSD?
pUSD. It is Polymarket's ERC-20 collateral on Polygon, backed by USDC. You wrap USDC.e through the CollateralOnramp contract or deposit through Polymarket's bridge, which wraps for you.
Can a Polymarket bot redeem winnings automatically?
Yes, if you code it. Winning shares redeem for $1 after resolution. On Circuit, a resolution trigger wakes the bot and positions.redeem redeems both outcomes of a resolved market in one action.
Is there a Polymarket bot on GitHub I can use?
Polymarket/agents is the official AI agent framework, last updated in November 2024. warproxxx/poly-maker is a popular market maker. Check that any bot uses the unified SDK and pUSD before you fund it.
Can I paper trade Polymarket?
Polymarket's docs describe no paper trading mode. Circuit paper sessions fill Polymarket orders against the live order book and pay real resolutions with simulated pUSD.