Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs-t.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 signed payload also changes. Compared with V1:
  • some legacy signed fields are removed from the hash flow
  • V2 introduces fields such as timestamp, metadata, and builder
  • the EIP-712 domain changes for V2 signing
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)
  • a non-zero signing timestamp (V2-only field)
  • the V2-compatible EIP-712 domain
  • metadata and builder fields when required by your signing library
  • pUSD collateral instead of USDC.e
py-clob-client (≤ 0.34.6) only emits V1 order fields and does NOT sign V2 payloads, so V2 markets reject its output with order_version_mismatch. To sign V2 orders in Python, use aion-sdk (>= 0.7.3) with the signing extra: 
pip install 'aion-sdk[signing]>=0.7.3'

from aion_sdk import build_v2_signed_order
from aion_sdk.signing import V2_CTF_EXCHANGE, V2_NEG_RISK_EXCHANGE_A

signed = build_v2_signed_order(
    private_key=PRIVATE_KEY,
    maker=WALLET_ADDRESS,
    token_id="<clob_token_id>",
    maker_amount="5500000",      # 6-decimal atomic units
    taker_amount="10000000",
    side="BUY",
    verifying_contract=V2_CTF_EXCHANGE,   # use V2_NEG_RISK_EXCHANGE_A / _B for neg-risk markets
    signature_type=0,            # 0=EOA, 1=Proxy, 2=Safe, 3=Deposit Wallet
)
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.7.3 and install the signing extra (pip install 'aion-sdk[signing]') to use the built-in build_v2_signed_order(...) helper. If you maintain custom signing code, validate it against real V2 orders before production rollout. py-clob-client (≤ 0.34.6) does not produce V2 orders — do not rely on it for V2 signing.

​
Troubleshooting

​
order_version_mismatch

Your integration is posting a V1-formatted order to a V2 market. The most common cause is signing with py-clob-client (≤ 0.34.6), which only emits V1 fields. Fix:
  • Switch the signing path to aion_sdk.build_v2_signed_order(...) (see For SDK and Agent Integrators above). Install with pip install 'aion-sdk[signing]>=0.7.3'.
  • Ensure the signed payload contains timestamp (non-zero unix seconds), metadata (bytes32), and builder (bytes32).
  • Verify the EIP-712 domain uses name="Polymarket CTF Exchange", version="2", chainId=137, and the correct V2 verifyingContract (CTF Exchange or Neg-Risk Exchange A/B).
  • Switching wallet types (e.g. EOA → Deposit Wallet) does not fix this — the issue is the order format, 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 order struct compatibility (timestamp, metadata, builder fields)
  • V2 EIP-712 domain configuration
  • 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.