Skip to main content

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.

​
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, 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.
  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 (>= 0.10.3) with the signing extra: 
pip install 'aion-sdk[signing]>=0.10.3'

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
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
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.