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

# Polymarket V2 Migration

> What the Polymarket V2 rollout means for AionMarket users, agent builders, and wallet integrations.

## Overview

Polymarket V2 changes how collateral and order signing work on Polygon. For AionMarket users, the key shift is that new Polymarket trading flows settle in `pUSD` instead of trading directly against `USDC.e`, and V2 orders use the updated signing shape required by Polymarket.

If you use AionMarket at [www.aionmarket.com](https://www.aionmarket.com/), this guide explains:

* what changed in Polymarket V2
* who needs to take action
* how wallet migration affects trading
* what integrators need to update in their own order flow

## TL;DR

* Polymarket V2 replaces the old V1 order path.
* V2 uses `pUSD` as the collateral token for trading.
* Existing `USDC.e` is still your asset, but it must be wrapped or migrated into `pUSD` before V2 trading can proceed.
* Kalshi workflows are not affected by this migration.
* If you use custom trading code, you must send V2-shaped orders and use the correct signing domain.
* If you use the AionMarket SDK, upgrade to the latest version that supports V2-compatible order payloads.

## What Changed

### Collateral Token

Under V2, Polymarket trading uses `pUSD` as the active collateral asset. `pUSD` is designed to stay 1:1 with `USDC.e`, but the exchange expects the V2 collateral path.

Practical impact:

* `USDC.e` may still sit in your wallet safely
* new V2 trades require usable `pUSD`
* redeemed or newly routed collateral may now appear as `pUSD`

### Order Format

V2 orders are not just a token swap. The verifying contract and signing path also change.

Compared with V1:

* some legacy signed fields are removed from the hash flow
* V2 uses a new `verifyingContract` (CTF Exchange V2 + Neg-Risk variants); the EIP-712 Order struct itself stays the same 12 fields as V1
* the EIP-712 domain `version` stays `"1"` even on V2 (the contract’s ERC-5267 `eip712Domain()` getter reports `"2"` but `_hashTypedDataV4` is built with `"1"`)

If your integration still sends V1-shaped payloads, Polymarket may reject them with errors such as:

* `order_version_mismatch`
* fee-rate parsing errors caused by old payload shape
* signature validation failures caused by the wrong domain version

## Who Needs to Act

### Users Trading Polymarket Through AionMarket

If you only trade Kalshi, no migration work is required.

If you trade Polymarket through AionMarket, you should verify:

* your Polymarket wallet has migrated or wrapped collateral into `pUSD`
* your wallet has the required V2 allowances
* your SDK or automation path is generating V2-compatible orders

### Users With External Wallets

If you use MetaMask, Rabby, Coinbase Wallet, or another self-custody wallet:

* you will sign the approval and wrap steps from your browser wallet
* you need a small amount of `POL` on Polygon for gas
* after migration completes, you can trade with the V2-compatible balance state

### Agent Builders and API Integrators

If you build orders directly instead of using a hosted wrapper flow, you must update your integration for:

* V2 order struct fields
* the updated EIP-712 domain
* `pUSD` collateral assumptions
* post-allowance cache refresh where required by the CLOB client stack

## What AionMarket Users Should Do

### If You Already Hold Polymarket Collateral

Before placing your next Polymarket trade, make sure your wallet is ready for V2:

1. Open the AionMarket wallet or trading experience at [www.aionmarket.com](https://www.aionmarket.com/).
2. Check whether your wallet still holds `USDC.e` for Polymarket.
3. Complete the migration or wrap flow into `pUSD` if prompted.
4. Confirm any required allowance transactions.
5. Retry the trade once the wallet state is fully updated.

### If You Have No Existing Polymarket Balance

In most cases, there is no immediate migration step. You only need to ensure that:

* future collateral lands in the correct V2-compatible flow
* wallet approvals are configured before trading

### If You Still Have Open V1 Orders

Before relying on V2 trading, clear or review old open orders. A legacy V1 order book cannot be assumed to remain valid after the V2 cutover.

## AionMarket Wallet Guidance

AionMarket should treat the migration as a Polymarket-specific change, not a platform-wide venue change.

What remains unchanged:

* Kalshi-related trading flows
* most agent lifecycle APIs
* user identity and API key ownership

What changes for Polymarket:

* collateral display should use `pUSD` where appropriate
* wallet readiness checks should account for V2 allowance state
* trading integrations should recognize the V2 signing path

## For SDK and Agent Integrators

### Required Order Updates

If you construct Polymarket orders directly, ensure your payload includes the V2-compatible fields expected by Polymarket.

> **V2 is a contract / order-format upgrade, not a wallet-type requirement.** All four `signatureType` values (`0`=EOA, `1`=POLY\_PROXY, `2`=GNOSIS\_SAFE, `3`=POLY\_1271 / Deposit Wallet) are valid in V2. Do **not** assume that V2 requires `signatureType=3`.

Typical V2 expectations include:

* the `signatureType` that matches your actual wallet (commonly `0` for EOA, `3` only for Polymarket Deposit Wallets)
* the **V2 `verifyingContract`** (CTF Exchange V2 `0xE111180000d2663C0091e4f400237545B87B996B`, or Neg-Risk Exchange A/B for neg-risk markets)
* the V2-compatible EIP-712 domain (`name="Polymarket CTF Exchange"`, `version="1"`, `chainId=137`)
* `pUSD` collateral instead of `USDC.e`

Note: V1 and V2 share the **same 12 EIP-712 fields** (`salt, maker, signer, taker, tokenId, makerAmount, takerAmount, expiration, nonce, feeRateBps, side, signatureType`). Earlier versions of this guide and `aion-sdk ≤ 0.10.1` incorrectly required extra `timestamp` / `metadata` / `builder` fields in the typed data; **upgrade to `aion-sdk >= 0.10.3`** if you see `Invalid order payload` errors. `0.10.3` additionally hard-fails when `signer`/`maker`/private-key are inconsistent (the most common cause of CLOB rejections for `signatureType=1/2/3`).

`py-clob-client` (≤ 0.34.6) signs against the V1 verifying contract, so V2 markets reject its output. To sign V2 orders in Python, use [`aion-sdk`](https://pypi.org/project/aion-sdk/) (>= 0.10.3) with the `signing` extra:

```bash theme={null}
pip install 'aion-sdk[signing]>=0.10.3'
```

```python theme={null}
from aion_sdk import build_v2_signed_order

# EOA wallet (signature_type=0): maker == signer == EOA address
signed = build_v2_signed_order(
    private_key=PRIVATE_KEY,
    maker=EOA_ADDRESS,
    signer=EOA_ADDRESS,          # MUST equal Account.from_key(private_key).address
    token_id="<clob_token_id>",
    maker_amount="5500000",      # 6-decimal atomic units
    taker_amount="10000000",
    side="BUY",
    neg_risk=False,              # set True for neg-risk markets (auto-picks exchange)
    signature_type=0,            # 0=EOA, 1=Proxy, 2=Safe, 3=Deposit Wallet
)

# Deposit Wallet (signature_type=3): maker = wallet contract, signer = EOA
signed = build_v2_signed_order(
    private_key=PRIVATE_KEY,     # EOA's private key
    maker=DEPOSIT_WALLET,        # wallet contract address on Polygon
    signer=EOA_ADDRESS,          # EOA controlling the deposit wallet
    token_id="<clob_token_id>",
    maker_amount="5500000",
    taker_amount="10000000",
    side="BUY",
    neg_risk=sub_market["negRisk"],
    signature_type=3,
)
```

> **`signer` vs `maker` (Deposit Wallet trap):** for `signatureType` 1/2/3 the `maker` is the **wallet contract**, but `signer` MUST be the **EOA** that owns it — i.e. the address derived from `private_key`. The CLOB recovers the ECDSA signer and compares it against the `signer` field; if they differ you get `INVALID_ORDER` / `Invalid order payload`. SDK >= 0.10.3 raises a `ValueError` up-front instead of producing such an order.
>
> Always set `neg_risk=sub_market["negRisk"]`. Picking the wrong exchange contract also produces `Invalid order payload`.

The returned dict is the exact `order` payload accepted by `POST /markets/trade`. EOA wallets are fully supported by V2 — do **not** switch wallet types just to bypass a signing-format error.

### Example Migration Mindset

When reviewing your existing implementation, look for these old assumptions:

* hard-coded V1 fee fields in the signed struct
* V1-only domain version assumptions
* `USDC.e` treated as the only active trading collateral
* allowance refresh skipped after on-chain approvals

### SDK Recommendation

If your system depends on the AionMarket SDK, upgrade to `aion-sdk >= 0.10.3` and install the `signing` extra (`pip install 'aion-sdk[signing]'`) to use the built-in `build_v2_signed_order(...)` helper. Versions `<= 0.10.1` had a V2 signing bug (wrong EIP-712 domain version + 3 extra struct fields) and produced `Invalid order payload` for every V2 order. `0.10.2` fixed the typed-data shape; `0.10.3` adds a `neg_risk` parameter, requires explicit `signer` for non-EOA wallets, and hard-fails on signer/private-key mismatches — closing the most common Deposit Wallet (`signatureType=3`) failure mode.

## Troubleshooting

### `order_version_mismatch` or `Invalid order payload`

Your integration is posting an incorrectly-signed order to a V2 market. The most common causes are:

1. signing with `py-clob-client` (≤ 0.34.6) against the V1 verifying contract
2. running `aion-sdk ≤ 0.10.1`, which incorrectly added `timestamp` / `metadata` / `builder` to the EIP-712 typed data and used domain `version="2"` instead of `"1"`
3. (Deposit Wallet, `signatureType=3`) passing `signer=DEPOSIT_WALLET` instead of `signer=EOA`. The signature is produced by the EOA's `private_key`, so the recovered signer is the EOA — if the order's `signer` field is the deposit-wallet contract, CLOB returns `Invalid order payload`.
4. neg-risk markets signed against the vanilla CTF Exchange (or vice versa). The `verifyingContract` is part of the EIP-712 domain, so a wrong choice yields a valid-but-rejected signature.

Fix:

* Upgrade to `pip install -U 'aion-sdk[signing]>=0.10.3'` and re-sign with `aion_sdk.build_v2_signed_order(...)`. Pass `neg_risk=sub_market["negRisk"]` (no need to set `verifying_contract` manually) and — for `signatureType=1/2/3` — pass an explicit `signer=EOA_ADDRESS`.
* Verify the EIP-712 domain uses `name="Polymarket CTF Exchange"`, `version="1"`, `chainId=137`, and the correct V2 `verifyingContract` (vanilla CTF `0xE111180000d2663C0091e4f400237545B87B996B`, or Neg-Risk Exchange A/B).
* Confirm the typed data contains exactly **12 Order fields** (no `timestamp`/`metadata`/`builder`).
* Switching wallet types (e.g. EOA → Deposit Wallet) does **not** fix this — the issue is the signing payload, not the wallet kind.

### `bad signature`

This usually points to a mismatch between the signed payload and the V2 EIP-712 domain.

Fix:

* re-check the domain version and verifying contract
* ensure the order was signed as V2, not V1

### `Insufficient balance`

This can happen when your wallet still holds `USDC.e` but has not finished the V2 collateral migration or cache refresh step.

Fix:

* complete the wrap or migration flow into `pUSD`
* verify balances again
* refresh the wallet session if needed

### Allowance-related errors after approval

On-chain approvals may succeed before the trading stack refreshes its cached allowance state.

Fix:

* refresh allowance/balance state through your supported SDK flow
* retry after the cache refresh completes

### No gas for wallet actions

Self-custody wallets on Polygon still need a small amount of `POL` for approval and wrap transactions.

Fix:

* fund the wallet with a small Polygon gas balance
* reconnect and retry

## FAQ

### Is my `USDC.e` still safe?

Yes. The migration is about trading compatibility and collateral routing, not asset loss. The main issue is that V2 trading expects the active collateral path to be in `pUSD`.

### Do I lose value during migration?

The expected model is a 1:1 collateral conversion path between `USDC.e` and `pUSD`. Always confirm the current AionMarket and Polymarket UI before submitting transactions.

### Does this affect Kalshi?

No. This guide only applies to Polymarket-related wallet and order flows.

### Do I need to change my agent API keys?

Usually no. API key ownership remains the same. The changes are primarily in wallet collateral state and Polymarket order construction.

### What if I do nothing?

Your wallet assets are not automatically lost, but you may be unable to place new Polymarket V2 trades until your collateral and wallet state are migrated to the V2-compatible path.

## For Builders

If you maintain a custom Polymarket execution path on top of AionMarket, validate all of the following before release:

* V2 contract addresses and collateral addresses
* V2 EIP-712 domain configuration (`name="Polymarket CTF Exchange"`, `version="1"`, `chainId=137`, V2 `verifyingContract`)
* 12-field Order struct (V1 = V2 here; do **not** add `timestamp`/`metadata`/`builder` to the typed data)
* correct `signatureType` for the actual wallet being signed with (any of `0`/`1`/`2`/`3`, **not hard-coded to `3`**)
* post-approval balance/allowance refresh behavior
* pUSD balance display and settlement expectations

## Recommended Reading

* [AionMarket](https://www.aionmarket.com/)
* [Wallet Setup](/essentials/wallet-setup)
* [Trading Guide](/essentials/trading-guide)
* [Python SDK](/essentials/python-sdk)
* [Polymarket official V2 migration docs](https://docs.polymarket.com/trading/deposit-wallets)

If you expose a public migration banner, wallet prompt, or agent automation workflow on AionMarket, keep this guide aligned with the latest Polymarket production documentation.