Polymarket V2 Migration

Documentation Index

Fetch the complete documentation index at: https://docs.polynode.dev/llms.txt

Use this file to discover all available pages before exploring further.

​

Before Cutover: Your Checklist

1. Upgrade your SDK to the V2-ready version. Older versions won’t generate the correct V2 payload.
   • Rust: polynode >= 0.12.0. Install with cargo add polynode@0.12.0.
   • TypeScript: polynode-sdk >= 0.9.0. Install with npm install polynode-sdk@^0.9.0.
   • Python: polynode >= 0.9.0. Install with pip install "polynode>=0.9.0".
2. Flip the exchange version flag in your TraderConfig. See The Switch below. This is the only code change required.
3. Mint a V2 builder code at polymarket.com/settings?tab=builder if you want attribution on your orders. Optional, orders still work without one.
4. Cancel V1 resting orders you don’t want cleared at cutover. Open V1 orders get wiped when Polymarket flips the switch.
5. Fund PolyUSD. V2 orders settle in PolyUSD (pUSD), not USDC.e. If your Safe holds USDC.e, call trader.wrap_to_polyusd(amount) (Python) / trader.wrapToPolyUsd(amount) (TS) / trader.wrap_to_polyusd(amount) (Rust) to convert it via the Collateral Onramp. amount is in raw 6-decimal units (1_000_000 = $1; TS takes a bigint — use 1_000_000n). Existing V1 pUSD balance carries over.
6. Test against V2 now. Point your SDK at V2 (step 2) and place a small order against clob-v2.polymarket.com. ensure_ready / ensureReady sets the V2 approvals and refreshes the CLOB’s cached balance/allowance view for you.
7. Verify V2 confirmation. Your settlement stream tags V2 trades with "exchange_version": "v2" on every event.

​

The Switch

let config = TraderConfig {
    exchange_version: ExchangeVersion::V2,  // ← this line
    ..Default::default()
};

• New contract addresses (V2 CTF Exchange + NegRisk A/B)
• New EIP-712 domain (version "2", new verifyingContract)
• New Order struct (adds builder, metadata, timestamp; drops nonce, feeRateBps from the signed hash)
• CLOB host swap to clob-v2.polymarket.com
• PolyUSD collateral wrapping via the Onramp contract

​

What We’ve Verified

• V2 settlement decoding verified against real on-chain transactions
• V2 trade events (OrderFilled, OrdersMatched) decoded from block receipts
• PolyUSD wrapping and unwrapping tested and detected in real time
• V2 order placement tested live on the V2 CLOB
• Full order lifecycle verified: place, check status, cancel, re-place
• All existing market data, token IDs, and enrichment confirmed identical between V1 and V2
• Order hash verification: our EIP-712 order hash computation produces byte-for-byte identical results to the live V2 exchange contract’s hashOrder() function on Polygon mainnet — cryptographic proof that our implementation is correct

​

V2 Contract Addresses

​

How V2 Fits Together

​

Why Token IDs Don’t Change

V1 (current):
  USDC.e → V1 Exchange → ConditionalTokens (mints/burns tokens directly)

V2 (new):
  PolyUSD → V2 Exchange → CollateralAdapter → ConditionalTokens
                                 |
                           Unwraps PolyUSD → USDC.e
                           Deposits USDC.e into ConditionalTokens
                           Same tokens minted as V1

• Same token IDs across V1 and V2
• Same condition IDs
• Same market metadata (Gamma API, enrichment)
• Positions opened on V1 are fully compatible with V2 and vice versa

​

New V2 Contracts

​

What’s New in V2

​

What Didn’t Change

• ConditionalTokens contract — same address, same position system, same token IDs
• Market data — same condition IDs, same Gamma metadata, same enrichment pipeline
• Authentication — same API key derivation, same HMAC headers
• WebSocket subscriptions — same event types, same format
• Position splits/merges/conversions — same ConditionalTokens events
• Oracle system — unchanged UMA adapters and resolution flow
• Orderbook streaming — same WebSocket protocol and message format

​

Impact on polynode Users

​

Settlement Stream

• settlement — early detection (3-5 seconds pre-confirmation)
• status_update — block confirmation with latency measurement
• trade — confirmed trade from OrderFilled event
• deposit — now includes PolyUSD wrapping/unwrapping alongside USDC.e

​

Trading SDK

use polynode::trading::{PolyNodeTrader, TraderConfig, OrderParams, OrderSide, ExchangeVersion};

let mut config = TraderConfig {
    polynode_key: "pn_live_...".into(),
    exchange_version: ExchangeVersion::V2,  // ← only change needed
    ..Default::default()
};

let mut trader = PolyNodeTrader::new(config)?;
let signer = PrivateKeySigner::from_hex("0x...")?;
let status = trader.ensure_ready(Box::new(signer), None).await?;

// Order placement is identical to V1
let result = trader.order(OrderParams {
    token_id: "10293...".into(),
    side: OrderSide::Buy,
    price: 0.05,
    size: 10.0,
    ..Default::default()
}).await?;

​

Builder Attribution in V2

let result = trader.order(OrderParams {
    token_id: "10293...".into(),
    side: OrderSide::Buy,
    price: 0.05,
    size: 10.0,
    builder: Some("0x0000000000000000000000000000000000000000000000000000000000000001".into()),
    ..Default::default()
}).await?;

​

Pre-Migration V1 Orders

​

Common V2 Errors

1. Your wallet has USDC.e but not PolyUSD. V2 uses PolyUSD as the collateral token. Call trader.wrap_to_polyusd(amount_raw) (Python/Rust) or trader.wrapToPolyUsd(amount_raw) (TS) to convert. Amounts are raw 6-decimal integers.
2. Approvals not yet visible to the CLOB. The V2 CLOB caches per-API-key balance + allowance state. ensureReady / ensure_ready refreshes this cache after setting approvals; if you changed approvals outside that flow, call trader.refreshBalanceAllowance() / trader.refresh_balance_allowance() manually.
3. Order notional + fee exceeds balance. V2 markets charge a fee (~2–5% of notional depending on base_fee). For a BUY, balance >= makerAmount + platformFee must hold or the CLOB rejects.

use polynode::trading::{LinkOpts, SignatureType};

trader.link_wallet(Box::new(signer), Some(LinkOpts {
    signature_type: Some(SignatureType::Eoa),
})).await?;

​

Timeline

• Now: V2 test environment live at clob-v2.polymarket.com. V2 contracts live on Polygon mainnet processing real trades. polynode settlement stream tags V2 trades with exchange_version: "v2".
• Before April 28: Flip your SDK config to exchange_version: V2 (or keep V1 until cutover). Mint a builder code if you want attribution. Cancel V1 resting orders you don’t want cleared.
• April 28, ~11am UTC: Polymarket cutover. V2 becomes the primary exchange. V1 orderbooks cleared.
• After cutover: Any integration still on V1 will fail with order_version_mismatch. Flip your config.