Polymarket Protocol V2 SDK Migration

Update your integration to trade on Polymarket Protocol V2 markets while keeping support for existing CTF markets. Before you start:

If you use a standalone CLOB SDK, complete the unified SDK migration first to update client setup.
If upgrading from before 0.10.0 and using portfolio or history reads, also apply the Data API v2 migration.

Upgrade the SDK

TypeScript
Python

Upgrade @polymarket/client to the latest release (0.12.0 or later) using your preferred package manager.

npm install @polymarket/client@latest

bun add @polymarket/client@latest

pnpm add @polymarket/client@latest

yarn add @polymarket/client@latest

Upgrade polymarket-client to the latest release (0.12.0 or later) using your preferred package manager. Requires Python 3.11 or later.

uv add --upgrade-package polymarket-client "polymarket-client>=0.12.0"

python -m pip install --upgrade "polymarket-client>=0.12.0"

poetry add polymarket-client@latest

Ensure Trading Approvals

TypeScript
Python

Keep calling setupTradingApprovals() on your SecureClient. It also approves the contracts required for Polymarket Protocol V2. Gasless wallets need a configured Relayer or Builder API key.

await client.setupTradingApprovals();

Keep calling setup_trading_approvals() on your AsyncSecureClient. It also approves the contracts required for Polymarket Protocol V2. Gasless wallets need a configured Relayer or Builder API key.

await client.setup_trading_approvals()

Select the Trading ID

TypeScript
Python

Given a market, for example returned by fetchMarket(), check its version: use the desired outcome’s positionId for V2 or tokenId for V1. This example selects YES:

const outcome = market.outcomes.yes;
const assetId =
  market.version === ProtocolVersion.V2 ? outcome.positionId : outcome.tokenId;

Given a market, for example returned by get_market(), check its version: use the desired outcome’s position_id for V2 or token_id for V1. This example selects YES:

outcome = market.outcomes.yes
asset_id = outcome.position_id if market.version == ProtocolVersion.V2 else outcome.token_id

Trade as Usual

TypeScript
Python

Use the selected assetId:

import { OrderSide } from "@polymarket/client";

const response = await client.placeLimitOrder({
  assetId,
  side: OrderSide.BUY,
  price: "0.50",
  size: "10",
});

Use the selected ID for order books, prices, and market subscriptions too.

Use the selected asset_id:

response = await client.place_limit_order(
    asset_id=asset_id,
    side="BUY",
    price="0.50",
    size="10",
)

Use the selected ID for order books, prices, and market subscriptions too.

Verify the Migration

Verify BUY and SELL fills and balances on both a V2 market and a CTF market.

Read Balances and Allowances

TypeScript
Python

Read balances and allowances using the asset ID selected earlier:

import { AssetType, ProtocolVersion } from "@polymarket/client";

const { balance, allowances } = await client.fetchBalanceAllowance({
  assetId,
  assetType: market.version === ProtocolVersion.V2
    ? AssetType.CONDITIONAL_V2
    : AssetType.CONDITIONAL,
});

console.log(balance, allowances);

Balances and allowances are returned in base units. Allowances are keyed by spender address. To refresh before reading, use updateBalanceAllowance with the same parameters.

Read balances and allowances using the asset ID selected earlier:

from polymarket import ProtocolVersion

result = await client.get_balance_allowance(
    asset_id=asset_id,
    asset_type=(
        "CONDITIONAL-V2"
        if market.version == ProtocolVersion.V2
        else "CONDITIONAL"
    ),
)

print(result.balance, result.allowances)

Balances and allowances are returned in base units. Allowances are keyed by spender address.

Update Resolution Reads

If your integration tracks V2 market resolution:

TypeScript
Python

Call fetchResolutions for the selected market:

if (!market.conditionId) throw new Error("Missing condition ID");

const resolutions = await client.fetchResolutions({
  conditionIds: [market.conditionId],
});

Use payouts only from a row whose status is "resolved".

Call get_resolutions for the selected market:

if not market.condition_id:
    raise ValueError("Missing condition ID")

resolutions = await client.get_resolutions(condition_ids=[market.condition_id])

Use payouts only from a row whose status is "resolved".

Getting Started

Core Concepts

Market Data

Trading

Programs

Migration Guides

Resources

Verify the Migration

Read Balances and Allowances

Update Resolution Reads

​Verify the Migration

​Read Balances and Allowances

​Update Resolution Reads

Verify the Migration

Read Balances and Allowances

Update Resolution Reads