Escrow Lifecycle

Deposit, trade, withdraw — how USDC moves through PMXT’s non-custodial PreFundedEscrow.

Hosted trading on PMXT settles through a non-custodial PreFundedEscrow smart contract on Polygon (chainId 137). USDC sits in the escrow under your wallet’s beneficial ownership; PMXT cannot move funds without an EIP-712 signature from your wallet. This page walks through the full lifecycle: approve, deposit, trade, withdraw.

You fund Polygon only. USDC always sits in the Polygon PreFundedEscrow for the currently hosted trading venues (Polymarket, Opinion, and Limitless). For hosted venues that don’t settle on Polygon (Opinion on BSC, Limitless on Base), PMXT operates an internal cross-chain leg that holds outcome tokens on the venue’s chain; you neither fund nor sign anything on that side. Pass any EVM-compatible private key; the same EVM wallet/key can trade the currently hosted venues.

Why escrow at all?

Polymarket’s CLOB exchange expects the submitter to be the operator of the user’s CLOB proxy wallet. That proxy is created by Polymarket’s USDC.e adapter and is non-trivial to operate from a third-party context. PMXT’s PreFundedEscrow solves this by acting as a pre-funded operator: the user deposits USDC once, PMXT routes orders against that balance, and the user can withdraw at any time. The user signs every order with EIP-712 against the Polygon escrow’s domain; the escrow contract can only spend USDC against signed orders, never unilaterally.

For Opinion, the same Polygon escrow balance funds a cross-chain settlement leg into a BSC-side VenueEscrow that holds Opinion outcome tokens — you still only deposit on Polygon, and your EIP-712 signature still targets the Polygon escrow domain. The BSC hop is PMXT’s plumbing.

The client.escrow namespace

Hosted exchange clients (Polymarket, Opinion, Limitless) expose an escrow namespace. Every method builds an unsigned transaction. Your wallet — MetaMask, ethers Wallet, viem, web3.py, etc. — is responsible for signing and broadcasting it. PMXT never holds your private key.

Method (Python / TypeScript)	Description
escrow.approve_tx(token, amount_wei=None) / escrow.approveTx(token, amountWei?)	Build an unsigned ERC-20 approval for USDC or CTF.
escrow.deposit_tx(amount) / escrow.depositTx(amount)	Build an unsigned USDC deposit into PreFundedEscrow.
escrow.withdraw_tx(action, amount=None) / escrow.withdrawTx(action, amount?)	Build an unsigned request / claim / cancel withdrawal.
escrow.withdrawals(include="pending,events") / escrow.withdrawals({ include })	Read pending withdrawal state and historical events.

See the source: sdks/python/pmxt/escrow.py and sdks/typescript/pmxt/escrow.ts.

1. Approve and deposit

Before the first deposit, the escrow contract needs permission to pull USDC from your wallet (a standard ERC-20 approval). Then you deposit. For most users, the dashboard handles both in a single connected-wallet flow.

Recommended: use the dashboard

Open pmxt.dev/dashboard, connect the wallet whose address you passed to the SDK, and use the Deposit flow. Your wallet (MetaMask, Rabby, WalletConnect, etc.) prompts you to sign — PMXT never sees your private key.

1. Go to pmxt.dev/dashboard and connect the matching wallet.
2. Click Deposit and enter the USDC amount.
3. Approve the USDC allowance in your wallet (one-time per token).
4. Confirm the deposit transaction in your wallet.

Approval is one-time per token + spender; the deposit itself is one-time setup before your first trade. If you ever rotate the escrow contract (rare, gated on a PMXT migration announcement), you’ll need to re-approve.

Advanced: programmatic approve + deposit

If you’re scripting deposits (CI, treasury automation, custom wallet integrations), client.escrow builds unsigned transactions you sign and broadcast with your own wallet library.

Approve

Python

# Unlimited approval for USDC (most common)
result = client.escrow.approve_tx("usdc")
# result is a dict wrapping the unsigned tx, e.g.:
#   { "tx": { "to": "0x...", "data": "0x...", "value": "0",
#             "chainId": 137, "gas": "...", "maxFeePerGas": "...",
#             "maxPriorityFeePerGas": "...", "nonce": "..." } }
tx = result["tx"]
# Sign and broadcast `tx` with your preferred wallet library.

# Or scope the approval to a specific wei amount
result = client.escrow.approve_tx("usdc", amount_wei=1_000_000_000)  # 1,000 USDC
tx = result["tx"]

# Approve the Polymarket CTF token (only needed for direct CTF transfers)
result = client.escrow.approve_tx("ctf")
tx = result["tx"]

// Unlimited approval for USDC (most common)
const { tx } = await client.escrow.approveTx("usdc");
// The returned object wraps the unsigned tx, e.g.:
//   { tx: { to: "0x...", data: "0x...", value: "0", chainId: 137,
//           gas: "...", maxFeePerGas: "...",
//           maxPriorityFeePerGas: "...", nonce: "..." } }

// Or scope the approval to a specific wei amount (bigint)
const { tx: txScoped } = await client.escrow.approveTx("usdc", 1_000_000_000n);

// Approve the CTF token
const { tx: ctfTx } = await client.escrow.approveTx("ctf");

Deposit

Amounts are in whole USDC (6 decimals); the SDK validates precision and rejects values like 0.0000001.

Python

# Deposit 10 USDC
result = client.escrow.deposit_tx(amount=10.0)
tx = result["tx"]
# Sign and send `tx` with your wallet library.

# Decimals up to 6 places are supported
tx = client.escrow.deposit_tx(amount=10.5)["tx"]
tx = client.escrow.deposit_tx(amount=10.123456)["tx"]

// Deposit 10 USDC — number, decimal string, or wei BigInt all accepted
const { tx } = await client.escrow.depositTx(10);
const { tx: tx2 } = await client.escrow.depositTx("10.5");
const { tx: tx3 } = await client.escrow.depositTx(10_500_000n); // wei micro-USDC

USDC precision is 6 decimals. The SDK rejects 0.0000001 with ValidationError. Pre-round before passing the value in.

2. Confirm the deposit

After the deposit transaction confirms on-chain, the balance shows up in escrow. fetch_balance is the canonical check.

Python

balances = client.fetch_balance()
usdc = balances[0]
print(f"Available: {usdc.available}, Locked: {usdc.locked}, Total: {usdc.total}")

const balances = await client.fetchBalance();
const usdc = balances[0];
console.log(`Available: ${usdc.available}, Locked: ${usdc.locked}, Total: ${usdc.total}`);

On-chain confirmation usually takes 2–5 seconds on Polygon. If fetch_balance still reads zero 30 seconds after broadcast, check the tx on Polygonscan — a failed deposit (e.g. due to missing approval) will not update escrow state.

3. Trade

With escrow funded, you can trade. create_order and submit_order debit the escrow balance; cancel_order releases the reservation. No additional escrow calls are needed during normal trading — the balance just gets spent.

order = client.create_order(
    market_id="2eeb03dc-404b-41d5-bc57-6aeb37927ae6",
    outcome_id="a114f052-1fd1-4bcd-b9cf-de019db81b67",
    side="buy",
    order_type="market",
    amount=5.0,
    denom="usdc",
    slippage_pct=30.0,
)

4. Withdraw

Withdrawals are a two-step timelock. You first request a withdrawal; after a contract-enforced delay (~1 hour in production), you claim it. You can also cancel a pending request.

The timelock is a security feature — it gives you a window to detect and abort an unauthorized withdrawal even if the operator key were compromised. Because the escrow is non-custodial, every withdrawal step requires a signature from your wallet.

Recommended: withdraw from the dashboard

The dashboard handles the full request → wait → claim journey as one user flow.

1. Open pmxt.dev/dashboard and connect your wallet.
2. Click Withdraw, enter the USDC amount, and confirm the request transaction in your wallet.
3. Wait for the timelock to elapse (~1 hour in production). The dashboard shows a countdown for each pending request.
4. Come back, click Claim on the matured request, and confirm the claim transaction in your wallet. Funds move from escrow to your wallet.

If you change your mind during the timelock window, the dashboard exposes a Cancel action on the pending request — the funds stay in escrow as free balance.

Advanced: programmatic withdraw

For scripted withdrawals, client.escrow.withdraw_tx builds unsigned request / claim / cancel transactions you sign and broadcast with your own wallet library.

Request

Python

tx = client.escrow.withdraw_tx("request", amount=10.0)["tx"]
# Sign and send `tx`. After the timelock, the funds become claimable.

const { tx } = await client.escrow.withdrawTx("request", 10);

Inspect pending withdrawals

Python

state = client.escrow.withdrawals(include="pending,events")
# state.pending is a list of pending requests with their `claimable_at` timestamps.
for req in state["pending"]:
    print(req["amount"], "claimable at", req["claimable_at"])

const state = await client.escrow.withdrawals({ include: "pending,events" });
// state.pending lists requests with claimable_at timestamps
for (const req of state.pending) {
  console.log(req.amount, "claimable at", req.claimable_at);
}

Claim

Once claimable_at has passed, claim the funds — they move from escrow to your wallet.

Python

tx = client.escrow.withdraw_tx("claim")["tx"]

const { tx } = await client.escrow.withdrawTx("claim");

claim does not take an amount. It claims all matured requests at once. The escrow tracks individual request maturities; only matured ones settle.

Cancel

If you change your mind during the timelock window, cancel a pending request and the funds remain in escrow as free balance.

Python

tx = client.escrow.withdraw_tx("cancel")["tx"]

const { tx } = await client.escrow.withdrawTx("cancel");

Errors you might hit

• MissingWalletAddress — client.escrow.* requires wallet_address on the exchange constructor. Pass it explicitly.
• ValidationError: amount precision exceeds 6 decimals — round before passing.
• InsufficientEscrowBalance (during a trade) — deposit more before retrying, or wait for matured withdrawals to clear pending positions.
• HostedTradingError (5xx) — transient server error; retry with backoff. See Hosted errors.

Source references

• Python: sdks/python/pmxt/escrow.py
• TypeScript: sdks/typescript/pmxt/escrow.ts