docs: sync with docs.polymarket.com - 2026-05-11
New pages: - docs/builders/fees.md (Builder Fees) - docs/trading/deposit-wallets.md (Deposit Wallets) Updated: - docs/concepts/pusd.md (Polymarket USD)
This commit is contained in:
Etherdrake
@@ -0,0 +1,264 @@
|
||||
# Builder Fees
|
||||
|
||||
> How builders earn fees on orders routed through their applications, and how to integrate.
|
||||
|
||||
CLOB V2 introduces a fee layer that lets builders earn a fee on every order routed through their application. When a builder attaches their unique **builder code** to an order and that order matches, a **builder fee** is collected alongside any platform fee.
|
||||
|
||||
Builder fees are flat percentages of trade notional, configured by each builder within enforced limits. They're additive — they stack on top of platform fees, never replace them.
|
||||
|
||||
<Note>
|
||||
New to the Builder Program? Start with [Builder Program](/builders/overview). This page covers the fee layer specifically.
|
||||
</Note>
|
||||
|
||||
***
|
||||
|
||||
## How it works
|
||||
|
||||
<Frame>
|
||||
<img src="https://mintcdn.com/polymarket-292d1b1b/lWwKl4XdsXxYugaA/images/core-concepts/builder-fee.png?fit=max&auto=format&n=lWwKl4XdsXxYugaA&q=85&s=9287dc95f24f07bcb9f33c4d7d6ed0f2" alt="" className="dark:hidden" width="2068" height="952" data-path="images/core-concepts/builder-fee.png" />
|
||||
|
||||
<img src="https://mintcdn.com/polymarket-292d1b1b/lWwKl4XdsXxYugaA/images/dark/core-concepts/builder-fee.png?fit=max&auto=format&n=lWwKl4XdsXxYugaA&q=85&s=31b5e9be53b16738ad9f2b833b1eb02a" alt="" className="hidden dark:block" width="2068" height="952" data-path="images/dark/core-concepts/builder-fee.png" />
|
||||
</Frame>
|
||||
|
||||
Builder fees and platform fees are independent. What the user pays depends on the market config and whether a builder code is attached:
|
||||
|
||||
| Market | Builder code attached | User pays |
|
||||
| -------------------- | --------------------- | -------------------------- |
|
||||
| No platform fee | No | Nothing |
|
||||
| No platform fee | Yes | Builder fee only |
|
||||
| Platform fee enabled | No | Platform fee only |
|
||||
| Platform fee enabled | Yes | Platform fee + builder fee |
|
||||
|
||||
Builder fees never replace platform fees — they're always additive.
|
||||
|
||||
<Warning>
|
||||
Polymarket reserves the right to revoke your ability to charge a builder fee in its sole discretion, for any reason or no reason, including but not limited to instances where fees are determined to have been collected through fraudulent, deceptive, misleading, automated, self-referred, or other non-bona fide trading activity.
|
||||
</Warning>
|
||||
|
||||
***
|
||||
|
||||
## Registration
|
||||
|
||||
Register for a builder code through your Polymarket account.
|
||||
|
||||
<Steps>
|
||||
<Step title="Create a builder profile">
|
||||
Go to [polymarket.com/settings?tab=builder](https://polymarket.com/settings?tab=builder) and set up your builder profile.
|
||||
</Step>
|
||||
|
||||
<Step title="Set your fee rates">
|
||||
Configure two rates on your profile:
|
||||
|
||||
* `builder_taker_fee_bps` — charged on taker orders routed through your app
|
||||
* `builder_maker_fee_bps` — charged on maker orders routed through your app
|
||||
</Step>
|
||||
|
||||
<Step title="Copy your builder code">
|
||||
Your profile is assigned a `bytes32` builder code. Attach it to every order you submit.
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
### Fee rate limits
|
||||
|
||||
| Parameter | Default | Maximum |
|
||||
| -------------- | ---------- | ------------- |
|
||||
| Taker fee rate | 0 bps (0%) | 100 bps (1%) |
|
||||
| Maker fee rate | 0 bps (0%) | 50 bps (0.5%) |
|
||||
| Granularity | — | 1 bp (0.01%) |
|
||||
|
||||
### Rate change policy
|
||||
|
||||
Fee rate changes are gated so users can see them coming:
|
||||
|
||||
* **Cooldown.** One rate change per 7 days.
|
||||
* **Advance notice.** Changes take effect 3 days after being scheduled.
|
||||
* **One pending change at a time.** You can't queue multiple changes — wait for the current one to take effect (or cancel it) before scheduling another.
|
||||
|
||||
***
|
||||
|
||||
## SDK integration
|
||||
|
||||
The V2 SDK handles builder codes natively — no separate signing library, no extra headers.
|
||||
|
||||
### Install
|
||||
|
||||
<CodeGroup>
|
||||
```bash TypeScript theme={null}
|
||||
npm install @polymarket/clob-client-v2 viem
|
||||
```
|
||||
|
||||
```bash Python theme={null}
|
||||
pip install py-clob-client-v2
|
||||
```
|
||||
</CodeGroup>
|
||||
|
||||
<Note>
|
||||
Coming from the old `@polymarket/builder-signing-sdk` + HMAC header flow? That's gone in V2 — see [Migrating to CLOB V2](/v2-migration#builder-program) for the full upgrade path.
|
||||
</Note>
|
||||
|
||||
### Attach your builder code
|
||||
|
||||
Pass `builderCode` on every order your application submits. This is how trades are attributed to your profile.
|
||||
|
||||
**Limit order:**
|
||||
|
||||
```typescript theme={null}
|
||||
const response = await client.createAndPostOrder(
|
||||
{
|
||||
tokenID: "0x123...",
|
||||
price: 0.55,
|
||||
size: 100,
|
||||
side: Side.BUY,
|
||||
expiration: 1714000000,
|
||||
builderCode: process.env.POLY_BUILDER_CODE,
|
||||
},
|
||||
{ tickSize: "0.01", negRisk: false },
|
||||
OrderType.GTC,
|
||||
);
|
||||
```
|
||||
|
||||
**Market order:**
|
||||
|
||||
```typescript theme={null}
|
||||
const response = await client.createAndPostMarketOrder(
|
||||
{
|
||||
tokenID: "0x123...",
|
||||
side: Side.BUY,
|
||||
amount: 500,
|
||||
price: 0.5, // worst-price limit (slippage protection)
|
||||
userUSDCBalance: 1000, // optional — enables fee-aware fill calculations
|
||||
builderCode: process.env.POLY_BUILDER_CODE,
|
||||
},
|
||||
{ tickSize: "0.01", negRisk: false },
|
||||
OrderType.FOK,
|
||||
);
|
||||
```
|
||||
|
||||
If `builderCode` is omitted, no builder fee is charged.
|
||||
|
||||
<Tip>
|
||||
You can also pass `builderConfig: { builderCode }` once at client construction and every order inherits it. See [Migrating to CLOB V2](/v2-migration#builder-program) for both patterns.
|
||||
</Tip>
|
||||
|
||||
### Query fee parameters
|
||||
|
||||
`getClobMarketInfo()` returns both platform and builder fee parameters for a market:
|
||||
|
||||
```typescript theme={null}
|
||||
const info = await client.getClobMarketInfo(conditionID);
|
||||
|
||||
// Platform fee
|
||||
// info.fd.r — fee rate
|
||||
// info.fd.e — fee exponent
|
||||
// info.fd.to — taker-only flag
|
||||
|
||||
// Builder fee
|
||||
// info.mbf — builder maker fee rate
|
||||
// info.tbf — builder taker fee rate
|
||||
```
|
||||
|
||||
***
|
||||
|
||||
## Fee calculation
|
||||
|
||||
### Platform fees
|
||||
|
||||
Platform fees use a dynamic per-market formula:
|
||||
|
||||
```
|
||||
platform_fee = C × feeRate × p × (1 - p)
|
||||
```
|
||||
|
||||
Where `C` is the trade size, `p` is the order price, and `feeRate` is a per-market parameter. Platform fees are currently taker-only and are not configurable by builders.
|
||||
|
||||
### Builder fees
|
||||
|
||||
Builder fees are a flat percentage of notional:
|
||||
|
||||
```
|
||||
builder_fee = notional × builder_fee_rate_bps / 10000
|
||||
```
|
||||
|
||||
**Example.** A 1,000 pUSD taker buy routed through a builder charging 100 bps (1%) taker fee:
|
||||
|
||||
```
|
||||
builder_fee = 1000 × 100 / 10000 = 10 pUSD
|
||||
```
|
||||
|
||||
The maker and taker sides of a single trade can have different builder codes and different rates. If Builder A (0.3% maker) posts the resting order and Builder B (0.8% taker) submits the matching order, each earns their respective fee from their respective side.
|
||||
|
||||
### Balance checks
|
||||
|
||||
The CLOB's balance checker accounts for all applicable fees (platform + builder) when validating an order. Users must have enough pUSD to cover the trade plus the maximum possible fees.
|
||||
|
||||
For market buy orders, pass `userUSDCBalance` and the SDK computes fee-adjusted fill amounts automatically.
|
||||
|
||||
***
|
||||
|
||||
## Onchain attribution
|
||||
|
||||
Builder attribution is part of the signed V2 order struct — not an offchain label. The `builder` field appears in every `OrderFilled` event emitted by the CTF Exchange V2 contract.
|
||||
|
||||
### V2 order struct
|
||||
|
||||
```
|
||||
salt, maker, signer, tokenId, makerAmount, takerAmount,
|
||||
side, signatureType, timestamp, metadata, builder
|
||||
```
|
||||
|
||||
The `builder` field is a `bytes32` matching your registered builder code.
|
||||
|
||||
### EIP-712 domain
|
||||
|
||||
The Exchange domain version is `"2"` in V2 (up from `"1"`). If you construct EIP-712 typed data manually rather than via the SDK, update your domain separator — see [For API users](/v2-migration#for-api-users) in the migration guide.
|
||||
|
||||
***
|
||||
|
||||
## Fee processing and payouts
|
||||
|
||||
When a user places an order with your `builderCode` attached:
|
||||
|
||||
1. The CLOB validates the order and the builder code.
|
||||
2. At match time, the Fees Service computes the platform and builder fees for each side.
|
||||
3. The trade settles onchain via `CTFExchangeV2.matchOrders()`, emitting `OrderFilled` events.
|
||||
4. The Builders Service indexes those events, joins onchain attribution with your builder profile, and accrues your earned fees.
|
||||
|
||||
Collected builder fees are distributed to the wallet associated with your builder profile.
|
||||
|
||||
***
|
||||
|
||||
## Program policies
|
||||
|
||||
### Disabled codes
|
||||
|
||||
Polymarket may disable a builder code at any time — for violations of the Builder Program terms, abusive fee practices, or platform integrity concerns. Orders carrying a disabled code will be rejected by the CLOB.
|
||||
|
||||
### Public visibility
|
||||
|
||||
Builder profiles and fee rates are publicly queryable. This is intentional — it lets users and third parties see what a builder charges before using their app.
|
||||
|
||||
### Existing builders
|
||||
|
||||
Builders with V1 integrations have builder code entities provisioned automatically. No action is required beyond upgrading to the V2 SDK and attaching your builder code to orders. See [Migrating to CLOB V2](/v2-migration) for the full upgrade path.
|
||||
|
||||
***
|
||||
|
||||
## Next steps
|
||||
|
||||
<CardGroup cols={2}>
|
||||
<Card title="Builder Program" icon="hammer" href="/builders/overview">
|
||||
Overview of the Builder Program and benefits
|
||||
</Card>
|
||||
|
||||
<Card title="Builder Methods" icon="code" href="/trading/clients/builder">
|
||||
SDK methods for querying your builder trades and orders
|
||||
</Card>
|
||||
|
||||
<Card title="Order Attribution" icon="tag" href="/trading/orders/attribution">
|
||||
Details on attaching builder codes to orders
|
||||
</Card>
|
||||
|
||||
<Card title="Migration Guide" icon="arrow-right" href="/v2-migration">
|
||||
Full V2 migration guide
|
||||
</Card>
|
||||
</CardGroup>
|
||||
@@ -1,7 +1,3 @@
|
||||
> ## 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.
|
||||
|
||||
# Polymarket USD
|
||||
|
||||
> pUSD — the collateral token used for all trading on Polymarket
|
||||
@@ -163,4 +159,4 @@ function unwrap(address _asset, address _to, uint256 _amount) external
|
||||
<Card title="Bridge" icon="arrow-right-arrow-left" href="/trading/bridge/deposit">
|
||||
Deposit from other chains — auto-wraps to pUSD
|
||||
</Card>
|
||||
</CardGroup>
|
||||
</CardGroup>
|
||||
@@ -0,0 +1,509 @@
|
||||
# Deposit Wallets
|
||||
|
||||
> Create deposit wallets, execute wallet actions, and place POLY_1271 orders
|
||||
|
||||
Deposit wallets are the wallet path for **new API users**. Existing Safe and
|
||||
Proxy users are unaffected and can continue using their current wallet setup.
|
||||
|
||||
For newly-created polymarket.com accounts using the deposit wallet flow, a
|
||||
deposit wallet is automatically deployed for you.
|
||||
|
||||
<Info>
|
||||
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.
|
||||
</Info>
|
||||
|
||||
## Where Deposit Wallets Fit
|
||||
|
||||
| Area | Existing Safe/Proxy users | New API user deposit wallet flow |
|
||||
| -------------------- | ----------------------------------- | ------------------------------------------------ |
|
||||
| Wallet type | Existing proxy wallet or Safe | Deposit wallet |
|
||||
| Wallet deployment | Existing relayer Safe/proxy flow | Relayer `WALLET-CREATE` |
|
||||
| Deployment signature | Existing Safe/proxy deployment flow | 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:
|
||||
|
||||
1. A **deposit wallet Batch** for on-chain wallet calls. This is submitted to the
|
||||
relayer as a `WALLET` transaction.
|
||||
2. A **CLOB order** with `signatureType = 3`. The CLOB validates this through
|
||||
ERC-1271 on the deposit wallet.
|
||||
|
||||
These signatures are not interchangeable. A `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.
|
||||
|
||||
## Integration Flow
|
||||
|
||||
<Steps>
|
||||
<Step title="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.
|
||||
</Step>
|
||||
|
||||
<Step title="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.
|
||||
</Step>
|
||||
|
||||
<Step title="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.
|
||||
</Step>
|
||||
|
||||
<Step title="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.
|
||||
</Step>
|
||||
|
||||
<Step title="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`.
|
||||
</Step>
|
||||
|
||||
<Step title="Place orders with POLY_1271">
|
||||
Initialize the CLOB client with the deposit wallet as the funder and
|
||||
`POLY_1271` as the signature type. Orders must have both `maker` and `signer`
|
||||
set to the deposit wallet address.
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
## 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.
|
||||
|
||||
<Tabs>
|
||||
<Tab title="TypeScript">
|
||||
Use the TypeScript clients with deposit wallet support:
|
||||
[@polymarket/builder-relayer-client](https://www.npmjs.com/package/@polymarket/builder-relayer-client)
|
||||
and
|
||||
[@polymarket/clob-client-v2](https://www.npmjs.com/package/@polymarket/clob-client-v2).
|
||||
|
||||
```bash theme={null}
|
||||
npm install @polymarket/builder-relayer-client @polymarket/clob-client-v2 @polymarket/builder-signing-sdk viem
|
||||
```
|
||||
|
||||
### Deploy the Wallet
|
||||
|
||||
```typescript theme={null}
|
||||
import {
|
||||
BuilderApiKeyCreds,
|
||||
BuilderConfig,
|
||||
} from "@polymarket/builder-signing-sdk";
|
||||
import { RelayClient } from "@polymarket/builder-relayer-client";
|
||||
import { createWalletClient, Hex, http } from "viem";
|
||||
import { privateKeyToAccount } from "viem/accounts";
|
||||
import { polygon } from "viem/chains";
|
||||
|
||||
const relayerUrl = process.env.RELAYER_URL!;
|
||||
const chainId = Number(process.env.CHAIN_ID ?? 137);
|
||||
const account = privateKeyToAccount(process.env.PRIVATE_KEY as Hex);
|
||||
const walletClient = createWalletClient({
|
||||
account,
|
||||
chain: polygon,
|
||||
transport: http(process.env.RPC_URL),
|
||||
});
|
||||
|
||||
const builderCreds: BuilderApiKeyCreds = {
|
||||
key: process.env.BUILDER_API_KEY!,
|
||||
secret: process.env.BUILDER_SECRET!,
|
||||
passphrase: process.env.BUILDER_PASS_PHRASE!,
|
||||
};
|
||||
|
||||
const builderConfig = new BuilderConfig({
|
||||
localBuilderCreds: builderCreds,
|
||||
});
|
||||
|
||||
const relayer = new RelayClient(
|
||||
relayerUrl,
|
||||
chainId,
|
||||
walletClient,
|
||||
builderConfig,
|
||||
);
|
||||
|
||||
const depositWalletAddress = await relayer.deriveDepositWalletAddress();
|
||||
const response = await relayer.deployDepositWallet();
|
||||
const confirmed = await response.wait();
|
||||
```
|
||||
|
||||
`deployDepositWallet()` submits a `WALLET-CREATE` transaction. It does not add a
|
||||
user signature to the deployment body.
|
||||
|
||||
### Execute a Wallet Batch
|
||||
|
||||
```typescript theme={null}
|
||||
import type { DepositWalletCall } from "@polymarket/builder-relayer-client";
|
||||
|
||||
const calls: DepositWalletCall[] = [
|
||||
{
|
||||
target: process.env.PUSD_ADDRESS!,
|
||||
value: "0",
|
||||
data: approveCalldata,
|
||||
},
|
||||
];
|
||||
|
||||
const deadline = Math.floor(Date.now() / 1000 + 600).toString();
|
||||
const response = await relayer.executeDepositWalletBatch(
|
||||
calls,
|
||||
depositWalletAddress,
|
||||
deadline,
|
||||
);
|
||||
const confirmed = await response.wait();
|
||||
```
|
||||
|
||||
The TypeScript relayer client fetches the current `WALLET` nonce before signing
|
||||
and submitting the batch. The SDK signs the batch with this EIP-712 domain before
|
||||
submitting it to the relayer:
|
||||
|
||||
```typescript theme={null}
|
||||
{
|
||||
name: "DepositWallet",
|
||||
version: "1",
|
||||
chainId,
|
||||
verifyingContract: depositWalletAddress,
|
||||
}
|
||||
```
|
||||
|
||||
### Trade From the Deposit Wallet
|
||||
|
||||
```typescript theme={null}
|
||||
import {
|
||||
AssetType,
|
||||
ClobClient,
|
||||
OrderType,
|
||||
Side,
|
||||
SignatureTypeV2,
|
||||
} from "@polymarket/clob-client-v2";
|
||||
|
||||
const creds = {
|
||||
key: process.env.CLOB_API_KEY!,
|
||||
secret: process.env.CLOB_SECRET!,
|
||||
passphrase: process.env.CLOB_PASS_PHRASE!,
|
||||
};
|
||||
|
||||
const clob = new ClobClient({
|
||||
host: process.env.CLOB_API_URL!,
|
||||
chain: chainId,
|
||||
signer: walletClient,
|
||||
creds,
|
||||
signatureType: SignatureTypeV2.POLY_1271,
|
||||
funderAddress: depositWalletAddress,
|
||||
});
|
||||
|
||||
await clob.updateBalanceAllowance({ asset_type: AssetType.COLLATERAL });
|
||||
|
||||
const order = await clob.createAndPostOrder(
|
||||
{
|
||||
tokenID: process.env.TOKEN_ID!,
|
||||
price: 0.5,
|
||||
size: 10,
|
||||
side: Side.BUY,
|
||||
},
|
||||
{ tickSize: "0.01", negRisk: false },
|
||||
OrderType.GTC,
|
||||
);
|
||||
```
|
||||
</Tab>
|
||||
|
||||
<Tab title="Python">
|
||||
Use the Python builder relayer client with deposit wallet support:
|
||||
[py-builder-relayer-client](https://pypi.org/project/py-builder-relayer-client/).
|
||||
|
||||
```bash theme={null}
|
||||
pip install py-builder-relayer-client
|
||||
```
|
||||
|
||||
### Deploy the Wallet
|
||||
|
||||
```python theme={null}
|
||||
import os
|
||||
|
||||
from py_builder_relayer_client.client import RelayClient
|
||||
from py_builder_signing_sdk.config import BuilderApiKeyCreds, BuilderConfig
|
||||
|
||||
builder_config = BuilderConfig(
|
||||
local_builder_creds=BuilderApiKeyCreds(
|
||||
key=os.environ["BUILDER_API_KEY"],
|
||||
secret=os.environ["BUILDER_SECRET"],
|
||||
passphrase=os.environ["BUILDER_PASS_PHRASE"],
|
||||
)
|
||||
)
|
||||
|
||||
relayer = RelayClient(
|
||||
os.environ["RELAYER_URL"],
|
||||
int(os.environ.get("CHAIN_ID", "137")),
|
||||
os.environ["PRIVATE_KEY"],
|
||||
builder_config,
|
||||
)
|
||||
|
||||
deposit_wallet = relayer.get_expected_deposit_wallet()
|
||||
response = relayer.deploy_deposit_wallet()
|
||||
confirmed = response.wait()
|
||||
```
|
||||
|
||||
`get_expected_deposit_wallet()` derives the deterministic wallet address from
|
||||
the signer and the chain's deposit wallet configuration.
|
||||
|
||||
### Execute a Wallet Batch
|
||||
|
||||
```python theme={null}
|
||||
import time
|
||||
|
||||
from py_builder_relayer_client.models import DepositWalletCall, TransactionType
|
||||
|
||||
nonce_payload = relayer.get_nonce(
|
||||
relayer.signer.address(),
|
||||
TransactionType.WALLET.value,
|
||||
)
|
||||
wallet_nonce = str(nonce_payload["nonce"])
|
||||
|
||||
call = DepositWalletCall(
|
||||
target=os.environ["PUSD_ADDRESS"],
|
||||
value="0",
|
||||
data=approve_calldata,
|
||||
)
|
||||
|
||||
response = relayer.execute_deposit_wallet_batch(
|
||||
calls=[call],
|
||||
wallet_address=deposit_wallet,
|
||||
nonce=wallet_nonce,
|
||||
deadline=str(int(time.time()) + 600),
|
||||
)
|
||||
confirmed = response.wait()
|
||||
```
|
||||
|
||||
The Python relayer client mirrors the TypeScript wire format for `WALLET-CREATE`
|
||||
and `WALLET` requests, while keeping builder API key auth in the Python client.
|
||||
|
||||
### Trade From the Deposit Wallet
|
||||
|
||||
Use the Python CLOB client with deposit wallet order support:
|
||||
[py-clob-client-v2](https://pypi.org/project/py-clob-client-v2/).
|
||||
|
||||
```bash theme={null}
|
||||
pip install py-clob-client-v2
|
||||
```
|
||||
|
||||
```python theme={null}
|
||||
import os
|
||||
|
||||
from py_clob_client_v2 import (
|
||||
ApiCreds,
|
||||
AssetType,
|
||||
BalanceAllowanceParams,
|
||||
ClobClient,
|
||||
OrderArgs,
|
||||
OrderType,
|
||||
PartialCreateOrderOptions,
|
||||
Side,
|
||||
SignatureTypeV2,
|
||||
)
|
||||
|
||||
creds = ApiCreds(
|
||||
api_key=os.environ["CLOB_API_KEY"],
|
||||
api_secret=os.environ["CLOB_SECRET"],
|
||||
api_passphrase=os.environ["CLOB_PASS_PHRASE"],
|
||||
)
|
||||
|
||||
clob = ClobClient(
|
||||
host=os.environ["CLOB_API_URL"],
|
||||
chain_id=int(os.environ.get("CHAIN_ID", "137")),
|
||||
key=os.environ["PRIVATE_KEY"],
|
||||
creds=creds,
|
||||
signature_type=SignatureTypeV2.POLY_1271,
|
||||
funder=deposit_wallet,
|
||||
)
|
||||
|
||||
clob.update_balance_allowance(
|
||||
BalanceAllowanceParams(
|
||||
asset_type=AssetType.COLLATERAL,
|
||||
signature_type=SignatureTypeV2.POLY_1271,
|
||||
)
|
||||
)
|
||||
|
||||
response = clob.create_and_post_order(
|
||||
order_args=OrderArgs(
|
||||
token_id=os.environ["TOKEN_ID"],
|
||||
price=0.50,
|
||||
size=10,
|
||||
side=Side.BUY,
|
||||
),
|
||||
options=PartialCreateOrderOptions(tick_size="0.01", neg_risk=False),
|
||||
order_type=OrderType.GTC,
|
||||
)
|
||||
```
|
||||
</Tab>
|
||||
|
||||
<Tab title="Rust">
|
||||
### Deploy the Wallet and Execute Wallet Batches
|
||||
|
||||
The Rust SDK supports the CLOB order path for deposit wallets. It does not
|
||||
include a builder relayer client. Use the TypeScript or Python relayer client
|
||||
above, or the raw API flow below, to submit `WALLET-CREATE` and `WALLET`
|
||||
transactions.
|
||||
|
||||
Use the Rust CLOB client with deposit wallet support:
|
||||
[polymarket_client_sdk_v2](https://crates.io/crates/polymarket_client_sdk_v2).
|
||||
|
||||
```bash theme={null}
|
||||
cargo add polymarket_client_sdk_v2 --features clob
|
||||
```
|
||||
|
||||
Once the deposit wallet is deployed, funded, and approved, pass the deposit
|
||||
wallet address as the Rust CLOB client funder.
|
||||
|
||||
### Trade From the Deposit Wallet
|
||||
|
||||
```rust theme={null}
|
||||
use std::str::FromStr as _;
|
||||
|
||||
use polymarket_client_sdk_v2::auth::{LocalSigner, Signer as _};
|
||||
use polymarket_client_sdk_v2::clob::types::request::UpdateBalanceAllowanceRequest;
|
||||
use polymarket_client_sdk_v2::clob::types::{AssetType, OrderType, Side, SignatureType};
|
||||
use polymarket_client_sdk_v2::clob::{Client, Config};
|
||||
use polymarket_client_sdk_v2::types::{Address, Decimal, U256};
|
||||
use polymarket_client_sdk_v2::{POLYGON, PRIVATE_KEY_VAR};
|
||||
|
||||
let host = std::env::var("CLOB_API_URL")?;
|
||||
let token_id = U256::from_str(&std::env::var("TOKEN_ID")?)?;
|
||||
let deposit_wallet = Address::from_str(&std::env::var("DEPOSIT_WALLET")?)?;
|
||||
let signer =
|
||||
LocalSigner::from_str(&std::env::var(PRIVATE_KEY_VAR)?)?.with_chain_id(Some(POLYGON));
|
||||
|
||||
let client = Client::new(&host, Config::default())?
|
||||
.authentication_builder(&signer)
|
||||
.funder(deposit_wallet)
|
||||
.signature_type(SignatureType::Poly1271)
|
||||
.authenticate()
|
||||
.await?;
|
||||
|
||||
client
|
||||
.update_balance_allowance(
|
||||
UpdateBalanceAllowanceRequest::builder()
|
||||
.asset_type(AssetType::Collateral)
|
||||
.build(),
|
||||
)
|
||||
.await?;
|
||||
|
||||
let _response = client
|
||||
.limit_order()
|
||||
.token_id(token_id)
|
||||
.side(Side::Buy)
|
||||
.price(Decimal::from_str("0.50")?)
|
||||
.size(Decimal::from_str("10")?)
|
||||
.order_type(OrderType::GTC)
|
||||
.build_sign_and_post(&signer)
|
||||
.await?;
|
||||
```
|
||||
|
||||
The Rust client sets `signatureType = 3` and builds the wrapped ERC-1271 order
|
||||
signature when `SignatureType::Poly1271` and a deposit wallet funder are
|
||||
configured.
|
||||
</Tab>
|
||||
</Tabs>
|
||||
|
||||
## Raw API Integration
|
||||
|
||||
### Deposit Wallet Factory
|
||||
|
||||
The factory is configured per chain. Use the relayer's `GET /config` endpoint to
|
||||
retrieve the current factory address.
|
||||
|
||||
```json
|
||||
{
|
||||
"deposit_wallet_factory": "0x..."
|
||||
}
|
||||
```
|
||||
|
||||
### Deriving the Deposit Wallet Address
|
||||
|
||||
The wallet address is deterministic. Use the salt `0x0000000000000000000000000000000000000000000000000000000000000000`.
|
||||
|
||||
```
|
||||
depositWallet = factory.computeAddress(salt, initCode)
|
||||
```
|
||||
|
||||
Where `initCode` is the ERC-1967 proxy initialization code. Use the relayer client's
|
||||
`deriveDepositWalletAddress()` method or `get_expected_deposit_wallet()` helper.
|
||||
|
||||
### WALLET-CREATE
|
||||
|
||||
```json
|
||||
{
|
||||
"transactionType": "WALLET-CREATE",
|
||||
"owner": "0x...",
|
||||
"factory": "0x..."
|
||||
}
|
||||
```
|
||||
|
||||
No user signature is required. The relayer signs and submits the transaction.
|
||||
|
||||
### WALLET
|
||||
|
||||
```json
|
||||
{
|
||||
"transactionType": "WALLET",
|
||||
"calls": [
|
||||
{
|
||||
"target": "0x...",
|
||||
"value": "0",
|
||||
"data": "0x..."
|
||||
}
|
||||
],
|
||||
"nonce": "123",
|
||||
"deadline": "1714000000"
|
||||
}
|
||||
```
|
||||
|
||||
The batch is signed with a standard EIP-712 `DepositWallet.Batch` domain:
|
||||
|
||||
```typescript theme={null}
|
||||
{
|
||||
name: "DepositWallet",
|
||||
version: "1",
|
||||
chainId,
|
||||
verifyingContract: depositWalletAddress,
|
||||
}
|
||||
```
|
||||
|
||||
The relayer signs and submits on your behalf.
|
||||
|
||||
## Next Steps
|
||||
|
||||
<CardGroup cols={2}>
|
||||
<Card title="Builder Program" icon="hammer" href="/builders/overview">
|
||||
Overview of the Builder Program and benefits
|
||||
</Card>
|
||||
|
||||
<Card title="Builder Fees" icon="dollar" href="/builders/fees">
|
||||
How builder fees work and how to set rates
|
||||
</Card>
|
||||
|
||||
<Card title="pUSD" icon="coin" href="/concepts/pusd">
|
||||
The collateral token powering Polymarket trading
|
||||
</Card>
|
||||
|
||||
<Card title="Migration Guide" icon="arrow-right" href="/v2-migration">
|
||||
Full V2 migration guide
|
||||
</Card>
|
||||
</CardGroup>
|
||||
Reference in New Issue
Block a user