> ## Documentation Index
> Fetch the complete documentation index at: https://docs.polymarket.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Migrating to CLOB V2

> A complete guide to upgrading your integration to Polymarket's CLOB V2 — new contracts, new backend, new collateral token, and a simpler builder program.

Polymarket has shipped a coordinated upgrade of its entire trading infrastructure: **new Exchange contracts**, a **rewritten CLOB backend**, and a **new collateral token** (Polymarket USD, or pUSD). This guide walks you through everything you need to migrate from CLOB V1 to CLOB V2.

> [!WARNING]
>
> **CLOB V2 is live as of April 28, 2026.** Legacy V1 SDKs and V1-signed orders are no longer supported on production. Upgrade to the V2 SDK or update your raw order signing before submitting orders to `https://clob.polymarket.com`.

> [!NOTE]
>
> **Production URL:** CLOB V2 now runs at `https://clob.polymarket.com`. The pre-cutover `https://clob-v2.polymarket.com` testing host is no longer the integration target for production clients.

***

## TL;DR

| What | Before (V1) | After (V2) |
| - | - | - |
| SDK package | `@polymarket/clob-client` / `py-clob-client` | `@polymarket/clob-client-v2` / `py-clob-client-v2` |
| Constructor | Positional args | Options object, `chainId` → `chain` |
| Order fields | `nonce`, `feeRateBps`, `taker` | `timestamp` (ms), `metadata`, `builder` |
| Fees | Embedded in the signed order | Operator-set at match time |
| Collateral | USDC.e | **pUSD** (standard ERC-20, backed by USDC) |
| Builder auth | `POLY_BUILDER_*` HMAC headers + [`builder-signing-sdk`](https://github.com/Polymarket/builder-signing-sdk) | A single `builderCode` field on the order |
| EIP-712 domain version | `"1"` | `"2"` (exchange only — API auth unchanged) |
| Exchange `verifyingContract` (raw API signers) | V1 addresses | V2 addresses — see [Contracts](/resources/contracts) |
| Raw API order signing | V1 Order type | Updated Order type — [see API users section](#for-api-users) |

**If you're on the latest SDK,** most of this is handled automatically. If you're signing orders manually, update the EIP-712 domain, order fields, and contract addresses described below.

***

## Before you start

**1. Read this guide end-to-end**

Even if a section doesn't look relevant, skim it. V2 touches more surface area than any previous release.

**2. Pin the latest SDK**

Install the V2 SDK: [`@polymarket/clob-client-v2`](https://www.npmjs.com/package/@polymarket/clob-client-v2) (TypeScript) or [`py-clob-client-v2`](https://pypi.org/project/py-clob-client-v2/) (Python). Don't keep using the old `clob-client` / `py-clob-client` packages — those only work against V1 and no longer function against production.

**3. Test with a funded wallet**

Use a small funded wallet to test market discovery, order signing, posting, cancellation, and settlement behavior end-to-end on production.

> [!WARNING]
>
> **Open orders from before the CLOB V2 cutover were wiped.** If you had resting V1-era orders, they did not migrate and must be re-created with V2 order signing.

***

## What's changing

### 1. New Exchange contracts

The onchain exchange has been rewritten from the ground up.

* Solidity upgraded from **0.8.15 → 0.8.30**, with Solady replacing OpenZeppelin for gas savings.
* Order struct simplified: `nonce`, `feeRateBps`, and `taker` removed; `timestamp`, `metadata`, `builder` added.
* EIP-712 exchange domain version bumped from `"1"` to `"2"`.
* Fees collected onchain at match time (no longer embedded in the signed order).
* Onchain cancel replaced with operator-controlled `pauseUser` / `unpauseUser`.
* Batched mint/merge operations for gas efficiency.

See [Contracts](/resources/contracts) for V2 addresses.

### 2. Rewritten CLOB backend

The order manager, ledger, executor, balance checker, and tracker are all new services. From an integrator's perspective:

* **Nonce system removed.** Order uniqueness now comes from `timestamp` (milliseconds). You no longer track nonces.
* **New fee model.** Platform fees are dynamic per market and queryable via `getClobMarketInfo()`.
* **Builder codes** enable integrator attribution and revenue sharing, replacing the old HMAC-header flow.

### 3. New collateral token

Polymarket is migrating from **USDC.e** to **pUSD** (Polymarket USD), a standard ERC-20 on Polygon backed by USDC. Backing is enforced onchain by the smart contract.

* For users trading on polymarket.com, the frontend handles wrapping automatically with a one-time approval.
* Power users and API-only traders wrap their USDC.e into pUSD via the Collateral Onramp contract's `wrap()` function.

***

## For API users

If you sign and post orders directly (without the SDK), here's what changes in the wire protocol. SDK users can skip this section — the client handles it.

### EIP-712 domain

The Exchange domain version bumps to `"2"` and the `verifyingContract` moves to the V2 Exchange.

```ts theme={null}
{
  name: "Polymarket CTF Exchange",
  version: "1", // [!code --]
  version: "2", // [!code ++]
  chainId: 137,
  verifyingContract: "0x4bFb41d5B3570DeFd03C39a9A4D8dE6Bd8B8982E", // [!code --]
  verifyingContract: "0xE111180000d2663C0091e4f400237545B87B996B", // [!code ++]
}
```

For Neg Risk markets, the `verifyingContract` is different:

```ts theme={null}
{
  verifyingContract: "0xC5d563A36AE78145C45a50134d48A1215220f80a", // [!code --]
  verifyingContract: "0xe2222d279d744050d28e00520010520000310F59", // [!code ++]
}
```

See [Contracts](/resources/contracts) for the canonical V2 addresses.

> [!NOTE]
>
> **Only the Exchange domain changes.** The `ClobAuthDomain` used for L1 API authentication stays at version `"1"` — L1/L2 auth is identical in V2.

### EIP-712 Order type

The signed struct drops `taker`, `expiration`, `nonce`, and `feeRateBps`, and adds `timestamp`, `metadata`, and `builder`.

```ts theme={null}
Order(
  uint256 salt,
  address maker,
  address signer,
  address taker, // [!code --]
  uint256 tokenId,
  uint256 makerAmount,
  uint256 takerAmount,
  uint256 expiration, // [!code --]
  uint256 nonce, // [!code --]
  uint256 feeRateBps, // [!code --]
  uint8 side,
  uint8 signatureType // [!code --]
  uint8 signatureType, // [!code ++]
  uint256 timestamp, // [!code ++]
  bytes32 metadata, // [!code ++]
  bytes32 builder // [!code ++]
)
```

### Order value to sign

```ts theme={null}
{
  salt: "12345",
  maker: "0x...",
  signer: "0x...",
  taker: "0x0000000000000000000000000000000000000000", // [!code --]
  tokenId: "102936...",
  makerAmount: "1000000",
  takerAmount: "2000000",
  expiration: "0", // [!code --]
  nonce: "0", // [!code --]
  feeRateBps: "0", // [!code --]
  side: 0,
  signatureType: 1 // [!code --]
  signatureType: 1, // [!code ++]
  timestamp: "1713398400000", // [!code ++]
  metadata: "0x0000000000000000000000000000000000000000000000000000000000000000", // [!code ++]
  builder: "0x0000000000000000000000000000000000000000000000000000000000000000" // [!code ++]
}
```

* **`timestamp`** — order creation time in milliseconds. Replaces `nonce` for per-address uniqueness (not an expiration).
* **`metadata`** — bytes32.
* **`builder`** — bytes32. Zero unless you're attaching a builder code.

`side` is encoded as `uint8` in the signing payload (`0` = BUY, `1` = SELL), even though the wire body uses the string `"BUY"` / `"SELL"`. No change from V1.

### POST /order body

`expiration` is still present in the `POST /order` wire body for GTD/order-expiry handling, but it is **not** part of the V2 EIP-712 signed struct.

```ts theme={null}
{
  "order": {
    "salt": "12345",
    "maker": "0x...",
    "signer": "0x...",
    "taker": "0x0000000000000000000000000000000000000000", // [!code --]
    "tokenId": "102936...",
    "makerAmount": "1000000",
    "takerAmount": "2000000",
    "expiration": "0",
    "nonce": "0", // [!code --]
    "feeRateBps": "0", // [!code --]
    "side": "BUY",
    "signatureType": 1,
    "timestamp": "1713398400000", // [!code ++]
    "metadata": "0x0000000000000000000000000000000000000000000000000000000000000000", // [!code ++]
    "builder": "0x0000000000000000000000000000000000000000000000000000000000000000", // [!code ++]
    "signature": "0x..."
  },
  "owner": "<api-key>",
  "orderType": "GTC",
  "postOnly": false
}
```

### Request headers

The API auth headers are unchanged. Builder attribution moves into the signed `builder` field on the order, so the `POLY_BUILDER_*` HMAC headers are gone.

```yaml theme={null}
POLY_ADDRESS: 0x...
POLY_SIGNATURE: 0x...
POLY_TIMESTAMP: 1713398400
POLY_API_KEY: ...
POLY_PASSPHRASE: ...
POLY_BUILDER_API_KEY: ...        # [!code --]
POLY_BUILDER_SECRET: ...         # [!code --]
POLY_BUILDER_PASSPHRASE: ...     # [!code --]
POLY_BUILDER_SIGNATURE: 0x...    # [!code --]
```

***

## SDK Migration

### Install

CLOB V2 ships under new package names. Install them directly — don't keep using the old `clob-client` / `py-clob-client` packages.

```bash TypeScript theme={null}
npm install @polymarket/clob-client-v2 viem
```

```bash Python theme={null}
pip install py-clob-client-v2
```

> [!WARNING]
>
> The legacy `@polymarket/clob-client` and `py-clob-client` packages only work against V1 and no longer work against production CLOB V2.

> [!NOTE]
>
> **What's next.** We're planning a unified SDK that folds Gamma, Data, and CLOB into a single package. Future releases will converge there — for now, `clob-client-v2` / `py-clob-client-v2` are the V2 CLOB clients.

### Constructor: positional args → options object

The single most visible change. `chainId` is renamed to `chain`. `tickSizeTtlMs` is no longer configurable.

```typescript Before (V1) theme={null}
const client = new ClobClient(
  host,
  chainId,
  signer,
  creds,
  signatureType,
  funderAddress,
  useServerTime,
  builderConfig,
  getSigner,
  retryOnError,
  tickSizeTtlMs,   // ← removed in V2
  throwOnError,
);
```

```typescript After (V2) theme={null}
const client = new ClobClient({
  host,
  chain: chainId,  // ← renamed from chainId
  signer,
  creds,
  signatureType,
  funderAddress,
  useServerTime,
  builderConfig,   // shape changed — see Builder Program below
  getSigner,
  retryOnError,
  throwOnError,
});
```

> [!TIP]
>
> The only mental shift: wrap args in `{}` and rename `chainId` → `chain`. Everything else is the same.

### Order creation

Three fields are no longer user-settable: `feeRateBps`, `nonce`, `taker`. One new optional field: `builderCode`.

```typescript Before (V1) theme={null}
const order: UserOrder = {
  tokenID: "0x123...",
  price: 0.55,
  size: 100,
  side: Side.BUY,
  feeRateBps: 100,        // ← removed
  nonce: 12345,           // ← removed
  taker: "0xabc...",      // ← removed
  expiration: 1714000000,
};
```

```typescript After (V2) theme={null}
const order: UserOrderV2 = {
  tokenID: "0x123...",
  price: 0.55,
  size: 100,
  side: Side.BUY,
  expiration: 1714000000,
  builderCode: "0x...",   // optional — your builder code
};
```

**Market orders** follow the same pattern and add an optional `userUSDCBalance` field so the SDK can calculate fee-adjusted fill amounts:

```typescript theme={null}
const marketOrder: UserMarketOrderV2 = {
  tokenID: "0x123...",
  amount: 500,
  side: Side.BUY,
  orderType: OrderType.FOK,
  userUSDCBalance: 1000,   // optional — enables fee-aware calculations
  builderCode: "0x...",    // optional
};
```

## Fee model

Fees are now **determined by the protocol at match time**, not embedded in your signed order.

* **Platform fees** are dynamic per market: `fee = C × feeRate × p × (1 - p)`
* **Makers are never charged fees** — only takers pay.
* You no longer set `feeRateBps` on orders. The SDK handles fee calculation automatically.

### Querying fee parameters

V2 introduces `getClobMarketInfo()`, which returns all CLOB-level market parameters in one call:

```typescript TypeScript theme={null}
const info = await client.getClobMarketInfo(conditionID);
// info.mts  — minimum tick size
// info.mos  — minimum order size
// info.fd   — fee details { r: rate, e: exponent, to: takerOnly }
// info.t    — tokens [{ t: tokenID, o: outcome }, ...]
// info.rfqe — is RFQ enabled
```

```python Python theme={null}
info = client.get_clob_market_info(condition_id)
# info["mts"]  — minimum tick size
# info["mos"]  — minimum order size
# info["fd"]   — fee details { "r", "e", "to" }
# info["t"]    — tokens list
```

If you were calculating fees manually in your integration, you can now rely on the SDK. Pass `userUSDCBalance` on market buy orders to get accurate fill amounts after fees.

***

## Builder Program

V2 replaces the old builder authentication flow (HMAC headers + separate signing SDK) with a native **builder code** attached directly to each order.

### What's gone

* `@polymarket/builder-signing-sdk` — **no longer needed**
* `POLY_BUILDER_API_KEY`, `POLY_BUILDER_SECRET`, `POLY_BUILDER_PASSPHRASE`, `POLY_BUILDER_SIGNATURE` headers
* Remote vs. local signing distinction

### What's new

* A single `builderCode` (bytes32) from your [Builder Profile](https://polymarket.com/settings?tab=builder)
* Attach it per-order via the `builderCode` field, **or** pass it once at construction so every order inherits it

> [!NOTE]
>
> `BuilderConfig` still exists, but its shape changed. In V1 it wrapped HMAC credentials from `@polymarket/builder-signing-sdk`. In V2 it's just `{ builderCode: string }`.

> [!NOTE]
>
> **Your builder API key isn't retired.** The HMAC-based builder API key is still used to authenticate with the [Relayer](/trading/wallets-auth#execute-gasless-transactions) for gasless transactions. Only the order-signing flow moves to the `builderCode` field — your relayer integration keeps the same credentials.

```typescript Before (V1) theme={null}
import { BuilderConfig, BuilderApiKeyCreds } from "@polymarket/builder-signing-sdk";

const builderConfig = new BuilderConfig({
  localBuilderCreds: new BuilderApiKeyCreds({
    key: process.env.POLY_BUILDER_API_KEY,
    secret: process.env.POLY_BUILDER_SECRET,
    passphrase: process.env.POLY_BUILDER_PASSPHRASE,
  }),
});

const client = new ClobClient(
  host,
  chainId,
  signer,
  creds,
  signatureType,
  funderAddress,
  undefined,
  false,
  builderConfig,
);
```

```typescript After (V2) — per-order builder code theme={null}
const client = new ClobClient({
  host,
  chain: chainId,
  signer,
  creds,
  signatureType,
  funderAddress,
});

await client.createAndPostOrder(
  {
    tokenID: "0x...",
    price: 0.55,
    size: 100,
    side: Side.BUY,
    builderCode: process.env.POLY_BUILDER_CODE,
  },
  { tickSize: "0.01", negRisk: false },
);
```

```typescript After (V2) — pass once at construction theme={null}
const client = new ClobClient({
  host,
  chain: chainId,
  signer,
  creds,
  signatureType,
  funderAddress,
  builderConfig: { builderCode: process.env.POLY_BUILDER_CODE },
});

// Every order posted by this client now carries your builder code.
await client.createAndPostOrder(
  {
    tokenID: "0x...",
    price: 0.55,
    size: 100,
    side: Side.BUY,
  },
  { tickSize: "0.01", negRisk: false },
);
```

***

## Collateral token: USDC.e → pUSD

Polymarket USD (pUSD) replaces USDC.e as the collateral token. pUSD is a standard ERC-20 on Polygon backed by USDC, with backing enforced onchain by the smart contract. The permissionless Collateral Onramp accepts USDC.e.

* **For users on polymarket.com:** the UI handles wrapping automatically.
* **For API-only traders:** wrap USDC.e into pUSD via the Collateral Onramp's `wrap()` function. See the [pUSD page](/concepts/pusd) for full examples and [Contracts](/resources/contracts) for addresses.

***

## Test markets

The markets below were used for pre-cutover testing on `clob-v2.polymarket.com` and are retained for migration reference. For live testing, resolve current active markets into token IDs and metadata with [`gamma-api.polymarket.com/markets?condition_ids=<id>`](https://gamma-api.polymarket.com/markets), then submit small orders to production CLOB V2 at `https://clob.polymarket.com`.

### Markets with fees enabled

Use these to verify fee handling end-to-end.

* `0xaf5e903876ad42de97e1cf02c2ef8484df69bcfc5541b96a400116557d1e504e`
* `0xe9955a31d76ea97457410f61c9b9f2d27ac6fbd8302ed1849d93133884f4fb3b`
* `0x8e6a263fc5f4dd9433b4ccbc9bb9e0d89f4de8a91d3a82d6b437fe73fd847ea5`
* `0xc7d462e462d8d369aee17c9e3ea8f113166cf9a342a6434a0b2a0f7588dc1bbf`
* `0x0440d08e4f534afa8ad9f616a239a19ebf7f2476bd802b1d54180435fa83463f`
* `0xd048b3e9ccad82c57a4eec953e75794aeb5e6d0e08bdb79b9e01b24e0049f16d`
* `0x88310713845c54e36f29791a1c2dc172b9819b645ba82d5f87560805cd2bb788`
* `0xffcab88076a28795281bb07a082c7003a4ff5671420086cb16ec09dfbf9aea68`
* `0x64a5bcfb0c76a75081c8be49c895a976d506fce8d21aa9d73f1099e502f2fa4e`
* `0x8babe4f4d0eff732d660fa02929a581cb8478ed2a1696c158290b2794d3d7ac0`

### Additional markets with liquidity

* `0xcf8a237df51a51511c4f96bb4390480ad72b898ca8ec7e9a3c16c47c8e5e468a`
* `0x242d251e7e804f79e1f237896b0f5e73caea72375dcb84e5a60d1cd0d2f80ef5`
* `0x9c47ba9e666983bd8d82bfab790509153bf7756c43913f6ef269e33c8955939c`
* `0x221aaa62fed17db56fbc7983f88110a9c34861c3262154ee3315425378e3ae12`
* `0x625d0091f4c647e5497bd9b03f8526bd486d6c339380b8046e4dd5b3373046b7`
* `0xc9b9f89ac915385c8d77edb73872c49e5bf76e510b74b9609e74e7f8d0339df2`
* `0xde9f827cb2d568db7801439693645a941a38fe6feaeb08b86087ad367d991704`
* `0xfd029ab3d6d27b6e1f3480dce858c97fb12e5bebd6fb50be7520102c56ba8ce1`
* `0x894a61a2baa777adf1d03a263a4b2d8faa7e1ebc7bf6694a37701fae8add01d9`
* `0xcd57f3ad3bbbdaa96aacabd35f50c2d6e30f777e4a33876a4ab2dcd9f0b8c170`
* `0xc4b07998e8f9bf6b95f079d6dc0529f3c6f59698d4e168817ad5f99304de6c57`
* `0xe4f4b614a6c2b4ecd8eb700d19c0e6533d3fbd1bc28193b2255394ef74006e6f`
* `0xec181db4470b152493b58229862af3f6335b77cc719f5a0e7ed58c9f9848b992`
* `0x6ec4fec4885df7f3ac46e5d0051beb6d8ac75de6a8481f13f245ff26dcb4b662`
* `0x8f6e71601903224dc29c69b886a63f248c8051be259e7db299850708f1f86dd6`
* `0xfa40b5612a905f16ee42a18979f23fa1bbfcfc365f11d168f2e22bd0159ada77`
* `0x182390641d3b1b47cc64274b9da290efd04221c586651ba190880713da6347d9`

***

## Migration checklist

Work through this list as you update your integration:

> **SDK and constructor**
>
> * [ ] Install `@polymarket/clob-client-v2` / `py-clob-client-v2` (remove the legacy `clob-client` / `py-clob-client` packages)
> * [ ] Convert constructor calls from positional args to options object
> * [ ] Rename `chainId` parameter to `chain`
> * [ ] Remove `tickSizeTtlMs` and `geoBlockToken` from constructor config

> **Order creation**
>
> * [ ] Remove `feeRateBps`, `nonce`, `taker` from order creation calls
> * [ ] Add `builderCode` to orders if you're a builder
> * [ ] Pass `userUSDCBalance` on market buy orders for fee-adjusted fill amounts (optional)
> * [ ] Remove any manual fee calculation logic — fees are protocol-handled

> **Builder program**
>
> * [ ] Remove `@polymarket/builder-signing-sdk` from dependencies
> * [ ] Remove `POLY_BUILDER_*` environment variables
> * [ ] Copy your builder code from [your Builder Profile](https://polymarket.com/settings?tab=builder)
> * [ ] Store it as `POLY_BUILDER_CODE` (or any env var you prefer)
> * [ ] Attach `builderCode` on every order to get attribution

> **Raw order struct / manual signing**
>
> * [ ] Update any code that inspects raw order structs (new fields: `timestamp`, `metadata`, `builder`)
> * [ ] Update manual EIP-712 signing code (Exchange domain version `"1"` → `"2"`)
> * [ ] Update onchain contract references to new V2 addresses

> **Collateral**
>
> * [ ] If you're API-only, plan for wrapping USDC.e into pUSD via the Collateral Onramp
> * [ ] Update any hardcoded references to the old USDC.e address

> **Testing**
>
> * [ ] Test the full order lifecycle with small production orders
> * [ ] Verify builder attribution appears on the [Builder Leaderboard](https://builders.polymarket.com)
> * [ ] Re-create any pre-cutover resting orders with V2 signing

***

## Cutover day

**Go-live occurred on April 28, 2026 (\~11:00 UTC).** The migration involved approximately **1 hour of downtime** during which trading was paused.

**During the window:**

* All open orders were wiped. Any pre-cutover resting orders must be re-placed with V2 signing.
* The SDK's **hot-swap mechanism** queried a version endpoint and auto-refreshed when V2 went live.
* Clients already on the latest V2 SDK did not require manual intervention during the cutover.

**If your integration is still on the V1 SDK, it will not work against production CLOB V2.** There is no backward compatibility.

Follow [Discord](https://discord.gg/polymarket), Telegram, and [status.polymarket.com](https://status.polymarket.com) for operational updates and incident notices.

***

## FAQ

> **Do I need to re-generate my API keys?**
>
> No. L1/L2 authentication is identical in V2. Your existing API key, secret, and passphrase continue to work.

> **Will my open orders migrate automatically?**
>
> No — open orders from before the CLOB V2 cutover were wiped. Re-place them with V2 signing.

> **What happens if I forget to update the SDK?**
>
> Your V1 client will fail against the V2 backend. There is no backward compatibility — upgrade before submitting production orders.

> **Do I need to migrate my USDC.e to pUSD manually?**
>
> If you're trading through polymarket.com, no — the UI handles wrapping automatically with a one-time approval. If you're API-only, you'll need to call `wrap()` on the Collateral Onramp contract.

> **Is the builder code a secret?**
>
> No. Builder codes are **public identifiers** — they appear onchain in the `builder` field of every attributed order. Only you control which orders include your code, so keep it scoped to apps you own.

> **I calculate fees manually. What do I change?**
>
> Remove the manual calculation. Use `getClobMarketInfo(conditionID)` to query fee parameters (`fd.r`, `fd.e`, `fd.to`), and rely on the SDK to handle fee-adjusted amounts. Pass `userUSDCBalance` on market buy orders for accurate fill math.

> **Are WebSocket URLs or payloads changing?**
>
> WebSocket URLs are unchanged. Most message payloads are unchanged. The `fee_rate_bps` field on `last_trade_price` events continues to reflect the fee actually charged on the trade.

***

## Getting help

> **[Discord](https://discord.gg/polymarket)**
>
> Real-time help from the Polymarket team and community.

> **[Status](https://status.polymarket.com)**
>
> Live status, incidents, and maintenance windows.

> **[Builder Profile](https://polymarket.com/settings?tab=builder)**
>
> Copy your builder code and manage your builder account.

> **[API Reference](/api-reference/predictions/overview)**
>
> Endpoint-level documentation for every API.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.