Etherdrake
454358fdc1
- v2-migration.md: add builder API key clarification note - relayer/submit-a-transaction.md: document POST /submit now returns immediately without transactionHash - relayer/get-a-transaction-by-id.md: add note to poll for onchain transactionHash after submission
24 KiB
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 is shipping 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.
**Go-live: April 28, 2026 (\~11:00 UTC)** — approximately 1 hour of downtime. All open orders will be wiped during the cutover. Make sure your integration is on the V2 SDK before the maintenance window starts. **Test against V2 before go-live.** Point your client at `https://clob-v2.polymarket.com` to start integrating now. On April 28th (\~11:00 UTC), V2 takes over the production URL — `https://clob.polymarket.com` — so you don't need to change the base URL again after the cutover.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 |
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 |
| Raw API order signing | V1 Order type | Updated Order type — see API users section |
If you're on the latest SDK, most of this is handled automatically. The hot-swap mechanism detects the cutover and refreshes the client without manual intervention.
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 stop functioning after cutover. The order book is wiped during the maintenance window. Test your integration before the cutover. **Order book wipe:** All open orders are cancelled as part of the cutover. Plan to re-place orders immediately after the window closes.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, andtakerremoved;timestamp,metadata,builderadded. - 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 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.
{
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:
{
verifyingContract: "0xC5d563A36AE78145C45a50134d48A1215220f80a", // [!code --]
verifyingContract: "0xe2222d279d744050d28e00520010520000310F59", // [!code ++]
}
See 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.
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
{
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. Replacesnoncefor 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
{
"order": {
"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": "BUY",
"signatureType": 1,
"timestamp": "1713398400000", // [!code ++]
"metadata": "0x0000000000000000000000000000000000000000000000000000000000000000", // [!code ++]
"builder": "0x0000000000000000000000000000000000000000000000000000000000000000", // [!code ++]
"signature": "0x..."
},
"owner": "<api-key>",
"orderType": "GTC"
}
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.
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.
pip install py-clob-client-v2==1.0.0
Constructor: positional args → options object
The single most visible change. chainId is renamed to chain. tickSizeTtlMs is no longer configurable.
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,
});
Order creation
Three fields are no longer user-settable: feeRateBps, nonce, taker. One new optional field: builderCode.
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:
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
feeRateBpson orders. The SDK handles fee calculation automatically.
Querying fee parameters
V2 introduces getClobMarketInfo(), which returns all CLOB-level market parameters in one call:
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 neededPOLY_BUILDER_API_KEY,POLY_BUILDER_SECRET,POLY_BUILDER_PASSPHRASE,POLY_BUILDER_SIGNATUREheaders- Remote vs. local signing distinction
What's new
- A single
builderCode(bytes32) from your Builder Profile - Attach it per-order via the
builderCodefield, or pass it once at construction so every order inherits it
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 },
);
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 for full examples and Contracts for addresses.
Test markets
The following events have liquidity on clob-v2.polymarket.com — use them to dry-run your integration end-to-end before go-live.
US / Iran nuclear deal in 2027?
- Event:
gamma-api.polymarket.com/events/73106 - Orderbook:
token_id=102936…7216
Highest grossing movie in 2026?
- Event:
gamma-api.polymarket.com/events/79831 - Orderbooks:
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 full order lifecycle on preprod * [ ] Verify builder attribution appears on the [Builder Leaderboard](https://builders.polymarket.com) * [ ] Plan for order book wipe — all open orders must be re-placed after migrationCutover day
Go-live: April 28, 2026 (~11:00 UTC). The migration involves approximately 1 hour of downtime during which trading is paused.
During the window:
- All open orders are wiped. You must re-place orders after the migration completes.
- The SDK's hot-swap mechanism queries a version endpoint and auto-refreshes when V2 goes live.
- If you're on the latest V2 SDK, no manual intervention is needed during the cutover.
If your integration is on the V1 SDK after migration, it will stop working. There is no backward compatibility.
Follow Discord, Telegram, and status.polymarket.com for the exact maintenance window start time. The window is scheduled to avoid large market resolutions.