> ## 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.
**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`.
**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
Even if a section doesn't look relevant, skim it. V2 touches more surface area than any previous release.
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.
Use a small funded wallet to test market discovery, order signing, posting, cancellation, and settlement behavior end-to-end on production.
**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.
**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": "",
"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
```
The legacy `@polymarket/clob-client` and `py-clob-client` packages only work against V1 and no longer work against production CLOB V2.
**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,
});
```
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
`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 }`.
**Your builder API key isn't retired.** The HMAC-based builder API key is still used to authenticate with the [Relayer](/trading/gasless) 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=`](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:
* [ ] 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
* [ ] 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
* [ ] 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
* [ ] 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
* [ ] 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
* [ ] 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
No. L1/L2 authentication is identical in V2. Your existing API key, secret, and passphrase continue to work.
No — open orders from before the CLOB V2 cutover were wiped. Re-place them with V2 signing.
Your V1 client will fail against the V2 backend. There is no backward compatibility — upgrade before submitting production orders.
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.
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.
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.
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
Real-time help from the Polymarket team and community.
Live status, incidents, and maintenance windows.
Copy your builder code and manage your builder account.
Endpoint-level documentation for every API.