Skip to main content
Add V2 trading to an API integration already using pUSD and the CTFExchangeV2 order format. Keep your CTF trading path and CLOB authentication.

​
Migrate Trading

1

Select the Trading ID

Given a Gamma market, use its version to choose the desired outcome’s trading ID. For example, retrieve a market with:
Fetch a Market
Choose the ID field by version, even when both fields are present:Decode outcomes from JSON text. Select the ID at the intended outcome’s index, decoding clobTokenIds first for V1.Reject missing or unsupported versions, unmatched outcomes, and missing or non-decimal IDs. Keep the selected ID as a decimal string, referred to as <ASSET_ID> below.
2

Approve V2 Trading

V2 orders settle through ExchangeV3. Use the Polygon addresses for ExchangeV3, pUSD, and PositionManager from Contract Addresses. Grant these approvals from the maker (the EOA or smart wallet holding the funds) and wait for confirmation:Existing CTF permissions do not grant these approvals.
3

Refresh Balances and Allowances

After confirmation, refresh the CLOB cache with your existing CLOB L2 authentication and the maker’s signature type:
Read /balance-allowance with the same parameters and a fresh L2 signature for that path. Check its allowances entry for ExchangeV3. CONDITIONAL-V2 selects V2 positions; COLLATERAL selects pUSD. Keep CONDITIONAL for CTF positions.
4

Sign and Submit the V2 Order

Replace the order’s EIP-712 domain with this Polygon configuration:
V2 Order Domain
Keep the CTFExchangeV2 signed order structure, set order.tokenId to the V2 position ID, and re-sign. Submit through your existing order flow. CTF orders retain their exchange and domain version "2".

​
Verify the Migration

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

​
Track Resolution Through Gamma

If you monitor resolution through Gamma, read the V2 market response:
V2 Market Resolution
For V2, resolutionStatus is inactive, active, or resolved. For V1, keep using umaResolutionStatus.

​
Check Identifiers and Subscriptions

Fetch the order book using the asset ID selected earlier:
Fetch the Order Book
Use the same asset ID for prices, orders, and market subscriptions (assets_ids). User-stream markets and market-wide cancellation use the market’s condition ID.

​
Update Custom Fill Calculations

If you calculate fills yourself, use integer base units and the maker’s signed amounts for each maker fill:
Counter-Asset Amount
makerAssetFill is collateral for a BUY and shares for a SELL. ExchangeV3 reduces a BUY’s remaining collateral budget by the amount actually spent. CLOB GTC/GTD BUY targets are shares; FOK/FAK BUY targets are collateral. Reconcile fills and fees separately: BUY fees add to collateral spend; SELL fees are deducted from proceeds.