Polymarket trading agent in Python vs Circuit

Most Polymarket agent 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. Install it with pip install polymarket-client. It has a PublicClient for market data and a SecureClient for trading. Each comes 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 agents on GitHub with stars as of October 17, 2026:

Check the last commit date and the client library before you copy an agent. Code built on the archived client will not run as written. That client's README says so.

Each row is a step your code owns when you build on the SDK. The right column is what Circuit does for an agent written with its Polymarket SDK.

Polymarket charges takers a fee of C × feeRate × p × (1 − p). C is shares and p is the price. Makers pay nothing. 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 for 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. That is the highest point of the curve. An agent 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. An agent can compare its estimate against the real cost before it buys.

Per Polymarket's docs most markets resolve through the UMA Optimistic Oracle. A proposer posts a bond of typically $750 pUSD. Then a 2-hour challenge period runs. Undisputed markets resolve about 2 hours after the proposal. A disputed market adds a 24 to 48 hour debate and about 48 hours of UMA voting. That can take several days. A market judged unknown resolves 50/50 and each share redeems for $0.50. Up-down crypto markets resolve from a Chainlink TWAP instead.

A DIY agent 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 agent on outcome resolution. The agent calls positions.redeem for each resolved market it holds. See Polymarket trading agents for the full set of Circuit actions.

A Circuit agent is TypeScript. A minimal loop that buys longshots below a price looks like this in prose:

1. 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 put in.
2. For each candidate call orders.quote with side BUY and spendPusd to get the price after fees.
3. Call orders.create for the ones your rule accepts. Size them from the agent's pUSD in agent.allocation.
4. 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. Each operation keeps its fills and settlement receipts.

You can build the same agent without code. Describe it to Circuit 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. Polymarket strategies are tested on paper. Read crypto paper trading for how simulated fills work. Read Polymarket trading agent with Claude to build one in conversation.

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. Polymarket's docs say a Session Key can trade for up to 180 days and cannot withdraw. Never paste a private key or seed phrase into a chat.

Circuit is also hosted, but its wallets are self-custodial. Circuit keeps the signing key in a hardware enclave and agents never see it. Nothing is signed without a permit you sign with your passkey. You can export the key from Settings at any time.

Write it yourself in Python if your edge comes from a model trained with scikit-learn or PyTorch. Python also wins if you need to quote both sides of many books at once like poly-maker does. It wins if you want Polymarket's newest features such as Combos or Polymarket Perps on the day they ship. You also avoid depending on any platform.

Use Circuit if you want the agent hosted with key handling and redemption done for you. Circuit can also pair a prediction with a Hyperliquid perp in the same agent. Circuit charges no builder fee on Polymarket and no fees today. For a market making approach, see the market making agent guide.

Agents start in paper trading by default. That means simulated funds on live markets and no real money moving. Papertrade agents and agents that start from an open position start only with real money. Hyperliquid, Lighter, Lighter Robinhood 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. 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 agent to real money when the results convince you.

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. Each prepared action's review shows the costs it reports before you confirm. Today's terms make no commitment about future fees.

Is py-clob-client still supported?

No. Polymarket archived py-clob-client. Its README says it is no longer functional. py-clob-client-v2 is deprecated. Use polymarket-client from Polymarket/py-sdk. Install it 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. 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 agent need USDC or pUSD?

pUSD. It is Polymarket's ERC-20 collateral on Polygon. USDC backs it. You wrap USDC.e through the CollateralOnramp contract or deposit through Polymarket's bridge. The bridge wraps for you.

Can a Polymarket agent redeem winnings automatically?

Yes if you code it. Winning shares redeem for $1 after resolution. On Circuit a resolution trigger wakes the agent and positions.redeem redeems both outcomes of a resolved market in one action.

Is there a Polymarket agent on GitHub I can use?

Polymarket/agents is the official AI agent framework. It was last updated in November 2024. warproxxx/poly-maker is a popular market maker. Check that any agent 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.