py-clob-client v2 (2026): Migrating to the Unified Polymarket SDK

Why are py-clob-client and py-clob-client-v2 being replaced?

Two changes happened in sequence. On 28 April 2026, Polymarket's CLOB V2 went live with new Exchange contracts, pUSD as collateral and a new order struct, and the changelog was explicit: "Legacy V1 SDKs and V1-signed orders are no longer supported on production." That ended the original py-clob-client and @polymarket/clob-client for trading. The V2 clients, py-clob-client-v2 and @polymarket/clob-client-v2, carried integrations through the cutover.

The unified SDKs are the second step. Polymarket's guide migrates "from the previous CLOB, relayer, and builder-signing clients to the unified SDK," so one client now covers market discovery, order books, trading, positions, gasless wallet actions and the Gamma and Data APIs. New features land there too: the SDK changelog adds session keys, PolyBolt price streams and Combos quotes to the unified clients.

Neither registry marks the older packages as deprecated, and py-clob-client-v2 got a 1.2.0 release on 25 September 2026. Polymarket's docs and examples, though, are written for the unified clients. These are the versions checked on 13 October 2026:

How do you install the unified Polymarket SDK?

# Python: remove the old clients, then install the unified SDK
pip uninstall -y py-clob-client-v2 py-builder-relayer-client py-builder-signing-sdk
pip install polymarket-client

# TypeScript: the same move on npm
npm uninstall @polymarket/clob-client-v2 @polymarket/builder-relayer-client @polymarket/builder-signing-sdk
npm install @polymarket/client@latest viem

What changes in authentication?

This is the biggest structural change. With py-clob-client-v2, you built a client, derived credentials, then built a second client with the credentials, a signature type and a funder address:

import os

from py_clob_client_v2 import OrderArgs, Side
from py_clob_client_v2.client import ClobClient
from py_clob_client_v2.order_utils.model import SignatureTypeV2

HOST = "https://clob.polymarket.com"
KEY = os.environ["POLYMARKET_PRIVATE_KEY"]

creds = ClobClient(HOST, chain_id=137, key=KEY).create_or_derive_api_key()
client = ClobClient(
    HOST,
    chain_id=137,
    key=KEY,
    creds=creds,
    signature_type=SignatureTypeV2.POLY_1271,
    funder=os.environ["POLYMARKET_WALLET_ADDRESS"],
)

response = client.create_and_post_order(
    OrderArgs(token_id="YOUR_TOKEN_ID", price=0.52, size=10, side=Side.BUY)
)
print(response)

With polymarket-client, one awaited call does all of that, and the client works as an async context manager:

import asyncio
import os

from polymarket import AsyncSecureClient


async def main() -> None:
    async with await AsyncSecureClient.create(
        private_key=os.environ["POLYMARKET_PRIVATE_KEY"],
        wallet=os.environ["POLYMARKET_WALLET_ADDRESS"],
    ) as client:
        response = await client.place_limit_order(
            asset_id="YOUR_TOKEN_ID",
            price="0.52",
            size="10",
            side="BUY",
        )
        if response.ok:
            print(response.order_id, response.status)
        else:
            print(response.code, response.message)


asyncio.run(main())

The rest of the authentication changes follow the same pattern:

• Credentials. create_or_derive_api_key() runs inside create(), which "derives or creates CLOB credentials, resolves the account wallet, and configures signing."
• Wallet. signature_type and funder become wallet=. Leave it out to use the default Deposit Wallet flow. If the signer and wallet split is unclear, the Polymarket proxy wallet guide explains it.
• Resuming. Store client.credentials and pass it back as credentials=.
• Revoking. delete_api_key() becomes end_authentication(), which revokes the key and returns a public client.
• Builder and relayer keys. BuilderConfig and RelayClient give way to api_key=BuilderApiKey(...) or api_key=RelayerApiKey(key=..., address=...).

How do py-clob-client-v2 methods map to the unified SDK?

Two rows differ from Polymarket's migration guide. Its Python examples still show get_price_history and list_trades(market=...), but SDK 0.10.0 replaced them with list_price_history and condition_id, and in our check of 0.13.0, get_price_history no longer exists. The SDK changelog is the safer reference when the two disagree.

What are the common migration pitfalls?

• Missing await. Methods on AsyncSecureClient are coroutines. For scripts, SecureClient.create() offers the same methods synchronously, but realtime subscriptions are async only.
• Positional arguments. Most new methods are keyword-only, so get_order_book("TOKEN_ID") raises a TypeError. Write get_order_book(asset_id="TOKEN_ID"). post_order and post_orders are the exceptions, taking signed orders directly.
• The market order default. create_and_post_market_order defaulted to FOK, while place_market_order defaults to FAK and estimate_market_price still models FOK. Pass order_type explicitly.
• user_usdc_balance is not max_spend. The old field supplied your balance for fee adjustment. max_spend is the most you want to spend including fees, so set it equal to amount for an all-in budget or leave it out to pay fees on top.
• Rejections are values. A rejected order comes back with ok set to False, a code and a message, so check response.ok. Restarts and post-only mode raise RequestRejectedError instead.
• Lists are paginators. list_open_orders, list_account_trades and list_trades return paginators, so call first_page() or iterate with iter_items().

Trading involves risk, and a changed default can change how an order fills, so run the migrated bot with small orders before you size it back up.

Where does Predictefy fit in a Python stack?

A migration is a good moment to separate venue plumbing from strategy code. The Predictefy API and its Python SDK, predictefy, read 15+ venues through one normalized schema, with a non-custodial trading workflow. Paper trading costs 0 credits on every plan, which makes it an easy place to rehearse a migrated bot's order flow before it trades for real.

Frequently Asked Questions