Deposit wallets are the new wallet path for new API users. They replace the current proxy/Safe onboarding path for those new API users only. Existing users are unaffected in this phase and should continue using their current proxy or Safe setup. This rollout addresses the sustained rise in ghost fills that has caused instability for liquidity providers. The new flow makes the user’s trading wallet a deterministic smart account whose signatures are validated by the CLOB through ERC-1271.Documentation Index
Fetch the complete documentation index at: https://docs.polymarket.com/llms.txt
Use this file to discover all available pages before exploring further.
This guide is for developers integrating directly with the APIs or SDKs. It
does not change existing user balances, existing proxy wallets, or existing
Safes.
Until the production rollout, test against the preprod API URLs. On Monday,
when deposit wallets are released in production, the integration code stays
the same: replace the preprod relayer and CLOB URLs with the production URLs
in your SDK or API configuration.Relayer preprod URL:
https://relayer-v2-preprod-int.polymarket.com/What Changes
| Area | Before | New API user deposit wallet flow |
|---|---|---|
| Wallet created for new API users | Proxy wallet or Safe | Deposit wallet |
| Wallet deployment | Existing relayer Safe/proxy flow | Relayer WALLET-CREATE |
| Deployment signature | Safe deployment flow includes user signing | No user signature in the WALLET-CREATE payload |
| Wallet calls | Safe/proxy relayer transactions | Relayer WALLET batches |
| Order signature type | 0, 1, or 2 | 3, also called POLY_1271 |
| Order maker | EOA, proxy, or Safe | Deposit wallet address |
| Order signer field | EOA for existing types | Deposit wallet address |
| Signing key | User EOA or session signer | Deposit wallet owner or approved session signer |
Mental Model
A deposit wallet is a per-user ERC-1967 proxy deployed by a deposit wallet factory. The wallet holds pUSD and conditional tokens on-chain. The owner or session signer signs two different kinds of payloads:- A deposit wallet Batch for on-chain wallet calls. This is submitted to the
relayer as a
WALLETtransaction. - A CLOB order with
signatureType = 3. The CLOB validates this through ERC-1271 on the deposit wallet.
WALLET batch uses a normal
65-byte EIP-712 signature over the DepositWallet Batch type. A CLOB order
uses an ERC-7739-wrapped POLY_1271 signature and is longer than a normal ECDSA
signature.
New API User Flow
Create or identify the owner signer
Use the EOA or session signer that will own the deposit wallet. This signer is
also the key that signs deposit wallet batches and CLOB order payloads unless
your session signer flow delegates signing elsewhere.
Deploy the deposit wallet
Submit a relayer
WALLET-CREATE request. The body only needs the transaction
type, owner address, and deposit wallet factory address.The deposit wallet address is deterministic. TypeScript relayer users can call
deriveDepositWalletAddress(), and Python relayer users can call
get_expected_deposit_wallet(). Other integrations should store the address
returned by onboarding or derive it with the deterministic formula below.Fund the deposit wallet
Transfer pUSD to the deposit wallet address. pUSD held by the EOA does not count
as CLOB buying power for deposit wallet orders.
Approve trading contracts from the wallet
Approvals must be made from the deposit wallet, not from the owner EOA. Build
ERC-20 or ERC-1155 approval calldata and submit it through a relayer
WALLET
batch.Sync CLOB balances
After funding or changing allowances, call the CLOB balance allowance update
endpoint through the SDK or API. The request must use
signature_type = 3.SDK Users
Use a relayer client or the raw relayer API for wallet deployment and wallet batches. Use the CLOB client for order signing, posting, cancelling, balances, and account data.- TypeScript
- Python
- Rust
Use the TypeScript clients with deposit wallet support:
@polymarket/builder-relayer-client 0.0.9
and
@polymarket/clob-client-v2 1.0.3-canary.0.The TypeScript relayer client fetches the current
Deploy the Wallet
deployDepositWallet() submits a WALLET-CREATE transaction. It does not add a
user signature to the deployment body.Execute a Wallet Batch
WALLET nonce before signing
and submitting the batch. The SDK signs the batch with this EIP-712 domain before
submitting it to the relayer:Trade From the Deposit Wallet
API Users
Direct API integrations need to implement the same two relayer operations and the same CLOB order signature shape used by the SDKs.Deploy a Deposit Wallet
Submit this body to the relayer/submit endpoint:
| Field | Description |
|---|---|
type | Must be WALLET-CREATE |
from | Owner address for the deposit wallet |
to | Deposit wallet factory address for the active chain and environment |
| Chain | Deposit wallet factory |
|---|---|
Polygon mainnet 137 | 0x00000000000Fb5C9ADea0298D729A0CB3823Cc07 |
STATE_MINED or STATE_CONFIRMED. Store
the deployed wallet address from the WalletDeployed event, from your
onboarding flow, or derive it deterministically using the SDK’s chain config.
Deterministic address derivation follows the relayer clients:
Submit a Deposit Wallet Batch
For wallet actions such as token approvals, transfers, withdrawals, splits, or merges, fetch the currentWALLET nonce for the owner address, then sign a
Batch with the owner or session signer:
signature in a WALLET request is a normal 65-byte EIP-712 signature with
a 0x prefix. This is different from the CLOB order signature described below.
Place CLOB Orders
For deposit wallet orders, the raw order inside the/order request must use
signatureType = 3:
TypedDataSign payload under the
correct CTF Exchange V2 domain. The nested wallet fields are:
| Field | Value |
|---|---|
name | DepositWallet |
version | 1 |
chainId | Current chain ID |
verifyingContract | Deposit wallet address |
salt | 0x0000000000000000000000000000000000000000000000000000000000000000 |
POLY_1271 and the
deposit wallet funder address.
Sync Balance and Allowance
After funding the deposit wallet or approving contracts from it, update the CLOB balance cache usingsignature_type = 3.
Implementation Checklist
- Use deposit wallets only for new API users in this phase.
- Keep existing proxy and Safe users on their current signature type.
- Deploy the deposit wallet with relayer
WALLET-CREATE. - Store or derive the user’s deposit wallet address.
- Transfer pUSD to the deposit wallet, not only to the owner EOA.
- Approve pUSD and conditional token spenders through a
WALLETbatch. - Fetch the current
WALLETnonce fresh before each direct API batch. - Use
POLY_1271for CLOB orders from the deposit wallet. - Set CLOB order
makerandsignerto the deposit wallet address. - Sync CLOB balances with
signature_type = 3after deposits and approvals. - Use the correct exchange or negative-risk exchange verifying contract for the market being traded.
Common Issues
Order is rejected as invalid signature
Order is rejected as invalid signature
Check all four signature inputs:
signatureType must be 3, order maker must
be the deposit wallet, order signer must be the deposit wallet, and the order
signature must be the ERC-7739-wrapped POLY_1271 signature. Also confirm the
order was signed against the correct CTF Exchange V2 verifying contract for the
market.Wallet batch is rejected
Wallet batch is rejected
Fetch the current
WALLET nonce fresh from the relayer before signing the batch.
Confirm the deadline is still in the future and within the relayer’s accepted
range. The WALLET batch signature should be a normal 65-byte EIP-712 signature
over DepositWallet Batch.Order says not enough balance
Order says not enough balance
Confirm pUSD is held by the deposit wallet address. Then update the CLOB balance
cache with
signature_type = 3. pUSD sitting on the owner EOA does not fund
deposit wallet orders.Allowance is missing
Allowance is missing
Approvals must come from the deposit wallet. An EOA
approve() transaction does
not approve spending from the deposit wallet. Submit approval calldata through a
relayer WALLET batch.Direct API auth is confusing
Direct API auth is confusing
Relayer auth and CLOB auth are independent. Use the auth method required by your
relayer environment for
/submit. Use CLOB L1/L2 authentication for order and
balance endpoints. Do not reuse relayer cookies or headers as CLOB auth.