gavindiaz/PolymarketDocumentation
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: sync with official Polymarket docs - 2026-04-20

Browse Source
This commit is contained in:
Etherdrake
2026-04-20 01:19:37 +02:00
parent 3ad0048c35
commit ff4882db02
50 changed files with 705 additions and 1857 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/advanced/neg-risk.md
+1 -1
View File
@@ -71,7 +71,7 @@ const response = await client.createAndPostOrder(
Neg risk markets use different contracts than standard markets:
See [Contract Addresses](/resources/contract-addresses) for the Neg Risk Adapter and Neg Risk CTF Exchange addresses.
See [Contracts](/resources/contracts) for the Neg Risk Adapter and Neg Risk CTF Exchange addresses.
## Augmented Negative Risk
docs/api-reference/bridge/create-deposit-addresses.md
+1 -1
View File
@@ -65,7 +65,7 @@ components:
$ref: '#/components/schemas/Address'
description: >-
Your Polymarket wallet address where deposited funds will be
credited as USDC.e
credited as pUSD
DepositResponse:
type: object
properties:
docs/api-reference/bridge/get-a-quote.md
+2 -2
View File
@@ -39,7 +39,7 @@ paths:
fromTokenAddress: '0x3c499c542cEF5E3811e1192ce70d8cC03d5c3359'
recipientAddress: '0x17eC161f126e82A8ba337f4022d574DBEaFef575'
toChainId: '137'
toTokenAddress: '0x2791Bca1f2de4661ED88A30C99A7a9449Aa84174'
toTokenAddress: '0xC011a7E12a19f7B1f670d46F03B03f3342E82DFB'
responses:
'200':
description: Quote retrieved successfully
@@ -135,7 +135,7 @@ components:
toTokenAddress:
type: string
description: Destination token address
example: '0x2791Bca1f2de4661ED88A30C99A7a9449Aa84174'
example: '0xC011a7E12a19f7B1f670d46F03B03f3342E82DFB'
QuoteResponse:
type: object
properties:
docs/api-reference/bridge/get-transaction-status.md
+4 -4
View File
@@ -50,20 +50,20 @@ paths:
fromTokenAddress: '11111111111111111111111111111111'
fromAmountBaseUnit: '13566635'
toChainId: '137'
toTokenAddress: '0x2791Bca1f2de4661ED88A30C99A7a9449Aa84174'
toTokenAddress: '0xC011a7E12a19f7B1f670d46F03B03f3342E82DFB'
status: DEPOSIT_DETECTED
- fromChainId: '1151111081099710'
fromTokenAddress: '11111111111111111111111111111111'
fromAmountBaseUnit: '13400000'
toChainId: '137'
toTokenAddress: '0x2791Bca1f2de4661ED88A30C99A7a9449Aa84174'
toTokenAddress: '0xC011a7E12a19f7B1f670d46F03B03f3342E82DFB'
createdTimeMs: 1757646914535
status: PROCESSING
- fromChainId: '1151111081099710'
fromTokenAddress: '11111111111111111111111111111111'
fromAmountBaseUnit: '13500152'
toChainId: '137'
toTokenAddress: '0x2791Bca1f2de4661ED88A30C99A7a9449Aa84174'
toTokenAddress: '0xC011a7E12a19f7B1f670d46F03B03f3342E82DFB'
txHash: >-
3atr19NAiNCYt24RHM1WnzZp47RXskpTDzspJoCBBaMFwUB8fk37hFkxz35P5UEnnmWz21rb2t5wJ8pq3EE2XnxU
createdTimeMs: 1757531217339
@@ -123,7 +123,7 @@ components:
toTokenAddress:
type: string
description: Destination token contract address
example: '0x2791Bca1f2de4661ED88A30C99A7a9449Aa84174'
example: '0xC011a7E12a19f7B1f670d46F03B03f3342E82DFB'
status:
type: string
description: >
docs/api-reference/clients-sdks.md
+14 -25
View File
@@ -12,11 +12,11 @@ Polymarket provides official open-source clients in TypeScript, Python, and Rust
<CodeGroup>
```bash TypeScript theme={null}
npm install @polymarket/clob-client ethers@5
npm install @polymarket/clob-client-v2 ethers@5
```
```bash Python theme={null}
pip install py-clob-client
pip install py-clob-client-v2
```
```bash Rust theme={null}
@@ -28,14 +28,14 @@ Polymarket provides official open-source clients in TypeScript, Python, and Rust
<CodeGroup>
```typescript TypeScript theme={null}
import { ClobClient } from "@polymarket/clob-client";
import { ClobClient } from "@polymarket/clob-client-v2";
const client = new ClobClient(
"https://clob.polymarket.com",
137,
const client = new ClobClient({
host: "https://clob.polymarket.com",
chain: 137,
signer,
apiCreds,
);
creds: apiCreds,
});
const markets = await client.getMarkets();
```
@@ -46,7 +46,7 @@ Polymarket provides official open-source clients in TypeScript, Python, and Rust
client = ClobClient(
"https://clob.polymarket.com",
key=private_key,
chain_id=137,
chain=137,
creds=api_creds,
)
@@ -67,25 +67,14 @@ Polymarket provides official open-source clients in TypeScript, Python, and Rust
## Source Code
| Language | Package | Repository |
| ---------- | ------------------------- | ------------------------------------------------------------------------------------ |
| TypeScript | `@polymarket/clob-client` | [github.com/Polymarket/clob-client](https://github.com/Polymarket/clob-client) |
| Python | `py-clob-client` | [github.com/Polymarket/py-clob-client](https://github.com/Polymarket/py-clob-client) |
| Rust | `polymarket-client-sdk` | [github.com/Polymarket/rs-clob-client](https://github.com/Polymarket/rs-clob-client) |
| Language | Package | Repository |
| ---------- | ---------------------------- | ------------------------------------------------------------------------------------------ |
| TypeScript | `@polymarket/clob-client-v2` | [github.com/Polymarket/clob-client-v2](https://github.com/Polymarket/clob-client-v2) |
| Python | `py-clob-client-v2` | [github.com/Polymarket/py-clob-client-v2](https://github.com/Polymarket/py-clob-client-v2) |
| Rust | `polymarket-client-sdk` | [github.com/Polymarket/rs-clob-client-v2](https://github.com/Polymarket/rs-clob-client-v2) |
Each repository includes working examples in the `/examples` directory.
## Builder SDKs
If you're building an app through the [Builder Program](/builders/overview), additional signing SDKs are available:
| Language | Package | Repository |
| ---------- | --------------------------------- | ---------------------------------------------------------------------------------------------------- |
| TypeScript | `@polymarket/builder-signing-sdk` | [github.com/Polymarket/builder-signing-sdk](https://github.com/Polymarket/builder-signing-sdk) |
| Python | `py_builder_signing_sdk` | [github.com/Polymarket/py-builder-signing-sdk](https://github.com/Polymarket/py-builder-signing-sdk) |
See [Order Attribution](/trading/orders/attribution) for usage details.
## Relayer SDK
For [gasless transactions](/trading/gasless) using proxy wallets, the relayer client handles submitting transactions through Polymarket's relayer:
docs/api-reference/rebates/get-current-rebated-fees-for-a-maker.md
+2 -2
View File
@@ -88,7 +88,7 @@ paths:
- date: '2026-02-27'
condition_id: >-
0xbd31dc8a20211944f6b70f31557f1001557b59905b7738480ca09bd4532f84af
asset_address: '0x2791Bca1f2de4661ED88A30C99A7a9449Aa84174'
asset_address: '0xC011a7E12a19f7B1f670d46F03B03f3342E82DFB'
maker_address: '0xFeA4cB3dD4ca7CefD3368653B7D6FF9BcDFca604'
rebated_fees_usdc: '0.237519'
'400':
@@ -137,7 +137,7 @@ components:
asset_address:
type: string
description: Asset address (e.g. USDC contract)
example: '0x2791Bca1f2de4661ED88A30C99A7a9449Aa84174'
example: '0xC011a7E12a19f7B1f670d46F03B03f3342E82DFB'
maker_address:
type: string
description: Maker's Ethereum address
docs/api-reference/relayer/submit-a-transaction.md
+1 -1
View File
@@ -123,7 +123,7 @@ paths:
$ref: '#/components/schemas/SubmitRequest'
example:
from: '0x6e0c80c90ea6c15917308F820Eac91Ce2724B5b5'
to: '0x2791Bca1f2de4661ED88A30C99A7a9449Aa84174'
to: '0xC011a7E12a19f7B1f670d46F03B03f3342E82DFB'
proxyWallet: '0x6d8c4e9aDF5748Af82Dabe2C6225207770d6B4fa'
data: 0x...
nonce: '60'
docs/api-reference/rewards/get-raw-rewards-for-a-specific-market.md
+1 -1
View File
@@ -69,8 +69,8 @@ paths:
parameters:
- name: condition_id
in: path
description: The condition ID of the market
required: true
description: The condition ID of the market
schema:
type: string
example: '0xbd31dc8a20211944f6b70f31557f1001557b59905b7738480ca09bd4532f84af'
docs/api-reference/trade/get-builder-trades.md
+22 -16
View File
@@ -171,10 +171,11 @@ paths:
example:
error: could not fetch builder trades
security:
- polyBuilderApiKey: []
polyBuilderPassphrase: []
polyBuilderSignature: []
polyBuilderTimestamp: []
- polyApiKey: []
polyAddress: []
polySignature: []
polyPassphrase: []
polyTimestamp: []
components:
schemas:
BuilderTradesResponse:
@@ -342,25 +343,30 @@ components:
description: Last update timestamp
example: '2024-01-01T00:00:00Z'
securitySchemes:
polyBuilderApiKey:
polyApiKey:
type: apiKey
in: header
name: POLY_BUILDER_API_KEY
description: Builder API key for authentication
polyBuilderPassphrase:
name: POLY_API_KEY
description: Your API key
polyAddress:
type: apiKey
in: header
name: POLY_BUILDER_PASSPHRASE
description: Passphrase for builder authentication
polyBuilderSignature:
name: POLY_ADDRESS
description: Ethereum address associated with the API key
polySignature:
type: apiKey
in: header
name: POLY_BUILDER_SIGNATURE
description: HMAC signature for builder authentication
polyBuilderTimestamp:
name: POLY_SIGNATURE
description: HMAC signature of the request
polyPassphrase:
type: apiKey
in: header
name: POLY_BUILDER_TIMESTAMP
description: Unix timestamp for builder authentication
name: POLY_PASSPHRASE
description: API key passphrase
polyTimestamp:
type: apiKey
in: header
name: POLY_TIMESTAMP
description: Unix timestamp of the request
````
docs/api-reference/trade/get-single-order-by-id.md
-24
View File
@@ -123,10 +123,6 @@ paths:
polySignature: []
polyPassphrase: []
polyTimestamp: []
- polyBuilderApiKey: []
polyBuilderPassphrase: []
polyBuilderSignature: []
polyBuilderTimestamp: []
components:
schemas:
OpenOrder:
@@ -257,25 +253,5 @@ components:
in: header
name: POLY_TIMESTAMP
description: Unix timestamp of the request
polyBuilderApiKey:
type: apiKey
in: header
name: POLY_BUILDER_API_KEY
description: Builder API key for authentication
polyBuilderPassphrase:
type: apiKey
in: header
name: POLY_BUILDER_PASSPHRASE
description: Passphrase for builder authentication
polyBuilderSignature:
type: apiKey
in: header
name: POLY_BUILDER_SIGNATURE
description: HMAC signature for builder authentication
polyBuilderTimestamp:
type: apiKey
in: header
name: POLY_BUILDER_TIMESTAMP
description: Unix timestamp for builder authentication
````
docs/api-reference/trade/get-user-orders.md
-24
View File
@@ -160,10 +160,6 @@ paths:
polySignature: []
polyPassphrase: []
polyTimestamp: []
- polyBuilderApiKey: []
polyBuilderPassphrase: []
polyBuilderSignature: []
polyBuilderTimestamp: []
components:
schemas:
OrdersResponse:
@@ -321,25 +317,5 @@ components:
in: header
name: POLY_TIMESTAMP
description: Unix timestamp of the request
polyBuilderApiKey:
type: apiKey
in: header
name: POLY_BUILDER_API_KEY
description: Builder API key for authentication
polyBuilderPassphrase:
type: apiKey
in: header
name: POLY_BUILDER_PASSPHRASE
description: Passphrase for builder authentication
polyBuilderSignature:
type: apiKey
in: header
name: POLY_BUILDER_SIGNATURE
description: HMAC signature for builder authentication
polyBuilderTimestamp:
type: apiKey
in: header
name: POLY_BUILDER_TIMESTAMP
description: Unix timestamp for builder authentication
````
docs/api-reference/trade/post-a-new-order.md
+20 -16
View File
@@ -61,14 +61,15 @@ paths:
order:
maker: '0x1234567890123456789012345678901234567890'
signer: '0x1234567890123456789012345678901234567890'
taker: '0x0000000000000000000000000000000000000000'
tokenId: 0xabc123def456...
makerAmount: '100000000'
takerAmount: '200000000'
side: BUY
expiration: '1735689600'
nonce: '0'
feeRateBps: '30'
timestamp: '1735689600000'
metadata: ''
builder: >-
0x0000000000000000000000000000000000000000000000000000000000000000
signature: 0x1234abcd...
salt: 1234567890
signatureType: 0
@@ -276,14 +277,13 @@ components:
required:
- maker
- signer
- taker
- tokenId
- makerAmount
- takerAmount
- side
- expiration
- nonce
- feeRateBps
- timestamp
- builder
- signature
- salt
- signatureType
@@ -298,10 +298,6 @@ components:
type: string
description: Ethereum address of the signer
example: '0x1234567890123456789012345678901234567890'
taker:
type: string
description: Ethereum address of the taker (0x0 for open orders)
example: '0x0000000000000000000000000000000000000000'
tokenId:
type: string
description: Token ID (asset ID) for the order
@@ -325,14 +321,22 @@ components:
type: string
description: Unix timestamp when the order expires
example: '1735689600'
nonce:
timestamp:
type: string
description: Order nonce
example: '0'
feeRateBps:
description: >-
Unix timestamp in milliseconds when the order was created (used for
order uniqueness)
example: '1735689600000'
metadata:
type: string
description: Fee rate in basis points
example: '30'
description: Reserved for future use
example: ''
builder:
type: string
description: >-
Builder code (bytes32) for integrator attribution. `0x` + 64 hex
chars or empty.
example: '0x0000000000000000000000000000000000000000000000000000000000000000'
signature:
type: string
description: Cryptographic signature of the order
docs/api-reference/trade/post-multiple-orders.md
+24 -19
View File
@@ -68,14 +68,15 @@ paths:
- order:
maker: '0x1234567890123456789012345678901234567890'
signer: '0x1234567890123456789012345678901234567890'
taker: '0x0000000000000000000000000000000000000000'
tokenId: 0xabc123def456...
makerAmount: '100000000'
takerAmount: '200000000'
side: BUY
expiration: '1735689600'
nonce: '0'
feeRateBps: '30'
timestamp: '1735689600000'
metadata: ''
builder: >-
0x0000000000000000000000000000000000000000000000000000000000000000
signature: 0x1234abcd...
salt: 1234567890
signatureType: 0
@@ -85,14 +86,15 @@ paths:
- order:
maker: '0x1234567890123456789012345678901234567890'
signer: '0x1234567890123456789012345678901234567890'
taker: '0x0000000000000000000000000000000000000000'
tokenId: 0xdef456abc789...
makerAmount: '200000000'
takerAmount: '100000000'
side: SELL
expiration: '1735689600'
nonce: '0'
feeRateBps: '30'
timestamp: '1735689600000'
metadata: ''
builder: >-
0x0000000000000000000000000000000000000000000000000000000000000000
signature: 0x5678efgh...
salt: 1234567891
signatureType: 0
@@ -298,14 +300,13 @@ components:
required:
- maker
- signer
- taker
- tokenId
- makerAmount
- takerAmount
- side
- expiration
- nonce
- feeRateBps
- timestamp
- builder
- signature
- salt
- signatureType
@@ -320,10 +321,6 @@ components:
type: string
description: Ethereum address of the signer
example: '0x1234567890123456789012345678901234567890'
taker:
type: string
description: Ethereum address of the taker (0x0 for open orders)
example: '0x0000000000000000000000000000000000000000'
tokenId:
type: string
description: Token ID (asset ID) for the order
@@ -347,14 +344,22 @@ components:
type: string
description: Unix timestamp when the order expires
example: '1735689600'
nonce:
timestamp:
type: string
description: Order nonce
example: '0'
feeRateBps:
description: >-
Unix timestamp in milliseconds when the order was created (used for
order uniqueness)
example: '1735689600000'
metadata:
type: string
description: Fee rate in basis points
example: '30'
description: Reserved for future use
example: ''
builder:
type: string
description: >-
Builder code (bytes32) for integrator attribution. `0x` + 64 hex
chars or empty.
example: '0x0000000000000000000000000000000000000000000000000000000000000000'
signature:
type: string
description: Cryptographic signature of the order
docs/builders/api-keys.md
+56 -74
View File
@@ -2,11 +2,11 @@
> Fetch the complete documentation index at: https://docs.polymarket.com/llms.txt
> Use this file to discover all available pages before exploring further.
# API Keys
# Builder Code
> Create and manage your Builder API credentials
> Your builder code for order attribution
Builder API keys authenticate your application with Polymarket's relayer and enable order attribution. You'll need these credentials to access gasless transactions and track volume.
Your **Builder Code** is a `bytes32` identifier that attributes orders routed through your application to your builder profile. Attach it to every order you submit — no additional authentication is required.
## Accessing Your Builder Profile
@@ -19,36 +19,21 @@ Builder API keys authenticate your application with Polymarket's relayer and ena
<Step title="From Menu">Click your profile image → Select "Builders"</Step>
</Steps>
## Creating API Keys
## Getting Your Builder Code
In the **Builder Keys** section of your profile:
In the **Builder Code** section of your profile, copy the `bytes32` value. It looks like:
1. Click **"+ Create New"** to generate a new API key
2. **Copy all three values immediately** — the secret and passphrase are only shown once
3. Store them securely in your secrets manager or environment variables
```
0x0000000000000000000000000000000000000000000000000000000000000001
```
Each API key includes three components:
Store it in your environment variables or a secrets manager.
| Component | Description | Example |
| ------------ | ------------------------------------------ | ----------------------- |
| `key` | Public identifier for your builder account | `abc123-def456-...` |
| `secret` | Secret key for signing requests | `base64-encoded-secret` |
| `passphrase` | Additional authentication value | `your-passphrase` |
<Warning>
The `secret` and `passphrase` are only displayed once when created. If you
lose them, you'll need to generate a new key.
</Warning>
## Managing Keys
Create separate keys for different environments:
| Environment | Purpose |
| ----------- | ----------------------------- |
| Development | Testing and local development |
| Staging | Pre-production testing |
| Production | Live trading |
<Note>
Builder codes are public identifiers — they appear onchain in the `builder`
field of every order you attribute. Only you control which orders include
your code, so keep it scoped to the apps you own.
</Note>
## Profile Settings
@@ -59,73 +44,68 @@ Your builder profile includes customizable settings:
| **Profile Picture** | Displayed on the [Builder Leaderboard](https://builders.polymarket.com) |
| **Builder Name** | Public name shown on the leaderboard |
| **Builder Address** | Your unique builder identifier (read-only) |
| **Builder Code** | The `bytes32` code you attach to orders |
| **Current Tier** | Your rate limit tier: Unverified, Verified, or Partner |
## Environment Variables
Store your credentials as environment variables:
Store your builder code as an environment variable:
<Tabs>
<Tab title="Bash">
```bash .env theme={null}
POLY_BUILDER_API_KEY=your-api-key
POLY_BUILDER_SECRET=your-secret
POLY_BUILDER_PASSPHRASE=your-passphrase
POLY_BUILDER_CODE=0x0000000000000000000000000000000000000000000000000000000000000001
```
</Tab>
<Tab title="TypeScript">
```typescript theme={null}
import { BuilderApiKeyCreds } from "@polymarket/builder-signing-sdk";
const builderCreds: BuilderApiKeyCreds = {
key: process.env.POLY_BUILDER_API_KEY!,
secret: process.env.POLY_BUILDER_SECRET!,
passphrase: process.env.POLY_BUILDER_PASSPHRASE!,
};
const builderCode = process.env.POLY_BUILDER_CODE!;
```
</Tab>
<Tab title="Python">
```python theme={null}
import os
from py_builder_signing_sdk import BuilderApiKeyCreds
builder_creds = BuilderApiKeyCreds(
key=os.environ["POLY_BUILDER_API_KEY"],
secret=os.environ["POLY_BUILDER_SECRET"],
passphrase=os.environ["POLY_BUILDER_PASSPHRASE"],
)
```
</Tab>
<Tab title="Rust">
```rust theme={null}
use polymarket_client_sdk::auth::Credentials;
let builder_creds = Credentials::new(
std::env::var("POLY_BUILDER_API_KEY")?.parse()?,
std::env::var("POLY_BUILDER_SECRET")?,
std::env::var("POLY_BUILDER_PASSPHRASE")?,
);
builder_code = os.environ["POLY_BUILDER_CODE"]
```
</Tab>
</Tabs>
## Security Best Practices
## Using Your Builder Code
| Practice | Description |
| ----------------------------- | --------------------------------------------------------- |
| **Never commit credentials** | Use `.gitignore` to exclude `.env` files |
| **Use environment variables** | Load credentials from env vars, not hardcoded strings |
| **Use a secrets manager** | AWS Secrets Manager, HashiCorp Vault, etc. for production |
| **Separate environments** | Use different keys for dev, staging, and production |
| **Monitor usage** | Check the leaderboard for unexpected volume changes |
Pass `builderCode` on every order to attribute it to your builder profile:
<Warning>
**Never expose Builder API credentials in client-side code.** Your secret and
passphrase must stay on your server.
</Warning>
<CodeGroup>
```typescript TypeScript theme={null}
const response = await client.createAndPostOrder(
{
tokenID: "0x...",
price: 0.55,
size: 100,
side: Side.BUY,
builderCode: process.env.POLY_BUILDER_CODE!,
},
{ tickSize: "0.01", negRisk: false },
);
```
```python Python theme={null}
response = client.create_and_post_order(
OrderArgs(
token_id="0x...",
price=0.55,
size=100,
side=BUY,
builder_code=os.environ["POLY_BUILDER_CODE"],
),
options={"tick_size": "0.01", "neg_risk": False},
)
```
</CodeGroup>
See [Order Attribution](/trading/orders/attribution) for full details.
## Troubleshooting
@@ -139,10 +119,12 @@ Store your credentials as environment variables:
* [Contact Polymarket](/builders/tiers#contact) to upgrade your tier
</Accordion>
<Accordion title="Lost secret or passphrase">
**Cause:** The secret and passphrase are only shown once when created.
<Accordion title="Builder code not found">
**Cause:** You haven't created a builder profile yet.
**Solution:** Create a new API key. You cannot recover the original values.
**Solution:** Go to
[polymarket.com/settings?tab=builder](https://polymarket.com/settings?tab=builder)
and set up your profile to get a builder code.
</Accordion>
</AccordionGroup>
@@ -150,7 +132,7 @@ Store your credentials as environment variables:
<CardGroup cols={2}>
<Card title="Attribute Orders" icon="tag" href="/trading/orders/attribution">
Configure your client to credit trades to your account.
Attach your builder code to orders for volume credit.
</Card>
<Card title="Understand Tiers" icon="layer-group" href="/builders/tiers">
docs/builders/overview.md
+14 -20
View File
@@ -41,12 +41,13 @@ A **builder** is a person, group, or organization that routes orders from users
User places an order through your application.
</Step>
<Step title="Sign Request">
Your app signs the request with Builder API credentials.
<Step title="Attach Builder Code">
Your app adds your `builderCode` to the order struct.
</Step>
<Step title="Submit to CLOB">
Order is submitted to Polymarket's CLOB with attribution headers.
Order is submitted to Polymarket's CLOB — the builder code is serialized
onchain as part of the signed order.
</Step>
<Step title="Trade Execution">
@@ -54,7 +55,8 @@ A **builder** is a person, group, or organization that routes orders from users
</Step>
<Step title="Volume Attribution">
Volume is credited to your builder account.
Volume is credited to your builder account for every matched trade where
your code is attached.
</Step>
</Steps>
@@ -64,12 +66,12 @@ A **builder** is a person, group, or organization that routes orders from users
<Step title="Create Builder Profile">
Go to
[polymarket.com/settings?tab=builder](https://polymarket.com/settings?tab=builder)
and generate your API keys.
and copy your builder code.
</Step>
<Step title="Configure Attribution">
Set up your CLOB client to include builder authentication headers with every
order.
<Step title="Attach Your Builder Code">
Pass `builderCode` on every order you submit — see [Order
Attribution](/trading/orders/attribution).
</Step>
<Step title="Enable Gasless Transactions">
@@ -86,11 +88,11 @@ A **builder** is a person, group, or organization that routes orders from users
## SDKs and Libraries
<CardGroup cols={2}>
<Card title="CLOB Client (TypeScript)" icon="github" href="https://github.com/Polymarket/clob-client">
<Card title="CLOB Client (TypeScript)" icon="github" href="https://github.com/Polymarket/clob-client-v2">
Place orders with builder attribution
</Card>
<Card title="CLOB Client (Python)" icon="github" href="https://github.com/Polymarket/py-clob-client">
<Card title="CLOB Client (Python)" icon="github" href="https://github.com/Polymarket/py-clob-client-v2">
Place orders with builder attribution
</Card>
@@ -102,17 +104,9 @@ A **builder** is a person, group, or organization that routes orders from users
Gasless onchain transactions
</Card>
<Card title="CLOB Client (Rust)" icon="github" href="https://github.com/Polymarket/rs-clob-client">
<Card title="CLOB Client (Rust)" icon="github" href="https://github.com/Polymarket/rs-clob-client-v2">
Place orders with builder attribution
</Card>
<Card title="Signing SDK (TypeScript)" icon="github" href="https://github.com/Polymarket/builder-signing-sdk">
Sign builder authentication headers
</Card>
<Card title="Signing SDK (Python)" icon="github" href="https://github.com/Polymarket/py-builder-signing-sdk">
Sign builder authentication headers
</Card>
</CardGroup>
## Examples
@@ -177,7 +171,7 @@ For existing Magic Link users from Polymarket.com:
<Tab title="Wallet Operations">
* Safe wallet deployment via Relayer
* Batch token approvals (USDC.e + outcome tokens)
* Batch token approvals (pUSD + outcome tokens)
* CTF operations (split, merge, redeem)
* Transaction monitoring
</Tab>
docs/changelog/changelog.md
-200
View File
@@ -1,200 +0,0 @@
> ## 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 Changelog
> Welcome to the Polymarket Changelog. Here you will find any important changes to Polymarket, including but not limited to CLOB, API, UI and Mobile Applications.
<Update label="Apr 17, 2026" description="CLOB V2: upgrades go live April 22 at ~11:00 UTC, with ~1 hour of downtime">
Polymarket is shipping a coordinated upgrade: **new Exchange contracts, a rewritten CLOB backend, and a new collateral token (pUSD)**.
**Exchange upgrades go live April 22, 2026 at \~11:00 UTC with \~1 hour of downtime.** All integrations must migrate to the V2 SDK before the cutover — there will be no backward compatibility after go-live.
**Full walkthrough:** [Migrating to CLOB V2](/v2-migration). Follow [Discord](https://discord.gg/polymarket), Telegram, and [status.polymarket.com](https://status.polymarket.com) for the exact start time.
**Test against V2 now:** point your client at `https://clob-v2.polymarket.com`. On April 22, V2 takes over `https://clob.polymarket.com`, so no base-URL change is needed after the cutover.
**What's changing**
* New Exchange contracts (CTF Exchange V2 + Neg Risk CTF Exchange V2)
* **pUSD** replaces USDC.e as the collateral token (standard ERC-20 on Polygon, backed by USDC, backing enforced onchain)
* Order struct: `nonce`, `feeRateBps`, `taker` removed — `timestamp` (ms), `metadata`, `builder` added
* Fees are now set at match time — no more `feeRateBps` on orders
* Builder attribution is native via `builderCode` on orders (no more `builder-signing-sdk`)
* EIP-712 Exchange domain version bumps from `"1"` to `"2"` (ClobAuth stays at `"1"`)
**What you need to do**
* Install the V2 SDK — [`@polymarket/clob-client-v2`](https://www.npmjs.com/package/@polymarket/clob-client-v2) or [`py-clob-client-v2`](https://pypi.org/project/py-clob-client-v2/) — and remove the legacy `clob-client` / `py-clob-client` packages
* Update constructor from positional args to options object; rename `chainId` → `chain`
* Remove `feeRateBps`, `nonce`, and `taker` from your order creation code
* If you're a builder, copy your code from [Settings → Builder](https://polymarket.com/settings?tab=builder) and attach it to orders
* If you sign orders without the SDK, update the `verifyingContract` and the signed Order fields — see [For API users](/v2-migration#for-api-users)
* Plan for all open orders to be wiped at cutover
**During the window:** Trading will be paused for \~1 hour on April 22 starting around 11:00 UTC. The SDK's hot-swap mechanism will auto-refresh the client when V2 goes live — no manual action needed if you're on the latest SDK.
</Update>
<Update label="Apr 13, 2026" description="Bridge API: added support link for bridging issues">
* **Support contact**: Added a link to [our Bridge API provider's support](https://intercom.help/funxyz/en/articles/10732578-contact-us) (Fun.xyz) for failed, stuck, or compliance-held bridge transactions. See [Deposit Status](/trading/bridge/status).
</Update>
<Update label="Apr 10, 2026" description="New keyset pagination endpoints for markets and events">
* **New endpoints**: Added `GET /markets/keyset` and `GET /events/keyset` for cursor-based pagination, replacing offset-based `GET /markets` and `GET /events`.
* **How it works**: These use an opaque `after_cursor`/`next_cursor` token instead of `offset`, providing stable and efficient paging through large result sets. Same filters, same response shape per item — the only differences are the wrapper response (`{ "markets": [...], "next_cursor": "..." }`) and the rejection of `offset`.
* **Migration**: The existing `GET /markets` and `GET /events` endpoints remain available but will be deprecated in a future release. New integrations should use the keyset variants.
</Update>
<Update label="Apr 9, 2026" description="GET /markets: closed defaults to false">
* **`closed` default change**: The `closed` query parameter on `GET /markets` now defaults to `false`. Closed markets are excluded from results unless you explicitly pass `closed=true`.
</Update>
<Update label="Mar 31, 2026" description="REST API Fee Fields Update">
* **Fee calculation source**: Fees should now be calculated using the `feeSchedule` object within a market.
</Update>
<Update label="Mar 30, 2026" description="Fee Structure V2">
* **New fee categories**: Fees now apply to Crypto, Sports, Finance, Politics, Economics, Culture, Weather, Tech, Mentions, and Other / General markets with updated rates per category. Geopolitical and world events markets remain fee-free.
* **Updated documentation**: [Fees](/trading/fees) and [Maker Rebates Program](/market-makers/maker-rebates).
</Update>
<Update label="Mar 17, 2026" description="March Madness: $2M+ in Liquidity Rewards">
* **March Madness Liquidity Rewards**: Adding \$2M+ in liquidity rewards to both live and pregame markets.
* **How it works**: Liquidity rewards are payments for placing competitive bids. Rewards are paid out based on the size of your orders, how close they are to the midpoint, and how consistently they are quoted relative to other liquidity providers. Orders must be active on the book for a minimum of **3.5 seconds** to be eligible.
**Daily reward rates for markets (subject to change):**
**48 hours before GameStartTime:**
* \$7.5k for full game ML market
* \$500 for 5 other markets (most recently created full game spread, most recently created full game total, 1st half ML, most recently created 1st half spread, most recently created 1st half total)
**From game live to game completion (note: rewards are expressed in daily rates):**
* \$60k for full game ML
* \$4k for most recently created full game spread and most recently created full game total
**From game live to halftime (note: rewards are expressed in daily rates):**
* \$8k for 1st half ML, most recently created 1st half spread, most recently created 1st half total
* **Markets**: [Browse March Madness markets](https://polymarket.com/sports/cbb/games)
* **More details**: [Liquidity Rewards documentation](/market-makers/liquidity-rewards#liquidity-rewards)
</Update>
<Update label="Mar 1, 2026" description="Taker Fees & Maker Rebates: All Crypto Markets">
* **Crypto market fees expansion**: Starting March 6, 2026, taker fees and maker rebates extend to all crypto markets including 1H, 4H, daily, and weekly. The same fee structure as existing crypto markets applies. Only new markets created after March 6 are affected.
* **Updated documentation**: [Fees](/trading/fees) and [Maker Rebates Program](/market-makers/maker-rebates) updated to reflect all crypto market coverage.
</Update>
<Update label="Feb 12, 2026" description="5-Minute Crypto Markets">
* **5-minute crypto markets**: Launched with taker fees enabled. Fees follow the same curve as 15-minute crypto markets, peaking at 1.56% at 50% probability.
* **Maker Rebates**: Liquidity providers earn daily USDC rebates funded by taker fees, same as 15-minute crypto markets.
</Update>
<Update label="Feb 11, 2026" description="Taker Fees & Maker Rebates: NCAAB and Serie A">
* **Sports market fees**: Taker fees to be enabled on NCAAB (college basketball) and Serie A markets on February 18, 2026.
* **Per-market rebate calculation**: Rebates are now calculated per market, makers only compete with other makers in the same market.
* **Updated documentation**: [Maker Rebates Program](/market-makers/maker-rebates) updated with sports fee tables and parameters.
</Update>
<Update label="Jan 28, 2026" description="Bridge API: Withdrawal Endpoint">
* **Withdrawal Endpoint**: New `/withdraw` endpoint to bridge USDC.e from Polymarket to any supported chain and token.
* **Multi-chain withdrawals**: Withdraw to EVM chains (Ethereum, Arbitrum, Base, etc.), Solana, and Bitcoin.
* **Updated documentation**: Bridge API docs updated to reflect deposit and withdrawal functionality.
</Update>
<Update label="Jan 16, 2026" description="Docs Update: RTDS documentation">
* RTDS docs updated to reflect RTDS supports **comments** and **crypto prices** only.
* Removed legacy CLOB references and `clob_auth` from RTDS docs.
</Update>
<Update label="Jan 16, 2026" description="Docs Update: Maker Rebates Program">
* **Maker Rebates Program**: Updated funding schedule with distribution method (volume-weighted vs fee-curve weighted).
* **Fee-curve weighted rebates**: Documented fee-equivalent formula and rebate calculation.
* **FAQ**: Clarified how rebates are calculated during fee-curve weighted periods.
</Update>
<Update label="Jan 6, 2026" description="New API Features">
* **Releases**: Daily Releases timing
* **HeartBeats API**: HeartBeats endpoint for monitoring connection status and canceling orders
* **Post Only Orders**: Orders that are rejected if they would immediately match against an existing order
</Update>
<Update label="Jan 5, 2026" description="Taker Fees & Maker Rebates">
* **Taker Fees**: Enabled on 15-minute crypto markets. Fees vary by price and peak at 1.56% at 50% probability.
* **Maker Rebates**: Daily USDC rebates paid to liquidity providers, funded by taker fees.
</Update>
<Update label="Sept 24, 2025" description="Polymarket Real-Time Data Socket (RTDS) official release">
* **Crypto Price Feeds**: Access real-time cryptocurrency prices from two sources (Binance & Chainlink)
* **Comment Streaming**: Real-time updates for comment events including new comments, replies, and reactions
* **Dynamic Subscriptions**: Add, remove, and modify subscriptions without reconnecting
* **TypeScript Client**: Official TypeScript client available at [real-time-data-client](https://github.com/Polymarket/real-time-data-client)
For complete documentation, see [Market Data](/market-data/overview).
</Update>
<Update label="September 15, 2025" description="WSS price_change event update">
* There has been a significant change to the structure of the price change message. This update will be applied at 11PM UTC September 15, 2025. We apologize for the short notice
* Please see the [Market Channel](/market-data/websocket/market-channel) for details.
</Update>
<Update label="August 26, 2025" description="Updated /trades and /activity endpoints">
* Reduced maximum values for query parameters on Data-API /trades and /activity:
* `limit`: 500
* `offset`: 1,000
</Update>
<Update label="August 21, 2025" description="Batch Orders Increase">
* The batch orders limit has been increased from 5 -> 15. Read more about the batch orders functionality [here](/trading/orders/create).
</Update>
<Update label="July 23, 2025" description="Get Book(s) update">
* We’re adding new fields to the `get-book` and `get-books` CLOB endpoints to include key market metadata that previously required separate queries.
* `min_order_size`
* type: string
* description: Minimum price increment.
* `neg_risk`
* type: boolean
* description: Boolean indicating whether the market is neg\_risk.
* `tick_size`
* type: string
* description: Minimum price increment.
</Update>
<Update label="June 3, 2025" description="New Batch Orders Endpoint">
* We’re excited to roll out a highly requested feature: **order batching**. With this new endpoint, users can now submit up to five trades in a single request. To help you get started, we’ve included sample code demonstrating how to use it. Please see [Create Orders](/trading/orders/create) for more details.
</Update>
<Update label="June 3, 2025" description="Change to /data/trades">
* We're adding a new `side` field to the `MakerOrder` portion of the trade object. This field will indicate whether the maker order is a `buy` or `sell`, helping to clarify trade events where the maker side was previously ambiguous. For more details, refer to the MakerOrder object on the [Orders](/trading/orders/cancel) page.
</Update>
<Update label="May 28, 2025" description="Websocket Changes">
* The 100 token subscription limit has been removed for the Markets channel. You can now subscribe to as many token IDs as needed for your use case.
* New Subscribe Field `initial_dump`
* Optional field to indicate whether you want to receive the initial order book state when subscribing to a token or list of tokens.
* `default: true`
</Update>
<Update label="May 28, 2025" description="New FAK Order Type">
We’re excited to introduce a new order type soon to be available to all users: Fill and Kill (FAK). FAK orders behave similarly to the well-known Fill or Kill (FOK) orders, but with a key difference:
* FAK will fill as many shares as possible immediately at your specified price, and any remaining unfilled portion will be canceled.
* Unlike FOK, which requires the entire order to fill instantly or be canceled, FAK is more flexible and aims to capture partial fills if possible.
</Update>
<Update label="May 15, 2025" description="Increased API Rate Limits">
All API users will enjoy increased rate limits for the CLOB endpoints.
* CLOB - /books (website) (300req - 10s / Throttle requests over the maximum configured rate)
* CLOB - /books (50 req - 10s / Throttle requests over the maximum configured rate)
* CLOB - /price (100req - 10s / Throttle requests over the maximum configured rate)
* CLOB markets/0x (50req / 10s - Throttle requests over the maximum configured rate)
* CLOB POST /order - 500 every 10s (50/s) - (BURST) - Throttle requests over the maximum configured rate
* CLOB POST /order - 3000 every 10 minutes (5/s) - Throttle requests over the maximum configured rate
* CLOB DELETE /order - 500 every 10s (50/s) - (BURST) - Throttle requests over the maximum configured rate
* DELETE /order - 3000 every 10 minutes (5/s) - Throttle requests over the maximum configured rate
</Update>
docs/concepts/order-lifecycle.md
+4 -7
View File
@@ -46,7 +46,7 @@ Post-only orders will only rest on the book. If a post-only order would match im
* Side (buy or sell)
* Price and size
* Expiration time
* Nonce (for replay protection)
* Timestamp (in milliseconds, used for order uniqueness)
You sign this order with your private key, creating an EIP712 signature.
</Step>
@@ -75,7 +75,7 @@ Post-only orders will only rest on the book. If a post-only order would match im
* Verifies both signatures
* Transfers tokens from seller to buyer
* Transfers USDC.e from buyer to seller
* Transfers pUSD from buyer to seller
Settlement is **atomic**—either the entire trade succeeds or nothing happens.
</Step>
@@ -119,10 +119,7 @@ Price improvement always benefits the taker. If you place a buy order at `$0.55`
## Cancellation
You can cancel orders at any time before they're matched:
* **Via API** — Cancel through the CLOB API (instant)
* **Onchain** — Cancel directly on the Exchange contract (fallback if API is unavailable)
You can cancel orders at any time before they're matched via the CLOB API.
Partial fills cannot be cancelled—only the unfilled portion of an order can be cancelled.
@@ -132,7 +129,7 @@ Before placing orders, ensure:
| Requirement | Description |
| ------------------- | -------------------------------------------------- |
| **Balance** | Sufficient USDC.e (for buys) or tokens (for sells) |
| **Balance** | Sufficient pUSD (for buys) or tokens (for sells) |
| **Allowance** | Approve the Exchange contract to spend your assets |
| **API Credentials** | Valid API key for authenticated endpoints |
docs/concepts/positions-tokens.md
+7 -7
View File
@@ -27,15 +27,15 @@ Tokens are **ERC1155** assets on Polygon, using the [Gnosis Conditional Token Fr
<Note>
Outcome tokens are always fully backed. Every Yes/No pair in existence is
backed by exactly `$1` of USDC.e collateral locked in the CTF contract.
backed by exactly `$1` of pUSD collateral locked in the CTF contract.
</Note>
### Split
Convert USDC.e into outcome tokens. Splitting \$1 creates 1 Yes token and 1 No token.
Convert pUSD into outcome tokens. Splitting \$1 creates 1 Yes token and 1 No token.
```
$100 USDC.e → 100 Yes tokens + 100 No tokens
$100 pUSD → 100 Yes tokens + 100 No tokens
```
Use this when you want to:
@@ -54,10 +54,10 @@ You can sell your position at any time before resolution.
### Merge
Convert a complete set of tokens back into USDC.e. Merging requires equal amounts of Yes and No tokens.
Convert a complete set of tokens back into pUSD. Merging requires equal amounts of Yes and No tokens.
```
100 Yes tokens + 100 No tokens → $100 USDC.e
100 Yes tokens + 100 No tokens → $100 pUSD
```
Use this when you want to:
@@ -67,7 +67,7 @@ Use this when you want to:
### Redeem
After a market resolves, exchange winning tokens for USDC.e.
After a market resolves, exchange winning tokens for pUSD.
| Outcome | Yes tokens | No tokens |
| ------------------- | -------------- | -------------- |
@@ -75,7 +75,7 @@ After a market resolves, exchange winning tokens for USDC.e.
| Event doesn't occur | Worth \$0 | Worth \$1 each |
```
100 winning tokens → $100 USDC.e
100 winning tokens → $100 pUSD
```
### Position Value
docs/concepts/resolution.md
+3 -3
View File
@@ -34,7 +34,7 @@ Every market has pre-defined resolution rules that specify:
Anyone can propose a resolution by:
1. Selecting the winning outcome
2. Posting a bond (typically \$750 USDC.e)
2. Posting a bond (typically \$750 pUSD)
3. Submitting the proposal to the UMA Oracle
If the proposal is correct and undisputed, the proposer receives their bond back plus a reward.
@@ -89,10 +89,10 @@ Once a market resolves:
### Redeeming Tokens
After resolution, call the `redeemPositions` function on the CTF contract to exchange winning tokens for USDC.e. The contract burns your tokens and returns the corresponding collateral.
After resolution, call the `redeemPositions` function on the CTF contract to exchange winning tokens for pUSD. The contract burns your tokens and returns the corresponding collateral.
```
100 winning tokens → $100 USDC.e
100 winning tokens → $100 pUSD
```
## Clarifications
docs/index.md
+3 -3
View File
@@ -67,9 +67,9 @@ export const IconCard = ({ icon, title, description, href, color }) => {
<CodeGroup>
```typescript TypeScript theme={null}
import { ClobClient, Side } from "@polymarket/clob-client";
import { ClobClient, Side } from "@polymarket/clob-client-v2";
const client = new ClobClient(host, chainId, signer, creds);
const client = new ClobClient({ host, chain: chainId, signer, creds });
const order = await client.createAndPostOrder(
{ tokenID, price: 0.50, size: 10, side: Side.BUY },
@@ -81,7 +81,7 @@ export const IconCard = ({ icon, title, description, href, color }) => {
from py_clob_client.client import ClobClient
from py_clob_client.order_builder.constants import BUY
client = ClobClient(host, key=key, chain_id=chain_id, creds=creds)
client = ClobClient(host, key=key, chain=chain, creds=creds)
order = client.create_and_post_order(
OrderArgs(token_id=token_id, price=0.50, size=10, side=BUY),
options={"tick_size": "0.01", "neg_risk": False}
docs/market-makers/getting-started.md
+30 -29
View File
@@ -6,16 +6,16 @@
> One-time setup for market making on Polymarket
Before you can start market making, you need to complete these one-time setup steps — deposit USDC.e to Polygon, deploy a wallet, approve tokens for trading, and generate API credentials.
Before you can start market making, you need to complete these one-time setup steps — deposit pUSD to Polygon, deploy a wallet, approve tokens for trading, and generate API credentials.
<Steps>
<Step title="Deposit USDC.e">
Market makers need USDC.e on Polygon to fund their trading operations.
<Step title="Deposit pUSD">
Market makers need pUSD on Polygon to fund their trading operations.
| Method | Best For | Documentation |
| ----------------------- | ------------------------------------ | ---------------------------------------------------- |
| Bridge API | Automated deposits from other chains | [Bridge Deposit](/trading/bridge/deposit) |
| Direct Polygon transfer | Already have USDC.e on Polygon | N/A |
| Direct Polygon transfer | Already have pUSD on Polygon | N/A |
| Cross-chain bridge | Large deposits from Ethereum | [Supported Assets](/trading/bridge/supported-assets) |
### Using the Bridge API
@@ -54,13 +54,14 @@ Before you can start market making, you need to complete these one-time setup st
```typescript TypeScript theme={null}
import { RelayClient, RelayerTxType } from "@polymarket/builder-relayer-client";
const client = new RelayClient(
"https://relayer-v2.polymarket.com/",
137, // Polygon mainnet
const client = new RelayClient({
host: "https://relayer-v2.polymarket.com/",
chain: 137,
signer,
builderConfig,
RelayerTxType.SAFE,
);
relayerApiKey: process.env.RELAYER_API_KEY!,
relayerApiKeyAddress: process.env.RELAYER_API_KEY_ADDRESS!,
txType: RelayerTxType.SAFE,
});
// Deploy the Safe wallet
const response = await client.deploy();
@@ -71,7 +72,7 @@ Before you can start market making, you need to complete these one-time setup st
```python Python theme={null}
from py_builder_relayer_client.client import RelayClient
# client initialized with builder_config
# client initialized with Relayer API Key credentials (see Gasless Transactions)
# Deploy the Safe wallet
response = client.deploy()
@@ -91,20 +92,20 @@ Before you can start market making, you need to complete these one-time setup st
### Required Approvals
| Token | Spender | Purpose |
| -------------------- | --------------------- | -------------------------------- |
| USDC.e | CTF Contract | Split USDC.e into outcome tokens |
| CTF (outcome tokens) | CTF Exchange | Trade outcome tokens |
| CTF (outcome tokens) | Neg Risk CTF Exchange | Trade neg-risk market tokens |
| Token | Spender | Purpose |
| -------------------- | --------------------- | ------------------------------ |
| pUSD | CTF Contract | Split pUSD into outcome tokens |
| CTF (outcome tokens) | CTF Exchange | Trade outcome tokens |
| CTF (outcome tokens) | Neg Risk CTF Exchange | Trade neg-risk market tokens |
### Contract Addresses
```typescript theme={null}
const ADDRESSES = {
USDCe: "0x2791Bca1f2de4661ED88A30C99A7a9449Aa84174",
pUSD: "0xC011a7E12a19f7B1f670d46F03B03f3342E82DFB",
CTF: "0x4D97DCd97eC945f40cF65F87097ACe5EA0476045",
CTF_EXCHANGE: "0x4bFb41d5B3570DeFd03C39a9A4D8dE6Bd8B8982E",
NEG_RISK_CTF_EXCHANGE: "0xC5d563A36AE78145C45a50134d48A1215220f80a",
CTF_EXCHANGE: "0xE111180000d2663C0091e4f400237545B87B996B",
NEG_RISK_CTF_EXCHANGE: "0xe2222d279d744050d28e00520010520000310F59",
NEG_RISK_ADAPTER: "0xd91E80cF2E7be2e162c6513ceD06f1dD0dA35296",
};
```
@@ -120,9 +121,9 @@ Before you can start market making, you need to complete these one-time setup st
"function approve(address spender, uint256 amount) returns (bool)",
]);
// Approve USDCe for CTF contract
// Approve pUSD for CTF contract
const approveTx = {
to: ADDRESSES.USDCe,
to: ADDRESSES.pUSD,
data: erc20Interface.encodeFunctionData("approve", [
ADDRESSES.CTF,
ethers.constants.MaxUint256,
@@ -130,21 +131,21 @@ Before you can start market making, you need to complete these one-time setup st
value: "0",
};
const response = await client.execute([approveTx], "Approve USDCe for CTF");
const response = await client.execute([approveTx], "Approve pUSD for CTF");
await response.wait();
```
```python Python theme={null}
from web3 import Web3
USDC = "0x2791Bca1f2de4661ED88A30C99A7a9449Aa84174"
pUSD = "0xC011a7E12a19f7B1f670d46F03B03f3342E82DFB"
CTF = "0x4D97DCd97eC945f40cF65F87097ACe5EA0476045"
MAX_UINT256 = 2**256 - 1
approve_tx = {
"to": USDC,
"to": pUSD,
"data": Web3().eth.contract(
address=USDC,
address=pUSD,
abi=[{
"name": "approve",
"type": "function",
@@ -158,7 +159,7 @@ Before you can start market making, you need to complete these one-time setup st
"value": "0"
}
response = client.execute([approve_tx], "Approve USDC for CTF")
response = client.execute([approve_tx], "Approve pUSD for CTF")
response.wait()
```
</CodeGroup>
@@ -169,9 +170,9 @@ Before you can start market making, you need to complete these one-time setup st
<CodeGroup>
```typescript TypeScript theme={null}
import { ClobClient } from "@polymarket/clob-client";
import { ClobClient } from "@polymarket/clob-client-v2";
const client = new ClobClient("https://clob.polymarket.com", 137, signer);
const client = new ClobClient({ host: "https://clob.polymarket.com", chain: 137, signer });
// Derive API credentials from your wallet
const credentials = await client.createOrDeriveApiKey();
@@ -186,7 +187,7 @@ Before you can start market making, you need to complete these one-time setup st
private_key = os.getenv("PRIVATE_KEY")
temp_client = ClobClient("https://clob.polymarket.com", key=private_key, chain_id=137)
temp_client = ClobClient("https://clob.polymarket.com", key=private_key, chain=137)
credentials = temp_client.create_or_derive_api_creds()
```
docs/market-makers/inventory.md
+38 -38
View File
@@ -6,7 +6,7 @@
> Managing outcome token inventory for market making
Market makers need outcome tokens on both sides to quote a market. The three core inventory operations are **splitting** USDC.e into YES/NO token pairs, **merging** pairs back into USDC.e, and **redeeming** winning tokens after resolution — all executed gaslessly through the Relayer Client.
Market makers need outcome tokens on both sides to quote a market. The three core inventory operations are **splitting** pUSD into YES/NO token pairs, **merging** pairs back into pUSD, and **redeeming** winning tokens after resolution — all executed gaslessly through the Relayer Client.
<Info>
For a full breakdown of how the Conditional Token Framework works, see [CTF
@@ -16,9 +16,9 @@ Market makers need outcome tokens on both sides to quote a market. The three cor
***
## Splitting USDC.e into Tokens
## Splitting pUSD into Tokens
Split converts USDC.e into equal amounts of YES and NO tokens — creating the inventory you need to quote both sides of a market.
Split converts pUSD into equal amounts of YES and NO tokens — creating the inventory you need to quote both sides of a market.
<CodeGroup>
```typescript TypeScript theme={null}
@@ -27,19 +27,19 @@ Split converts USDC.e into equal amounts of YES and NO tokens — creating the i
import { RelayClient, Transaction } from "@polymarket/builder-relayer-client";
const CTF_ADDRESS = "0x4D97DCd97eC945f40cF65F87097ACe5EA0476045";
const USDCe_ADDRESS = "0x2791Bca1f2de4661ED88A30C99A7a9449Aa84174";
const pUSD_ADDRESS = "0xC011a7E12a19f7B1f670d46F03B03f3342E82DFB";
const ctfInterface = new Interface([
"function splitPosition(address collateralToken, bytes32 parentCollectionId, bytes32 conditionId, uint[] partition, uint amount)",
]);
// Split $1000 USDCe into YES/NO tokens
const amount = ethers.utils.parseUnits("1000", 6); // USDCe has 6 decimals
// Split $1000 pUSD into YES/NO tokens
const amount = ethers.utils.parseUnits("1000", 6); // pUSD has 6 decimals
const splitTx: Transaction = {
to: CTF_ADDRESS,
data: ctfInterface.encodeFunctionData("splitPosition", [
USDCe_ADDRESS, // collateralToken
pUSD_ADDRESS, // collateralToken
ethers.constants.HashZero, // parentCollectionId (always zero for Polymarket)
conditionId, // conditionId from market
[1, 2], // partition: [YES, NO]
@@ -48,7 +48,7 @@ Split converts USDC.e into equal amounts of YES and NO tokens — creating the i
value: "0",
};
const response = await client.execute([splitTx], "Split USDCe into tokens");
const response = await client.execute([splitTx], "Split pUSD into tokens");
const result = await response.wait();
console.log("Split completed:", result?.transactionHash);
```
@@ -57,7 +57,7 @@ Split converts USDC.e into equal amounts of YES and NO tokens — creating the i
from web3 import Web3
CTF_ADDRESS = "0x4D97DCd97eC945f40cF65F87097ACe5EA0476045"
USDCe_ADDRESS = "0x2791Bca1f2de4661ED88A30C99A7a9449Aa84174"
pUSD_ADDRESS = "0xC011a7E12a19f7B1f670d46F03B03f3342E82DFB"
ctf_abi = [{
"name": "splitPosition",
@@ -72,8 +72,8 @@ Split converts USDC.e into equal amounts of YES and NO tokens — creating the i
"outputs": []
}]
# Split $1000 USDCe into YES/NO tokens
amount = 1000 * 10**6 # USDCe has 6 decimals
# Split $1000 pUSD into YES/NO tokens
amount = 1000 * 10**6 # pUSD has 6 decimals
split_tx = {
"to": CTF_ADDRESS,
@@ -82,7 +82,7 @@ Split converts USDC.e into equal amounts of YES and NO tokens — creating the i
).encode_abi(
abi_element_identifier="splitPosition",
args=[
USDCe_ADDRESS,
pUSD_ADDRESS,
bytes(32), # parentCollectionId (always zero)
condition_id, # conditionId from market
[1, 2], # partition: [YES, NO]
@@ -92,7 +92,7 @@ Split converts USDC.e into equal amounts of YES and NO tokens — creating the i
"value": "0"
}
response = client.execute([split_tx], "Split USDCe into tokens")
response = client.execute([split_tx], "Split pUSD into tokens")
response.wait()
```
@@ -103,25 +103,25 @@ Split converts USDC.e into equal amounts of YES and NO tokens — creating the i
let ctf_client = CtfClient::new(provider, 137)?;
// Split $1000 USDCe into YES/NO tokens
// Split $1000 pUSD into YES/NO tokens
let request = SplitPositionRequest::builder()
.collateral_token(address!("0x2791Bca1f2de4661ED88A30C99A7a9449Aa84174"))
.collateral_token(address!("0xC011a7E12a19f7B1f670d46F03B03f3342E82DFB"))
.condition_id(condition_id)
.partition(vec![U256::from(1), U256::from(2)])
.amount(U256::from(1000_000_000u64)) // 1000 USDCe (6 decimals)
.amount(U256::from(1000_000_000u64)) // 1000 pUSD (6 decimals)
.build();
let result = ctf_client.split_position(&request).await?;
println!("Split tx: {:?}", result.transaction_hash);
```
</CodeGroup>
After splitting 1000 USDC.e, you receive 1000 YES tokens and 1000 NO tokens. Your USDC.e balance decreases by 1000.
After splitting 1000 pUSD, you receive 1000 YES tokens and 1000 NO tokens. Your pUSD balance decreases by 1000.
***
## Merging Tokens to USDC.e
## Merging Tokens to pUSD
Merge converts equal amounts of YES and NO tokens back into USDC.e — useful for reducing exposure, exiting a market, or freeing up capital.
Merge converts equal amounts of YES and NO tokens back into pUSD — useful for reducing exposure, exiting a market, or freeing up capital.
<CodeGroup>
```typescript TypeScript theme={null}
@@ -129,13 +129,13 @@ Merge converts equal amounts of YES and NO tokens back into USDC.e — useful fo
"function mergePositions(address collateralToken, bytes32 parentCollectionId, bytes32 conditionId, uint[] partition, uint amount)",
]);
// Merge 500 YES + 500 NO back to 500 USDCe
// Merge 500 YES + 500 NO back to 500 pUSD
const amount = ethers.utils.parseUnits("500", 6);
const mergeTx: Transaction = {
to: CTF_ADDRESS,
data: ctfInterface.encodeFunctionData("mergePositions", [
USDCe_ADDRESS,
pUSD_ADDRESS,
ethers.constants.HashZero,
conditionId,
[1, 2],
@@ -144,7 +144,7 @@ Merge converts equal amounts of YES and NO tokens back into USDC.e — useful fo
value: "0",
};
const response = await client.execute([mergeTx], "Merge tokens to USDCe");
const response = await client.execute([mergeTx], "Merge tokens to pUSD");
await response.wait();
```
@@ -162,7 +162,7 @@ Merge converts equal amounts of YES and NO tokens back into USDC.e — useful fo
"outputs": []
}]
# Merge 500 YES + 500 NO back to 500 USDCe
# Merge 500 YES + 500 NO back to 500 pUSD
amount = 500 * 10**6
merge_tx = {
@@ -171,36 +171,36 @@ Merge converts equal amounts of YES and NO tokens back into USDC.e — useful fo
address=CTF_ADDRESS, abi=merge_abi
).encode_abi(
abi_element_identifier="mergePositions",
args=[USDCe_ADDRESS, bytes(32), condition_id, [1, 2], amount]
args=[pUSD_ADDRESS, bytes(32), condition_id, [1, 2], amount]
),
"value": "0"
}
response = client.execute([merge_tx], "Merge tokens to USDCe")
response = client.execute([merge_tx], "Merge tokens to pUSD")
response.wait()
```
```rust Rust theme={null}
use polymarket_client_sdk::ctf::types::MergePositionsRequest;
// Merge 500 YES + 500 NO back to 500 USDCe
// Merge 500 YES + 500 NO back to 500 pUSD
let request = MergePositionsRequest::builder()
.collateral_token(address!("0x2791Bca1f2de4661ED88A30C99A7a9449Aa84174"))
.collateral_token(address!("0xC011a7E12a19f7B1f670d46F03B03f3342E82DFB"))
.condition_id(condition_id)
.partition(vec![U256::from(1), U256::from(2)])
.amount(U256::from(500_000_000u64)) // 500 USDCe (6 decimals)
.amount(U256::from(500_000_000u64)) // 500 pUSD (6 decimals)
.build();
let result = ctf_client.merge_positions(&request).await?;
```
</CodeGroup>
After merging 500 of each, your YES and NO balances decrease by 500 and your USDC.e balance increases by 500.
After merging 500 of each, your YES and NO balances decrease by 500 and your pUSD balance increases by 500.
***
## Redeeming After Resolution
Once a market resolves, redeem winning tokens for USDC.e. Each winning token is worth $1 — losing tokens redeem for $0.
Once a market resolves, redeem winning tokens for pUSD. Each winning token is worth $1 — losing tokens redeem for $0.
### Check Resolution Status
@@ -241,7 +241,7 @@ Once a market resolves, redeem winning tokens for USDC.e. Each winning token is
const redeemTx: Transaction = {
to: CTF_ADDRESS,
data: ctfInterface.encodeFunctionData("redeemPositions", [
USDCe_ADDRESS,
pUSD_ADDRESS,
ethers.constants.HashZero,
conditionId,
[1, 2], // Redeem both YES and NO (only winners pay out)
@@ -272,7 +272,7 @@ Once a market resolves, redeem winning tokens for USDC.e. Each winning token is
address=CTF_ADDRESS, abi=redeem_abi
).encode_abi(
abi_element_identifier="redeemPositions",
args=[USDCe_ADDRESS, bytes(32), condition_id, [1, 2]]
args=[pUSD_ADDRESS, bytes(32), condition_id, [1, 2]]
),
"value": "0"
}
@@ -285,7 +285,7 @@ Once a market resolves, redeem winning tokens for USDC.e. Each winning token is
use polymarket_client_sdk::ctf::types::RedeemPositionsRequest;
let request = RedeemPositionsRequest::builder()
.collateral_token(address!("0x2791Bca1f2de4661ED88A30C99A7a9449Aa84174"))
.collateral_token(address!("0xC011a7E12a19f7B1f670d46F03B03f3342E82DFB"))
.condition_id(condition_id)
.index_sets(vec![U256::from(1), U256::from(2)]) // Redeem both (only winners pay)
.build();
@@ -297,11 +297,11 @@ Once a market resolves, redeem winning tokens for USDC.e. Each winning token is
## Negative Risk Markets
Multi-outcome markets use the Neg Risk CTF Exchange. Split and merge work the same way, but use different contract addresses:
Multi-outcome markets use the Neg Risk CTF Exchange and Neg Risk Adapter. Split and merge work the same way, but use different contract addresses:
```typescript theme={null}
const NEG_RISK_CTF_EXCHANGE = "0xe2222d279d744050d28e00520010520000310F59";
const NEG_RISK_ADAPTER = "0xd91E80cF2E7be2e162c6513ceD06f1dD0dA35296";
const NEG_RISK_CTF_EXCHANGE = "0xC5d563A36AE78145C45a50134d48A1215220f80a";
```
See [Negative Risk Markets](/advanced/neg-risk) for details on how multi-outcome token mechanics differ.
@@ -313,7 +313,7 @@ See [Negative Risk Markets](/advanced/neg-risk) for details on how multi-outcome
### Before Quoting
1. Check market metadata via the [Gamma API](/market-data/fetching-markets)
2. Split sufficient USDC.e to cover your expected quoting size
2. Split sufficient pUSD to cover your expected quoting size
3. Set token approvals if not already done (see [Getting Started](/market-makers/getting-started))
### During Trading
@@ -341,7 +341,7 @@ const transactions: Transaction[] = [
{
to: CTF_ADDRESS,
data: ctfInterface.encodeFunctionData("splitPosition", [
USDCe_ADDRESS,
pUSD_ADDRESS,
ethers.constants.HashZero,
conditionIdA,
[1, 2],
@@ -353,7 +353,7 @@ const transactions: Transaction[] = [
{
to: CTF_ADDRESS,
data: ctfInterface.encodeFunctionData("splitPosition", [
USDCe_ADDRESS,
pUSD_ADDRESS,
ethers.constants.HashZero,
conditionIdB,
[1, 2],
docs/market-makers/overview.md
+9 -9
View File
@@ -21,7 +21,7 @@ Market makers are essential to Polymarket's ecosystem — they provide liquidity
<Steps>
<Step title="Complete Setup">
Deploy wallets, fund with USDC.e, and set token approvals. See the [Getting
Deploy wallets, fund with pUSD, and set token approvals. See the [Getting
Started](/market-makers/getting-started) guide.
</Step>
@@ -39,14 +39,14 @@ Market makers are essential to Polymarket's ecosystem — they provide liquidity
## Quick Reference
| Action | Tool | Documentation |
| ---------------------- | -------------- | ------------------------------------------------- |
| Deposit USDC.e | Bridge API | [Bridge](/trading/bridge/deposit) |
| Approve tokens | Relayer Client | [Getting Started](/market-makers/getting-started) |
| Post limit orders | CLOB REST API | [Create Orders](/trading/orders/create) |
| Monitor orderbook | WebSocket | [WebSocket](/market-data/websocket/overview) |
| Split USDC.e to tokens | CTF / Relayer | [Inventory](/market-makers/inventory) |
| Merge tokens to USDC.e | CTF / Relayer | [Inventory](/market-makers/inventory) |
| Action | Tool | Documentation |
| -------------------- | -------------- | ------------------------------------------------- |
| Deposit pUSD | Bridge API | [Bridge](/trading/bridge/deposit) |
| Approve tokens | Relayer Client | [Getting Started](/market-makers/getting-started) |
| Post limit orders | CLOB REST API | [Create Orders](/trading/orders/create) |
| Monitor orderbook | WebSocket | [WebSocket](/market-data/websocket/overview) |
| Split pUSD to tokens | CTF / Relayer | [Inventory](/market-makers/inventory) |
| Merge tokens to pUSD | CTF / Relayer | [Inventory](/market-makers/inventory) |
***
docs/market-makers/trading.md
+9 -9
View File
@@ -22,16 +22,16 @@ The core market making workflow is posting a bid and ask around your fair value.
<CodeGroup>
```typescript TypeScript theme={null}
import { ClobClient, Side, OrderType } from "@polymarket/clob-client";
import { ClobClient, Side, OrderType } from "@polymarket/clob-client-v2";
const client = new ClobClient(
"https://clob.polymarket.com",
137,
wallet,
credentials,
const client = new ClobClient({
host: "https://clob.polymarket.com",
chain: 137,
signer: wallet,
creds: credentials,
signatureType,
funder,
);
funderAddress: funder,
});
// Bid at 0.48
const bid = await client.createAndPostOrder({
@@ -257,7 +257,7 @@ Cancel individual orders, by market, or everything at once:
```
</CodeGroup>
See [Cancel Orders](/trading/orders/cancel) for full details including onchain cancellation.
See [Cancel Orders](/trading/orders/cancel) for full details.
### Monitoring Open Orders
docs/polymarket-101.md
+6 -6
View File
@@ -43,9 +43,9 @@ For example, if "Yes" shares for an event are trading at `$0.65`, the market bel
### Collateral and Tokens
Polymarket uses USDC.e (Bridged USDC on Polygon) as collateral. Every Yes/No pair is fully backed:
Polymarket uses pUSD (Polymarket USD) as collateral. Every Yes/No pair is fully backed:
* `$1 USDC.e` creates one Yes share and one No share
* `$1 pUSD` creates one Yes share and one No share
* Winning shares are redeemable for `$1.00`
* Losing shares are worth `$0.00`
@@ -72,7 +72,7 @@ When an event concludes, markets are resolved through the **UMA Optimistic Oracl
1. A proposer submits the outcome with a bond
2. There's a challenge period where anyone can dispute
3. If disputed, UMA token holders vote on the correct resolution
4. Winning tokens become redeemable for \$1 USDC.e
4. Winning tokens become redeemable for \$1 pUSD
This community-driven process ensures fair and accurate market resolution.
@@ -84,17 +84,17 @@ Polymarket is built on **Polygon**, a blockchain network, for several key reason
* **Non-custodial** - You control your funds, not a centralized entity
* **Transparent** - All activity is publicly verifiable onchain
* **Fast and affordable** - Polygon enables quick, low-cost transactions
* **Stable value** - USDC.e is pegged 1:1 to the US dollar, avoiding crypto volatility
* **Stable value** - pUSD is a standard ERC-20 backed by USDC, with backing enforced onchain by the smart contract — avoiding crypto volatility
## Proxy Wallets
When a user first uses Polymarket.com to trade they are prompted to create a wallet. When they do this, a 1 of 1 multisig is deployed to Polygon which is controlled/owned by the accessing EOA (either MetaMask wallet or MagicLink wallet). This proxy wallet is where all the user's positions (ERC1155) and USDC.e (ERC20) are held.
When a user first uses Polymarket.com to trade they are prompted to create a wallet. When they do this, a 1 of 1 multisig is deployed to Polygon which is controlled/owned by the accessing EOA (either MetaMask wallet or MagicLink wallet). This proxy wallet is where all the user's positions (ERC1155) and pUSD (ERC20) are held.
Using proxy wallets allows Polymarket to provide an improved UX where multi-step transactions can be executed atomically and transactions can be relayed by relayers on the gas station network. If you are a developer looking to programmatically access positions you accumulated via the Polymarket.com interface, you can either continue using the smart contract wallet by executing transactions through it from the owner account, or you can transfer these assets to a new address using the owner account.
### Deployments
Each user has their own proxy wallet (and thus proxy wallet address). See [Contract Addresses](/resources/contract-addresses) for all deployed factory and trading contract addresses on Polygon.
Each user has their own proxy wallet (and thus proxy wallet address). See [Contracts](/resources/contracts) for all deployed factory and trading contract addresses on Polygon.
<Tip>
For details on signature types (`EOA`, `POLY_PROXY`, `GNOSIS_SAFE`) and how to
docs/quickstart.md
+16 -16
View File
@@ -77,11 +77,11 @@ Get up and running with the Polymarket API in minutes — fetch market data and
<Step title="Install the SDK">
<CodeGroup>
```bash TypeScript theme={null}
npm install @polymarket/clob-client ethers@5
npm install @polymarket/clob-client-v2 ethers@5
```
```bash Python theme={null}
pip install py-clob-client
pip install py-clob-client-v2
```
```bash Rust theme={null}
@@ -96,7 +96,7 @@ Get up and running with the Polymarket API in minutes — fetch market data and
<Tabs>
<Tab title="TypeScript">
```typescript theme={null}
import { ClobClient } from "@polymarket/clob-client";
import { ClobClient } from "@polymarket/clob-client-v2";
import { Wallet } from "ethers"; // v5.8.0
const HOST = "https://clob.polymarket.com";
@@ -104,18 +104,18 @@ Get up and running with the Polymarket API in minutes — fetch market data and
const signer = new Wallet(process.env.PRIVATE_KEY);
// Derive API credentials (L1 → L2 auth)
const tempClient = new ClobClient(HOST, CHAIN_ID, signer);
const tempClient = new ClobClient({ host: HOST, chain: CHAIN_ID, signer });
const apiCreds = await tempClient.createOrDeriveApiKey();
// Initialize trading client
const client = new ClobClient(
HOST,
CHAIN_ID,
const client = new ClobClient({
host: HOST,
chain: CHAIN_ID,
signer,
apiCreds,
0, // Signature type: 0 = EOA
signer.address, // Funder address
);
creds: apiCreds,
signatureType: 0, // Signature type: 0 = EOA
funderAddress: signer.address, // Funder address
});
```
</Tab>
@@ -125,18 +125,18 @@ Get up and running with the Polymarket API in minutes — fetch market data and
import os
host = "https://clob.polymarket.com"
chain_id = 137 # Polygon mainnet
chain = 137 # Polygon mainnet
private_key = os.getenv("PRIVATE_KEY")
# Derive API credentials (L1 → L2 auth)
temp_client = ClobClient(host, key=private_key, chain_id=chain_id)
temp_client = ClobClient(host, key=private_key, chain=chain)
api_creds = temp_client.create_or_derive_api_creds()
# Initialize trading client
client = ClobClient(
host,
key=private_key,
chain_id=chain_id,
chain=chain,
creds=api_creds,
signature_type=0, # Signature type: 0 = EOA
funder="YOUR_WALLET_ADDRESS", # Funder address
@@ -173,7 +173,7 @@ Get up and running with the Polymarket API in minutes — fetch market data and
</Note>
<Warning>
Before trading, your funder address needs **USDC.e** (for buying outcome
Before trading, your funder address needs **pUSD** (for buying outcome
tokens) and **POL** (for gas, if using EOA type `0`).
</Warning>
</Step>
@@ -184,7 +184,7 @@ Get up and running with the Polymarket API in minutes — fetch market data and
<Tabs>
<Tab title="TypeScript">
```typescript theme={null}
import { Side, OrderType } from "@polymarket/clob-client";
import { Side, OrderType } from "@polymarket/clob-client-v2";
// Fetch market details to get tick size and neg risk
const market = await client.getMarket("YOUR_CONDITION_ID");
docs/quickstart/overview.md
-291
View File
@@ -1,291 +0,0 @@
> ## 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.
# Quickstart
> Fetch a market and place your first order
Get up and running with the Polymarket API in minutes — fetch market data and place your first order.
<Steps>
<Step title="Fetch a Market">
All data endpoints are public — no API key or authentication needed. Use the markets endpoint to find a market and get its token IDs:
<Tabs>
<Tab title="cURL">
```bash theme={null}
curl "https://gamma-api.polymarket.com/markets?active=true&closed=false&limit=1"
```
</Tab>
<Tab title="TypeScript">
```typescript theme={null}
const response = await fetch(
"https://gamma-api.polymarket.com/markets?active=true&closed=false&limit=1"
);
const markets = await response.json();
const market = markets[0];
console.log(market.question);
console.log(market.clobTokenIds);
// ["123456...", "789012..."] — [Yes token ID, No token ID]
```
</Tab>
<Tab title="Python">
```python theme={null}
import requests
response = requests.get(
"https://gamma-api.polymarket.com/markets",
params={"active": "true", "closed": "false", "limit": 1}
)
markets = response.json()
market = markets[0]
print(market["question"])
print(market["clobTokenIds"])
# ["123456...", "789012..."] — [Yes token ID, No token ID]
```
</Tab>
<Tab title="Rust">
```rust theme={null}
use polymarket_client_sdk::gamma::Client;
use polymarket_client_sdk::gamma::types::request::MarketsRequest;
let client = Client::default();
let request = MarketsRequest::builder()
.closed(false)
.limit(1)
.build();
let markets = client.markets(&request).await?;
let market = &markets[0];
println!("{:?}", market.question);
println!("{:?}", market.clob_token_ids);
// Some(["123456...", "789012..."]) — [Yes token ID, No token ID]
```
</Tab>
</Tabs>
Save a token ID from `clobTokenIds` — you'll need it to place an order. The first ID is the Yes token, the second is the No token. See [Fetching Markets](/market-data/fetching-markets) for more strategies like fetching by slug, tag, or event.
</Step>
<Step title="Install the SDK">
<CodeGroup>
```bash TypeScript theme={null}
npm install @polymarket/clob-client ethers@5
```
```bash Python theme={null}
pip install py-clob-client
```
```bash Rust theme={null}
cargo add polymarket-client-sdk
```
</CodeGroup>
</Step>
<Step title="Set Up Your Client">
Derive API credentials and initialize the trading client:
<Tabs>
<Tab title="TypeScript">
```typescript theme={null}
import { ClobClient } from "@polymarket/clob-client";
import { Wallet } from "ethers"; // v5.8.0
const HOST = "https://clob.polymarket.com";
const CHAIN_ID = 137; // Polygon mainnet
const signer = new Wallet(process.env.PRIVATE_KEY);
// Derive API credentials (L1 → L2 auth)
const tempClient = new ClobClient(HOST, CHAIN_ID, signer);
const apiCreds = await tempClient.createOrDeriveApiKey();
// Initialize trading client
const client = new ClobClient(
HOST,
CHAIN_ID,
signer,
apiCreds,
0, // Signature type: 0 = EOA
signer.address, // Funder address
);
```
</Tab>
<Tab title="Python">
```python theme={null}
from py_clob_client.client import ClobClient
import os
host = "https://clob.polymarket.com"
chain_id = 137 # Polygon mainnet
private_key = os.getenv("PRIVATE_KEY")
# Derive API credentials (L1 → L2 auth)
temp_client = ClobClient(host, key=private_key, chain_id=chain_id)
api_creds = temp_client.create_or_derive_api_creds()
# Initialize trading client
client = ClobClient(
host,
key=private_key,
chain_id=chain_id,
creds=api_creds,
signature_type=0, # Signature type: 0 = EOA
funder="YOUR_WALLET_ADDRESS", # Funder address
)
```
</Tab>
<Tab title="Rust">
```rust theme={null}
use std::str::FromStr;
use polymarket_client_sdk::POLYGON;
use polymarket_client_sdk::auth::{LocalSigner, Signer};
use polymarket_client_sdk::clob::{Client, Config};
let private_key = std::env::var("POLYMARKET_PRIVATE_KEY")?;
let signer = LocalSigner::from_str(&private_key)?
.with_chain_id(Some(POLYGON));
// Derive API credentials and initialize trading client (L1 → L2 auth)
// Signature type defaults to EOA (0)
let client = Client::new("https://clob.polymarket.com", Config::default())?
.authentication_builder(&signer)
.authenticate()
.await?;
```
</Tab>
</Tabs>
<Note>
This example uses an EOA wallet (signature type `0`) — your wallet pays its
own gas. Proxy wallet users (types `1` and `2`) can use Polymarket's gasless
relayer instead. See [Authentication](/api-reference/authentication) for
details on signature types.
</Note>
<Warning>
Before trading, your funder address needs **USDC.e** (for buying outcome
tokens) and **POL** (for gas, if using EOA type `0`).
</Warning>
</Step>
<Step title="Place an Order">
Use the `token_id` from Step 1 to place a limit order:
<Tabs>
<Tab title="TypeScript">
```typescript theme={null}
import { Side, OrderType } from "@polymarket/clob-client";
// Fetch market details to get tick size and neg risk
const market = await client.getMarket("YOUR_CONDITION_ID");
const tickSize = String(market.minimum_tick_size); // e.g., "0.01"
const negRisk = market.neg_risk; // e.g., false
const response = await client.createAndPostOrder(
{
tokenID: "YOUR_TOKEN_ID", // From Step 1
price: 0.50,
size: 10,
side: Side.BUY,
orderType: OrderType.GTC,
},
{
tickSize,
negRisk,
},
);
console.log("Order ID:", response.orderID);
console.log("Status:", response.status);
```
</Tab>
<Tab title="Python">
```python theme={null}
from py_clob_client.clob_types import OrderArgs, OrderType
from py_clob_client.order_builder.constants import BUY
# Fetch market details to get tick size and neg risk
market = client.get_market("YOUR_CONDITION_ID")
tick_size = str(market["minimum_tick_size"]) # e.g., "0.01"
neg_risk = market["neg_risk"] # e.g., False
response = client.create_and_post_order(
OrderArgs(
token_id="YOUR_TOKEN_ID", # From Step 1
price=0.50,
size=10,
side=BUY,
order_type=OrderType.GTC,
),
options={
"tick_size": tick_size,
"neg_risk": neg_risk,
},
)
print("Order ID:", response["orderID"])
print("Status:", response["status"])
```
</Tab>
<Tab title="Rust">
```rust theme={null}
use polymarket_client_sdk::clob::types::Side;
use polymarket_client_sdk::types::dec;
// token_id is a U256 — parse from the string returned in Step 1
let token_id = "YOUR_TOKEN_ID".parse()?;
// The Rust SDK auto-fetches tick size, neg risk, and fee rate
// No need to manually look them up — the order builder handles it
let order = client
.limit_order()
.token_id(token_id)
.price(dec!(0.50))
.size(dec!(10))
.side(Side::Buy)
.build()
.await?;
let signed_order = client.sign(&signer, order).await?;
let response = client.post_order(signed_order).await?;
println!("Order ID: {}", response.order_id);
println!("Status: {:?}", response.status);
```
</Tab>
</Tabs>
</Step>
</Steps>
***
## Next Steps
<CardGroup cols={2}>
<Card title="Authentication" icon="lock" href="/api-reference/authentication">
Understand L1/L2 auth, signature types, and API credentials.
</Card>
<Card title="Trading Quickstart" icon="bolt" href="/trading/quickstart">
Detailed trading guide with order management and troubleshooting.
</Card>
<Card title="Fetching Markets" icon="magnifying-glass" href="/market-data/fetching-markets">
Strategies for discovering markets by slug, tag, or category.
</Card>
<Card title="Core Concepts" icon="book" href="/concepts/markets-events">
Understand markets, events, prices, and positions.
</Card>
</CardGroup>
docs/resources/contract-addresses.md
-106
View File
@@ -1,106 +0,0 @@
> ## 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.
# Contract Addresses
> All Polymarket smart contract addresses on Polygon
All Polymarket contracts are deployed on **Polygon mainnet** (Chain ID: 137). This is the single source of truth for all contract addresses used across the platform.
***
## Core Trading Contracts
| Contract | Address | Description |
| ------------------------ | -------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------- |
| CTF Exchange | [`0x4bFb41d5B3570DeFd03C39a9A4D8dE6Bd8B8982E`](https://polygonscan.com/address/0x4bFb41d5B3570DeFd03C39a9A4D8dE6Bd8B8982E) | Standard market order matching and settlement |
| Neg Risk CTF Exchange | [`0xC5d563A36AE78145C45a50134d48A1215220f80a`](https://polygonscan.com/address/0xC5d563A36AE78145C45a50134d48A1215220f80a) | Order matching for [neg risk](/advanced/neg-risk) (multi-outcome) markets |
| Neg Risk Adapter | [`0xd91E80cF2E7be2e162c6513ceD06f1dD0dA35296`](https://polygonscan.com/address/0xd91E80cF2E7be2e162c6513ceD06f1dD0dA35296) | Converts No tokens between outcomes in neg risk markets |
| Conditional Tokens (CTF) | [`0x4D97DCd97eC945f40cF65F87097ACe5EA0476045`](https://polygonscan.com/address/0x4D97DCd97eC945f40cF65F87097ACe5EA0476045) | ERC1155 token storage — split, merge, and redeem operations |
***
## Token Contracts
| Contract | Address | Description |
| --------------------- | -------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------- |
| USDC.e (Bridged USDC) | [`0x2791Bca1f2de4661ED88A30C99A7a9449Aa84174`](https://polygonscan.com/address/0x2791Bca1f2de4661ED88A30C99A7a9449Aa84174) | Collateral token used for all Polymarket trading (6 decimals) |
***
## Wallet Factory Contracts
| Contract | Address | Description |
| ------------------------ | -------------------------------------------------------------------------------------------------------------------------- | --------------------- |
| Gnosis Safe Factory | [`0xaacfeea03eb1561c4e67d661e40682bd20e3541b`](https://polygonscan.com/address/0xaacfeea03eb1561c4e67d661e40682bd20e3541b) | Deploys Safe wallets |
| Polymarket Proxy Factory | [`0xaB45c5A4B0c941a2F231C04C3f49182e1A254052`](https://polygonscan.com/address/0xaB45c5A4B0c941a2F231C04C3f49182e1A254052) | Deploys proxy wallets |
***
## Resolution Contracts
| Contract | Address | Description |
| --------------------- | -------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------- |
| UMA Adapter | [`0x6A9D222616C90FcA5754cd1333cFD9b7fb6a4F74`](https://polygonscan.com/address/0x6A9D222616C90FcA5754cd1333cFD9b7fb6a4F74) | Adapter connecting Polymarket to the UMA Optimistic Oracle |
| UMA Optimistic Oracle | [`0xCB1822859cEF82Cd2Eb4E6276C7916e692995130`](https://polygonscan.com/address/0xCB1822859cEF82Cd2Eb4E6276C7916e692995130) | Handles market resolution proposals and disputes |
***
## Liquidity
| Contract | Address | Description |
| --------------------------- | -------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------- |
| Uniswap v3 USDC.e/USDC Pool | [`0xd36ec33c8bed5a9f7b6630855f1533455b98a418`](https://polygonscan.com/address/0xd36ec33c8bed5a9f7b6630855f1533455b98a418) | Used for USDC.e ↔ USDC conversion during withdrawals |
***
## Source Code
<CardGroup cols={2}>
<Card title="CTF Exchange" icon="github" href="https://github.com/Polymarket/ctf-exchange">
Order matching and settlement contracts
</Card>
<Card title="Conditional Tokens" icon="github" href="https://github.com/gnosis/conditional-tokens-contracts">
Gnosis Conditional Token Framework (ERC1155)
</Card>
</CardGroup>
***
## Usage in Code
<CodeGroup>
```typescript TypeScript theme={null}
const ADDRESSES = {
USDC_E: "0x2791Bca1f2de4661ED88A30C99A7a9449Aa84174",
CTF: "0x4D97DCd97eC945f40cF65F87097ACe5EA0476045",
CTF_EXCHANGE: "0x4bFb41d5B3570DeFd03C39a9A4D8dE6Bd8B8982E",
NEG_RISK_CTF_EXCHANGE: "0xC5d563A36AE78145C45a50134d48A1215220f80a",
};
```
```python Python theme={null}
ADDRESSES = {
"USDC_E": "0x2791Bca1f2de4661ED88A30C99A7a9449Aa84174",
"CTF": "0x4D97DCd97eC945f40cF65F87097ACe5EA0476045",
"CTF_EXCHANGE": "0x4bFb41d5B3570DeFd03C39a9A4D8dE6Bd8B8982E",
"NEG_RISK_CTF_EXCHANGE": "0xC5d563A36AE78145C45a50134d48A1215220f80a",
}
```
```rust Rust theme={null}
use polymarket_client_sdk::{POLYGON, contract_config};
// Addresses are built into the SDK — no hardcoding needed
let config = contract_config(POLYGON, false).expect("polygon config");
// config.exchange: 0x4bFb41d5B3570DeFd03C39a9A4D8dE6Bd8B8982E
// config.collateral: 0x2791Bca1f2de4661ED88A30C99A7a9449Aa84174
// config.conditional_tokens: 0x4D97DCd97eC945f40cF65F87097ACe5EA0476045
let neg_config = contract_config(POLYGON, true).expect("polygon neg risk config");
// neg_config.exchange: 0xC5d563A36AE78145C45a50134d48A1215220f80a
// neg_config.neg_risk_adapter: Some(0xd91E80cF2E7be2e162c6513ceD06f1dD0dA35296)
```
</CodeGroup>
docs/resources/error-codes.md
+1 -5
View File
@@ -205,11 +205,7 @@ These errors are returned when an order passes initial validation but fails duri
</ResponseField>
<ResponseField name="400" type="Bad Request">
`not enough balance / allowance` — Insufficient USDC.e balance or token allowance. Check your balance with [`GET /balance-allowance`](/api-reference/clob#get-balance-allowance) and approve the exchange contract if needed.
</ResponseField>
<ResponseField name="400" type="Bad Request">
`invalid nonce` — The order nonce has already been used or is invalid.
`not enough balance / allowance` — Insufficient pUSD balance or token allowance. Check your balance with [`GET /balance-allowance`](/api-reference/clob#get-balance-allowance) and approve the exchange contract if needed.
</ResponseField>
<ResponseField name="400" type="Bad Request">
docs/trading/bridge/deposit.md
+5 -5
View File
@@ -6,14 +6,14 @@
> Bridge assets from any supported chain to fund your Polymarket account
Polymarket uses **USDC.e** (Bridged USDC) on Polygon as collateral for all trading. The Bridge API lets you deposit assets from Ethereum, Solana, Bitcoin, and other chains—they're automatically converted to USDC.e on Polygon.
Polymarket uses **pUSD** (Polymarket USD) on Polygon as collateral for all trading. The Bridge API lets you deposit assets from Ethereum, Solana, Bitcoin, and other chains—they're automatically converted to pUSD on Polygon.
## How It Works
1. Request deposit addresses for your Polymarket wallet
2. Send assets to the appropriate address for your source chain
3. Assets are bridged and swapped to USDC.e automatically
4. USDC.e is credited to your wallet for trading
3. Assets are bridged and swapped to pUSD automatically
4. pUSD is credited to your wallet for trading
## Create Deposit Addresses
@@ -61,9 +61,9 @@ curl -X POST https://bridge.polymarket.com/deposit \
</Step>
</Steps>
## USDC vs USDC.e
## USDC vs pUSD
You can deposit either USDC (native) or USDC.e (bridged) to your Polymarket wallet. If you deposit native USDC, you will be prompted to "activate funds," which swaps it to USDC.e via the lowest-fee Uniswap pool (less than 10bp slippage).
You can deposit either USDC (native) or USDC.e (bridged) as the source asset to your Polymarket wallet. Either way, the incoming USDC or USDC.e is wrapped into pUSD via the Collateral Onramp, and pUSD is what you hold and trade with on Polymarket.
## Large Deposits
docs/trading/bridge/quote.md
+1 -1
View File
@@ -19,7 +19,7 @@ curl -X POST https://bridge.polymarket.com/quote \
"fromTokenAddress": "0x3c499c542cEF5E3811e1192ce70d8cC03d5c3359",
"recipientAddress": "0x17eC161f126e82A8ba337f4022d574DBEaFef575",
"toChainId": "137",
"toTokenAddress": "0x2791Bca1f2de4661ED88A30C99A7a9449Aa84174"
"toTokenAddress": "0xC011a7E12a19f7B1f670d46F03B03f3342E82DFB"
}'
```
docs/trading/bridge/status.md
+1 -1
View File
@@ -53,7 +53,7 @@ A response with active deposits:
"fromTokenAddress": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
"fromAmountBaseUnit": "1000000000",
"toChainId": "137",
"toTokenAddress": "0x2791Bca1f2de4661ED88A30C99A7a9449Aa84174",
"toTokenAddress": "0xC011a7E12a19f7B1f670d46F03B03f3342E82DFB",
"status": "COMPLETED",
"txHash": "0xabc123...",
"createdTimeMs": 1697875200000
docs/trading/bridge/supported-assets.md
+1 -1
View File
@@ -6,7 +6,7 @@
> Chains and tokens supported for deposits to Polymarket
The Bridge API supports deposits from multiple chains and tokens. All deposits are automatically converted to **USDC.e on Polygon**, which is used as collateral for trading on Polymarket.
The Bridge API supports deposits from multiple chains and tokens. All deposits are automatically converted to **pUSD on Polygon**, which is used as collateral for trading on Polymarket.
## Get Supported Assets
docs/trading/bridge/withdraw.md
+8 -8
View File
@@ -4,15 +4,15 @@
# Withdraw
> Bridge USDC.e from Polymarket to any supported chain
> Bridge pUSD from Polymarket to any supported chain
Withdraw USDC.e from your Polymarket wallet to any supported chain and token. Funds are automatically bridged and swapped to your desired token on the destination chain.
Withdraw pUSD from your Polymarket wallet to any supported chain and token. Funds are automatically bridged and swapped to your desired token on the destination chain.
## How It Works
1. Specify your destination chain, token, and recipient address
2. Receive deposit addresses for each destination chain (EVM, Solana, Bitcoin)
3. Send USDC.e from your Polymarket wallet to the appropriate deposit address
3. Send pUSD from your Polymarket wallet to the appropriate deposit address
4. Funds are automatically bridged and swapped to your desired token
5. Funds arrive at your destination wallet
@@ -23,14 +23,14 @@ Withdraw USDC.e from your Polymarket wallet to any supported chain and token. Fu
</Warning>
<Warning>
When withdrawing, USDC.e (bridged USDC) is swapped through the
When withdrawing, pUSD is unwrapped to USDC via the Collateral Offramp and swapped through the
[Uniswap v3 pool](https://polygonscan.com/address/0xd36ec33c8bed5a9f7b6630855f1533455b98a418)
for USDC (native). The UI enforces less than 10bp difference in output amount.
At times, this pool may be exhausted. If you are having withdraw issues, try
breaking your withdraw into smaller amounts or waiting for the pool to be
rebalanced. Alternatively, you can withdraw USDC.e directly, which does not
rebalanced. Alternatively, you can withdraw pUSD directly, which does not
require Uniswap liquidity — just be aware that some exchanges no longer accept
USDC.e deposits directly.
pUSD deposits directly.
</Warning>
<Tip>
@@ -81,8 +81,8 @@ Withdrawals are **instant** and **free** — Polymarket does not charge withdraw
and recipient.
</Step>
<Step title="Send USDC.e">
Transfer USDC.e from your Polymarket wallet to the appropriate deposit
<Step title="Send pUSD">
Transfer pUSD from your Polymarket wallet to the appropriate deposit
address.
</Step>
docs/trading/clients/builder.md
+62 -127
View File
@@ -4,116 +4,69 @@
# Builder Methods
> Methods for querying orders and trades using builder API credentials.
> Methods for querying orders and trades attributed to your builder code.
## Client Initialization
## Overview
Builder methods require the client to initialize with a separate builder config using credentials acquired from [Polymarket.com](https://polymarket.com/settings?tab=builder) and the `@polymarket/builder-signing-sdk` package.
Builder attribution in V2 is handled natively through the order struct — you attach your **builder code** (a `bytes32` identifier from your [Builder Profile](https://polymarket.com/settings?tab=builder)) to every order you submit. No separate client configuration is required.
<Tabs>
<Tab title="Local Builder Credentials">
<CodeGroup>
```typescript TypeScript theme={null}
import { ClobClient } from "@polymarket/clob-client";
import { BuilderConfig, BuilderApiKeyCreds } from "@polymarket/builder-signing-sdk";
<CodeGroup>
```typescript TypeScript theme={null}
import { ClobClient } from "@polymarket/clob-client-v2";
const builderConfig = new BuilderConfig({
localBuilderCreds: new BuilderApiKeyCreds({
key: process.env.BUILDER_API_KEY,
secret: process.env.BUILDER_SECRET,
passphrase: process.env.BUILDER_PASS_PHRASE,
}),
});
const client = new ClobClient({
host: "https://clob.polymarket.com",
chain: 137,
signer,
creds: apiCreds,
signatureType,
funderAddress,
});
const clobClient = new ClobClient(
"https://clob.polymarket.com",
137,
signer,
apiCreds, // User's API credentials from L1 authentication
signatureType,
funderAddress,
undefined,
false,
builderConfig
);
```
// Attach your builder code on every order
const response = await client.createAndPostOrder(
{
tokenID: "0x...",
price: 0.55,
size: 100,
side: Side.BUY,
builderCode: process.env.POLY_BUILDER_CODE!,
},
{ tickSize: "0.01", negRisk: false },
);
```
```python Python theme={null}
from py_clob_client.client import ClobClient
from py_builder_signing_sdk.config import BuilderConfig, BuilderApiKeyCreds
import os
```python Python theme={null}
from py_clob_client.client import ClobClient
from py_clob_client.clob_types import OrderArgs
from py_clob_client.order_builder.constants import BUY
import os
builder_config = BuilderConfig(
local_builder_creds=BuilderApiKeyCreds(
key=os.getenv("BUILDER_API_KEY"),
secret=os.getenv("BUILDER_SECRET"),
passphrase=os.getenv("BUILDER_PASS_PHRASE"),
)
)
client = ClobClient(
host="https://clob.polymarket.com",
chain=137,
key=os.getenv("PRIVATE_KEY"),
creds=creds,
signature_type=signature_type,
funder=funder,
)
clob_client = ClobClient(
host="https://clob.polymarket.com",
chain_id=137,
key=os.getenv("PRIVATE_KEY"),
creds=creds, # User's API credentials from L1 authentication
signature_type=signature_type,
funder=funder,
builder_config=builder_config
)
```
</CodeGroup>
</Tab>
<Tab title="Remote Builder Signing">
<CodeGroup>
```typescript TypeScript theme={null}
import { ClobClient } from "@polymarket/clob-client";
import { BuilderConfig } from "@polymarket/builder-signing-sdk";
const builderConfig = new BuilderConfig({
remoteBuilderConfig: { url: "http://localhost:3000/sign" }
});
const clobClient = new ClobClient(
"https://clob.polymarket.com",
137,
signer,
apiCreds, // User's API credentials from L1 authentication
signatureType,
funder,
undefined,
false,
builderConfig
);
```
```python Python theme={null}
from py_clob_client.client import ClobClient
from py_builder_signing_sdk.config import BuilderConfig, RemoteBuilderConfig
import os
builder_config = BuilderConfig(
remote_builder_config=RemoteBuilderConfig(
url="http://localhost:3000/sign"
)
)
clob_client = ClobClient(
host="https://clob.polymarket.com",
chain_id=137,
key=os.getenv("PRIVATE_KEY"),
creds=creds, # User's API credentials from L1 authentication
signature_type=signature_type,
funder=funder,
builder_config=builder_config
)
```
</CodeGroup>
</Tab>
</Tabs>
# Attach your builder code on every order
response = client.create_and_post_order(
OrderArgs(
token_id="0x...",
price=0.55,
size=100,
side=BUY,
builder_code=os.environ["POLY_BUILDER_CODE"],
),
options={"tick_size": "0.01", "neg_risk": False},
)
```
</CodeGroup>
<Info>
See [Order Attribution](/trading/orders/attribution) for more information on builder signing.
See [Order Attribution](/trading/orders/attribution) for the full attribution flow.
</Info>
***
@@ -124,24 +77,20 @@ Builder methods require the client to initialize with a separate builder config
### getOrder
Get details for a specific order by ID using builder authentication. When called from a builder-configured client, the request authenticates with builder headers and returns orders attributed to the builder.
Get details for a specific order by ID.
```typescript Signature theme={null}
async getOrder(orderID: string): Promise<OpenOrder>
```
<Info>
When a `BuilderConfig` is present, the client automatically sends builder headers. If builder auth is unavailable, it falls back to standard L2 headers.
</Info>
<CodeGroup>
```typescript TypeScript theme={null}
const order = await clobClient.getOrder("0xb816482a...");
const order = await client.getOrder("0xb816482a...");
console.log(order);
```
```python Python theme={null}
order = clob_client.get_order("0xb816482a...")
order = client.get_order("0xb816482a...")
print(order)
```
</CodeGroup>
@@ -150,7 +99,7 @@ async getOrder(orderID: string): Promise<OpenOrder>
### getOpenOrders
Get all open orders attributed to the builder. When called from a builder-configured client, returns orders placed through the builder rather than orders owned by the authenticated user.
Get all open orders attributed to your builder code.
```typescript Signature theme={null}
async getOpenOrders(
@@ -175,10 +124,10 @@ async getOpenOrders(
```typescript TypeScript theme={null}
// All open orders for this builder
const orders = await clobClient.getOpenOrders();
const orders = await client.getOpenOrders();
// Filtered by market
const marketOrders = await clobClient.getOpenOrders({
const marketOrders = await client.getOpenOrders({
market: "0xbd31dc8a...",
});
```
@@ -187,7 +136,7 @@ const marketOrders = await clobClient.getOpenOrders({
### getBuilderTrades
Retrieves all trades attributed to your builder account. Use this to track which trades were routed through your platform.
Retrieves all trades attributed to your builder code. Use this to track which trades were routed through your platform.
```typescript Signature theme={null}
async getBuilderTrades(
@@ -254,7 +203,7 @@ async getBuilderTrades(
</ResponseField>
<ResponseField name="builder" type="string">
Address of the builder who attributed this trade.
Builder code attributed to this trade.
</ResponseField>
<ResponseField name="market" type="string">
@@ -335,20 +284,6 @@ async getBuilderTrades(
***
### revokeBuilderApiKey
Revokes the builder API key used to authenticate the current request. After revocation, the key can no longer be used for builder-authenticated requests.
```typescript Signature theme={null}
async revokeBuilderApiKey(): Promise<any>
```
<ResponseField name="returns" type="any">
Response from the revocation request.
</ResponseField>
***
## See Also
<CardGroup cols={2}>
@@ -357,7 +292,7 @@ async revokeBuilderApiKey(): Promise<any>
</Card>
<Card title="Order Attribution" icon="key" href="/trading/orders/attribution">
Attribute orders to your builder account.
Attach your builder code to orders for volume credit.
</Card>
<Card title="L2 Methods" icon="lock" href="/trading/clients/l2">
docs/trading/clients/l1.md
+7 -55
View File
@@ -13,16 +13,16 @@ L1 methods require the client to initialize with a signer.
<Tabs>
<Tab title="TypeScript">
```typescript theme={null}
import { ClobClient } from "@polymarket/clob-client";
import { ClobClient } from "@polymarket/clob-client-v2";
import { Wallet } from "ethers";
const signer = new Wallet(process.env.PRIVATE_KEY);
const client = new ClobClient(
"https://clob.polymarket.com",
137,
signer // Signer required for L1 methods
);
const client = new ClobClient({
host: "https://clob.polymarket.com",
chain: 137,
signer, // Signer required for L1 methods
});
// Ready to create user API credentials
const apiKey = await client.createApiKey();
@@ -38,7 +38,7 @@ L1 methods require the client to initialize with a signer.
client = ClobClient(
host="https://clob.polymarket.com",
chain_id=137,
chain=137,
key=private_key # Signer required for L1 methods
)
@@ -161,22 +161,10 @@ async createOrder(
The side of the order (buy or sell).
</ResponseField>
<ResponseField name="feeRateBps" type="number">
Optional fee rate in basis points. Optional.
</ResponseField>
<ResponseField name="nonce" type="number">
Optional nonce for the order. Optional.
</ResponseField>
<ResponseField name="expiration" type="number">
Optional expiration timestamp for the order. Optional.
</ResponseField>
<ResponseField name="taker" type="string">
Optional taker address for the order. Optional.
</ResponseField>
<ResponseField name="tickSize" type="TickSize">
The tick size used for order validation (CreateOrderOptions).
</ResponseField>
@@ -197,10 +185,6 @@ async createOrder(
The signer's address.
</ResponseField>
<ResponseField name="taker" type="string">
The taker's address in the signed order.
</ResponseField>
<ResponseField name="tokenId" type="string">
The token ID in the signed order.
</ResponseField>
@@ -221,14 +205,6 @@ async createOrder(
The expiration timestamp as a string.
</ResponseField>
<ResponseField name="nonce" type="string">
The nonce as a string.
</ResponseField>
<ResponseField name="feeRateBps" type="string">
The fee rate in basis points as a string.
</ResponseField>
<ResponseField name="signatureType" type="number">
The type identifier for the signature scheme used.
</ResponseField>
@@ -266,18 +242,6 @@ async createMarketOrder(
Optional price limit for the market order. Optional.
</ResponseField>
<ResponseField name="feeRateBps" type="number">
Optional fee rate in basis points. Optional.
</ResponseField>
<ResponseField name="nonce" type="number">
Optional nonce for the order. Optional.
</ResponseField>
<ResponseField name="taker" type="string">
Optional taker address for the order. Optional.
</ResponseField>
<ResponseField name="orderType" type="OrderType.FOK | OrderType.FAK">
Optional order type, either FOK (Fill-Or-Kill) or FAK (Fill-And-Kill). Optional.
</ResponseField>
@@ -294,10 +258,6 @@ async createMarketOrder(
The signer's address.
</ResponseField>
<ResponseField name="taker" type="string">
The taker's address in the signed order.
</ResponseField>
<ResponseField name="tokenId" type="string">
The token ID in the signed order.
</ResponseField>
@@ -318,14 +278,6 @@ async createMarketOrder(
The expiration timestamp as a string.
</ResponseField>
<ResponseField name="nonce" type="string">
The nonce as a string.
</ResponseField>
<ResponseField name="feeRateBps" type="string">
The fee rate in basis points as a string.
</ResponseField>
<ResponseField name="signatureType" type="number">
The type identifier for the signature scheme used.
</ResponseField>
docs/trading/clients/l2.md
+9 -33
View File
@@ -13,7 +13,7 @@ L2 methods require the client to initialize with a signer, signature type, API c
<Tabs>
<Tab title="TypeScript">
```typescript theme={null}
import { ClobClient } from "@polymarket/clob-client";
import { ClobClient } from "@polymarket/clob-client-v2";
import { Wallet } from "ethers";
const signer = new Wallet(process.env.PRIVATE_KEY);
@@ -24,14 +24,14 @@ L2 methods require the client to initialize with a signer, signature type, API c
passphrase: process.env.PASSPHRASE,
};
const client = new ClobClient(
"https://clob.polymarket.com",
137,
const client = new ClobClient({
host: "https://clob.polymarket.com",
chain: 137,
signer,
apiCreds,
2, // GNOSIS_SAFE
process.env.FUNDER_ADDRESS
);
creds: apiCreds,
signatureType: 2, // GNOSIS_SAFE
funderAddress: process.env.FUNDER_ADDRESS,
});
// Ready to send authenticated requests
const order = await client.postOrder(signedOrder);
@@ -52,7 +52,7 @@ L2 methods require the client to initialize with a signer, signature type, API c
client = ClobClient(
host="https://clob.polymarket.com",
chain_id=137,
chain=137,
key=os.getenv("PRIVATE_KEY"),
creds=api_creds,
signature_type=2, # GNOSIS_SAFE
@@ -101,22 +101,10 @@ async createAndPostOrder(
The side of the order (buy or sell).
</ResponseField>
<ResponseField name="feeRateBps" type="number">
Optional fee rate in basis points.
</ResponseField>
<ResponseField name="nonce" type="number">
Optional nonce for the order.
</ResponseField>
<ResponseField name="expiration" type="number">
Optional expiration timestamp for the order.
</ResponseField>
<ResponseField name="taker" type="string">
Optional taker address.
</ResponseField>
<ResponseField name="tickSize" type="TickSize">
Tick size for the order. One of `"0.1"`, `"0.01"`, `"0.001"`, `"0.0001"`.
</ResponseField>
@@ -187,18 +175,6 @@ async createAndPostMarketOrder(
Optional price hint for the market order.
</ResponseField>
<ResponseField name="feeRateBps" type="number">
Optional fee rate in basis points.
</ResponseField>
<ResponseField name="nonce" type="number">
Optional nonce for the order.
</ResponseField>
<ResponseField name="taker" type="string">
Optional taker address.
</ResponseField>
<ResponseField name="orderType" type="OrderType.FOK | OrderType.FAK">
Optional order type override. Defaults to FOK.
</ResponseField>
docs/trading/clients/public.md
+91 -6
View File
@@ -13,12 +13,12 @@ Public methods require the client to initialize with the host URL and Polygon ch
<Tabs>
<Tab title="TypeScript">
```typescript theme={null}
import { ClobClient } from "@polymarket/clob-client";
import { ClobClient } from "@polymarket/clob-client-v2";
const client = new ClobClient(
"https://clob.polymarket.com",
137
);
const client = new ClobClient({
host: "https://clob.polymarket.com",
chain: 137,
});
// Ready to call public methods
const markets = await client.getMarkets();
@@ -31,7 +31,7 @@ Public methods require the client to initialize with the host URL and Polygon ch
client = ClobClient(
host="https://clob.polymarket.com",
chain_id=137
chain=137
)
# Ready to call public methods
@@ -584,6 +584,77 @@ async getMarketTradesEvents(conditionID: string): Promise<MarketTradeEvent[]>
***
### getClobMarketInfo
Fetch all CLOB-level parameters for a market in a single call — tokens, tick size, base fees, rewards config, RFQ status, and fee details.
```typescript Signature theme={null}
async getClobMarketInfo(conditionID: string): Promise<ClobMarketDetails>
```
<ResponseField name="conditionID" type="string">
The condition ID of the market.
</ResponseField>
**Response (`ClobMarketDetails`)**
<ResponseField name="gst" type="string | null">
Game start time (used for sports markets), ISO 8601 timestamp or `null`.
</ResponseField>
<ResponseField name="r" type="object">
Rewards configuration for the market.
</ResponseField>
<ResponseField name="t" type="ClobToken[]">
Tokens for this market. Each entry has:
* `t` (string) — token ID
* `o` (string) — outcome label (e.g. `Yes`, `No`)
</ResponseField>
<ResponseField name="mos" type="number">
Minimum order size.
</ResponseField>
<ResponseField name="mts" type="number">
Minimum tick size (price increment).
</ResponseField>
<ResponseField name="mbf" type="number">
Maker base fee in basis points.
</ResponseField>
<ResponseField name="tbf" type="number">
Taker base fee in basis points.
</ResponseField>
<ResponseField name="rfqe" type="boolean">
Whether RFQ (Request for Quote) is enabled for this market.
</ResponseField>
<ResponseField name="itode" type="boolean">
Whether taker order delay is enabled.
</ResponseField>
<ResponseField name="ibce" type="boolean">
Whether Blockaid check is enabled.
</ResponseField>
<ResponseField name="fd" type="object">
Fee curve parameters:
* `r` (number) — fee rate
* `e` (number) — fee curve exponent
* `to` (boolean) — whether fees apply to takers only
</ResponseField>
<ResponseField name="oas" type="number">
Minimum order age in seconds.
</ResponseField>
***
### getFeeRateBps
Get the fee rate in basis points for a token.
@@ -598,6 +669,20 @@ async getFeeRateBps(tokenID: string): Promise<number>
***
### getFeeExponent
Get the fee curve exponent for a token. The exponent shapes the fee curve used by the protocol when calculating fees at match time.
```typescript Signature theme={null}
async getFeeExponent(tokenID: string): Promise<number>
```
<ResponseField name="returns" type="number">
The fee curve exponent for the specified token's market.
</ResponseField>
***
### getTickSize
Get the tick size (minimum price increment) for a market.
docs/trading/ctf/merge.md
+6 -6
View File
@@ -4,12 +4,12 @@
# Merge Tokens
> Convert outcome token pairs back to USDC.e
> Convert outcome token pairs back to pUSD
**Merging** is the inverse of splitting — it converts a full set of outcome tokens back into USDC.e collateral. For every 1 Yes token and 1 No token you merge, you receive \$1 USDC.e. The condition must already be prepared on the CTF contract (via `prepareCondition`).
**Merging** is the inverse of splitting — it converts a full set of outcome tokens back into pUSD collateral. For every 1 Yes token and 1 No token you merge, you receive \$1 pUSD. The condition must already be prepared on the CTF contract (via `prepareCondition`).
```
100 Yes tokens + 100 No tokens → $100 USDC.e
100 Yes tokens + 100 No tokens → $100 pUSD
```
## Prerequisites
@@ -24,14 +24,14 @@ Before merging, you need:
1. You call `mergePositions()` with the amount and market details
2. One unit of each position in a full set is burned in return for 1 collateral unit
3. The CTF contract releases USDC.e back to your wallet
3. The CTF contract releases pUSD back to your wallet
The operation is atomic — if you don't have enough of both tokens, the transaction reverts.
## Function Parameters
<ResponseField name="collateralToken" type="IERC20">
USDC.e (Bridged USDC) contract address: `0x2791Bca1f2de4661ED88A30C99A7a9449Aa84174`
pUSD (Polymarket USD) contract address: `0xC011a7E12a19f7B1f670d46F03B03f3342E82DFB`
</ResponseField>
<ResponseField name="parentCollectionId" type="bytes32">
@@ -54,7 +54,7 @@ The operation is atomic — if you don't have enough of both tokens, the transac
<CardGroup cols={2}>
<Card title="Redeem Tokens" icon="hand-holding-dollar" href="/trading/ctf/redeem">
Exchange winning tokens for USDC.e after resolution
Exchange winning tokens for pUSD after resolution
</Card>
<Card title="CTF Overview" icon="book" href="/trading/ctf/overview">
docs/trading/ctf/overview.md
+12 -12
View File
@@ -12,12 +12,12 @@ All outcomes on Polymarket are tokenized using the **Conditional Token Framework
The Conditional Token Framework creates **ERC1155 tokens** representing outcomes of prediction markets. Each binary market has two tokens:
| Token | Redeems for | Condition |
| ------- | ------------- | -------------------- |
| **Yes** | \$1.00 USDC.e | Event occurs |
| **No** | \$1.00 USDC.e | Event does not occur |
| Token | Redeems for | Condition |
| ------- | ----------- | -------------------- |
| **Yes** | \$1.00 pUSD | Event occurs |
| **No** | \$1.00 pUSD | Event does not occur |
These tokens are always **fully collateralized** — every Yes/No pair is backed by exactly \$1.00 USDC.e locked in the CTF contract.
These tokens are always **fully collateralized** — every Yes/No pair is backed by exactly \$1.00 pUSD locked in the CTF contract.
## Core Operations
@@ -25,15 +25,15 @@ CTF provides three fundamental operations:
<CardGroup cols={3}>
<Card title="Split" icon="scissors" href="/trading/ctf/split">
Convert USDC.e into Yes + No token pairs
Convert pUSD into Yes + No token pairs
</Card>
<Card title="Merge" icon="merge" href="/trading/ctf/merge">
Convert Yes + No pairs back to USDC.e
Convert Yes + No pairs back to pUSD
</Card>
<Card title="Redeem" icon="hand-holding-dollar" href="/trading/ctf/redeem">
Exchange winning tokens for USDC.e after resolution
Exchange winning tokens for pUSD after resolution
</Card>
</CardGroup>
@@ -83,7 +83,7 @@ getPositionId(collateralToken, collectionId)
| Parameter | Type | Value |
| ----------------- | --------- | ----------------------------------------- |
| `collateralToken` | `IERC20` | USDC.e contract address on Polygon |
| `collateralToken` | `IERC20` | pUSD contract address on Polygon |
| `collectionId` | `bytes32` | One of the two collection IDs from step 2 |
The two resulting position IDs are the ERC1155 token IDs for the Yes and No outcomes of the market.
@@ -109,7 +109,7 @@ For neg risk markets, an additional **conversion** operation allows exchanging a
## Contract Addresses
See [Contract Addresses](/resources/contract-addresses) for all Polymarket smart contract addresses on Polygon.
See [Contracts](/resources/contracts) for all Polymarket smart contract addresses on Polygon.
## Resources
@@ -127,11 +127,11 @@ See [Contract Addresses](/resources/contract-addresses) for all Polymarket smart
<CardGroup cols={3}>
<Card title="Split Tokens" icon="scissors" href="/trading/ctf/split">
Create outcome token pairs from USDC.e
Create outcome token pairs from pUSD
</Card>
<Card title="Merge Tokens" icon="merge" href="/trading/ctf/merge">
Convert token pairs back to USDC.e
Convert token pairs back to pUSD
</Card>
<Card title="Redeem Tokens" icon="hand-holding-dollar" href="/trading/ctf/redeem">
docs/trading/ctf/redeem.md
+6 -6
View File
@@ -4,13 +4,13 @@
# Redeem Tokens
> Exchange winning tokens for USDC.e after market resolution
> Exchange winning tokens for pUSD after market resolution
**Redeeming** converts winning outcome tokens into USDC.e after a market resolves. Each winning token is worth exactly $1.00 — the losing token is worth $0.
**Redeeming** converts winning outcome tokens into pUSD after a market resolves. Each winning token is worth exactly $1.00 — the losing token is worth $0.
```
Market resolves YES:
100 Yes tokens → $100 USDC.e
100 Yes tokens → $100 pUSD
100 No tokens → $0
```
@@ -18,7 +18,7 @@ Market resolves YES:
Redemption is only available **after a market resolves**. Once the oracle reports the outcome:
* **Winning tokens** can be redeemed for \$1.00 USDC.e each
* **Winning tokens** can be redeemed for \$1.00 pUSD each
* **Losing tokens** are worth \$0 and produce no payout
<Note>
@@ -44,7 +44,7 @@ Before redeeming:
## Function Parameters
<ResponseField name="collateralToken" type="IERC20">
USDC.e (Bridged USDC) contract address: `0x2791Bca1f2de4661ED88A30C99A7a9449Aa84174`
pUSD (Polymarket USD) contract address: `0xC011a7E12a19f7B1f670d46F03B03f3342E82DFB`
</ResponseField>
<ResponseField name="parentCollectionId" type="bytes32">
@@ -78,7 +78,7 @@ When you call `redeemPositions()`:
* Your token balance is multiplied by the payout
* Winning tokens are burned
* USDC.e is transferred to your wallet
* pUSD is transferred to your wallet
* Losing tokens are burned as well, but produce a \$0 payout
## Next Steps
docs/trading/ctf/split.md
+9 -9
View File
@@ -4,20 +4,20 @@
# Split Tokens
> Convert USDC.e into outcome token pairs
> Convert pUSD into outcome token pairs
**Splitting** converts USDC.e collateral into a full (position) set of outcome tokens. For every \$1 USDC.e you split, you receive 1 Yes token and 1 No token.
**Splitting** converts pUSD collateral into a full (position) set of outcome tokens. For every \$1 pUSD you split, you receive 1 Yes token and 1 No token.
```
$100 USDC.e → 100 Yes tokens + 100 No tokens
$100 pUSD → 100 Yes tokens + 100 No tokens
```
## Prerequisites
Before splitting, ensure you have:
1. **USDC.e balance** on Polygon
2. **USDC.e approval** for the CTF contract to spend your tokens
1. **pUSD balance** on Polygon
2. **pUSD approval** for the CTF contract to spend your tokens
3. **Condition ID** of the market — the condition must already be prepared on the CTF contract (via `prepareCondition`)
<Note>
@@ -27,16 +27,16 @@ Before splitting, ensure you have:
## How It Works
1. You approve the CTF contract to spend your USDC.e
1. You approve the CTF contract to spend your pUSD
2. You call `splitPosition()` with the amount and market details
3. The CTF contract transfers USDC.e from your wallet and mints both outcome tokens
3. The CTF contract transfers pUSD from your wallet and mints both outcome tokens
The operation is atomic — if any step fails, the entire transaction reverts.
## Function Parameters
<ResponseField name="collateralToken" type="IERC20">
USDC.e (Bridged USDC) contract address: `0x2791Bca1f2de4661ED88A30C99A7a9449Aa84174`
pUSD (Polymarket USD) contract address: `0xC011a7E12a19f7B1f670d46F03B03f3342E82DFB`
</ResponseField>
<ResponseField name="parentCollectionId" type="bytes32">
@@ -60,7 +60,7 @@ The operation is atomic — if any step fails, the entire transaction reverts.
<CardGroup cols={2}>
<Card title="Merge Tokens" icon="merge" href="/trading/ctf/merge">
Convert token pairs back to USDC.e
Convert token pairs back to pUSD
</Card>
<Card title="Trade on Orderbook" icon="chart-line" href="/trading/orders/create">
docs/trading/gasless.md
+80 -241
View File
@@ -6,7 +6,7 @@
> Execute onchain operations without paying gas fees
Polymarket's **Relayer Client** enables gasless transactions for your users. Instead of requiring users to hold POL for gas, Polymarket's infrastructure pays all transaction fees. This creates a seamless experience where users only need USDC.e to trade.
Polymarket's **Relayer Client** enables gasless transactions for your users. Instead of requiring users to hold POL for gas, Polymarket's infrastructure pays all transaction fees. This creates a seamless experience where users only need pUSD to trade.
## How It Works
@@ -18,43 +18,20 @@ The relayer acts as a transaction sponsor:
4. The relayer submits it onchain and pays the gas fee
5. The transaction executes from the user's wallet
<Note>
Gasless transactions require authentication with **Builder API Keys** or **Relayer API Keys**.
</Note>
## What Is Covered
Polymarket pays gas for all operations routed through the relayer:
| Operation | Description |
| --------------------- | --------------------------------------------------- |
| **Wallet deployment** | Deploy Safe or Proxy wallets for new users |
| **Token approvals** | Approve contracts to spend USDC.e or outcome tokens |
| **CTF operations** | Split, merge, and redeem positions |
| **Transfers** | Move tokens between addresses |
| Operation | Description |
| --------------------- | ------------------------------------------------- |
| **Wallet deployment** | Deploy Safe or Proxy wallets for new users |
| **Token approvals** | Approve contracts to spend pUSD or outcome tokens |
| **CTF operations** | Split, merge, and redeem positions |
| **Transfers** | Move tokens between addresses |
## Authentication
The relayer supports two authentication methods. Choose the one that fits your use case.
### Using Builder API Keys
Builder API Keys are for [Builder Program](/builders/overview) members. They authenticate via HMAC-SHA256 signed headers and are required to use the relayer SDKs.
All requests must include these headers:
| Header | Description |
| ------------------------- | ----------------------- |
| `POLY_BUILDER_API_KEY` | Your Builder API key |
| `POLY_BUILDER_TIMESTAMP` | Unix timestamp |
| `POLY_BUILDER_PASSPHRASE` | Your Builder passphrase |
| `POLY_BUILDER_SIGNATURE` | HMAC-SHA256 signature |
The SDKs handle header generation automatically when you provide your credentials via `BuilderConfig`.
### Using Relayer API Keys
Relayer API Keys are for market makers and anyone who needs a simpler alternative. You can create them from [Settings > API Keys](https://polymarket.com/settings?tab=api-keys) on the Polymarket website.
The relayer uses **Relayer API Keys**. You can create one from [Settings > API Keys](https://polymarket.com/settings?tab=api-keys) on the Polymarket website.
Include these headers with your requests:
@@ -71,205 +48,67 @@ Include these headers with your requests:
Before using the relayer, you need:
| Requirement | Source |
| ---------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| Builder API credentials **or** Relayer API key | [Builder Profile](https://polymarket.com/settings?tab=builder) or [Settings > API Keys](https://polymarket.com/settings?tab=api-keys) |
| User's private key or signer | Your wallet integration |
| USDC.e balance | For trading (not for gas) |
> The below section is for the Builder SDKs only. If you want to use the Relayer API Key directly without the SDK, see the [Relayer API Reference](/api-reference/relayer).
| Requirement | Source |
| ---------------------------- | ------------------------------------------------------------------- |
| Relayer API Key | [Settings > API Keys](https://polymarket.com/settings?tab=api-keys) |
| User's private key or signer | Your wallet integration |
| pUSD balance | For trading (not for gas) |
## Installation
<CodeGroup>
```bash npm theme={null}
npm install @polymarket/builder-relayer-client @polymarket/builder-signing-sdk
npm install @polymarket/builder-relayer-client
```
```bash pip theme={null}
pip install py-builder-relayer-client py-builder-signing-sdk
pip install py-builder-relayer-client
```
</CodeGroup>
## Client Setup
Initialize the relayer client with your signing configuration:
Initialize the relayer client with your Relayer API Key:
<Tabs>
<Tab title="Local Signing">
Use local signing when your backend handles all transactions securely.
<CodeGroup>
```typescript TypeScript theme={null}
import { createWalletClient, http, Hex } from "viem";
import { privateKeyToAccount } from "viem/accounts";
import { polygon } from "viem/chains";
import { RelayClient } from "@polymarket/builder-relayer-client";
<CodeGroup>
```typescript TypeScript theme={null}
import { createWalletClient, http, Hex } from "viem";
import { privateKeyToAccount } from "viem/accounts";
import { polygon } from "viem/chains";
import { RelayClient } from "@polymarket/builder-relayer-client";
import { BuilderConfig } from "@polymarket/builder-signing-sdk";
const account = privateKeyToAccount(process.env.PRIVATE_KEY as Hex);
const wallet = createWalletClient({
account,
chain: polygon,
transport: http(process.env.RPC_URL),
});
const account = privateKeyToAccount(process.env.PRIVATE_KEY as Hex);
const wallet = createWalletClient({
account,
chain: polygon,
transport: http(process.env.RPC_URL),
});
const client = new RelayClient({
host: "https://relayer-v2.polymarket.com/",
chain: 137,
signer: wallet,
relayerApiKey: process.env.RELAYER_API_KEY!,
relayerApiKeyAddress: process.env.RELAYER_API_KEY_ADDRESS!,
});
```
const builderConfig = new BuilderConfig({
localBuilderCreds: {
key: process.env.POLY_BUILDER_API_KEY!,
secret: process.env.POLY_BUILDER_SECRET!,
passphrase: process.env.POLY_BUILDER_PASSPHRASE!,
},
});
```python Python theme={null}
import os
from py_builder_relayer_client.client import RelayClient
const client = new RelayClient(
"https://relayer-v2.polymarket.com/",
137,
wallet,
builderConfig,
);
```
```python Python theme={null}
import os
from py_builder_relayer_client.client import RelayClient
from py_builder_signing_sdk import BuilderConfig, BuilderApiKeyCreds
builder_config = BuilderConfig(
local_builder_creds=BuilderApiKeyCreds(
key=os.getenv("POLY_BUILDER_API_KEY"),
secret=os.getenv("POLY_BUILDER_SECRET"),
passphrase=os.getenv("POLY_BUILDER_PASSPHRASE"),
)
)
client = RelayClient(
"https://relayer-v2.polymarket.com",
137,
os.getenv("PRIVATE_KEY"),
builder_config
)
```
</CodeGroup>
</Tab>
<Tab title="Remote Signing">
Use remote signing to keep credentials on a secure server you control.
**Your signing server** receives request details and returns authentication headers:
<CodeGroup>
```typescript Server (TypeScript) theme={null}
import {
buildHmacSignature,
BuilderApiKeyCreds,
} from "@polymarket/builder-signing-sdk";
const BUILDER_CREDENTIALS: BuilderApiKeyCreds = {
key: process.env.POLY_BUILDER_API_KEY!,
secret: process.env.POLY_BUILDER_SECRET!,
passphrase: process.env.POLY_BUILDER_PASSPHRASE!,
};
// POST /sign endpoint
export async function handleSignRequest(request) {
const { method, path, body } = await request.json();
const timestamp = Date.now().toString();
const signature = buildHmacSignature(
BUILDER_CREDENTIALS.secret,
parseInt(timestamp),
method,
path,
body,
);
return {
POLY_BUILDER_SIGNATURE: signature,
POLY_BUILDER_TIMESTAMP: timestamp,
POLY_BUILDER_API_KEY: BUILDER_CREDENTIALS.key,
POLY_BUILDER_PASSPHRASE: BUILDER_CREDENTIALS.passphrase,
};
}
```
```python Server (Python) theme={null}
import os
import time
from py_builder_signing_sdk.signing.hmac import build_hmac_signature
from py_builder_signing_sdk import BuilderApiKeyCreds
BUILDER_CREDENTIALS = BuilderApiKeyCreds(
key=os.environ["POLY_BUILDER_API_KEY"],
secret=os.environ["POLY_BUILDER_SECRET"],
passphrase=os.environ["POLY_BUILDER_PASSPHRASE"],
)
# POST /sign endpoint
def handle_sign_request(method: str, path: str, body: str):
timestamp = str(int(time.time()))
signature = build_hmac_signature(
BUILDER_CREDENTIALS.secret,
timestamp,
method,
path,
body
)
return {
"POLY_BUILDER_SIGNATURE": signature,
"POLY_BUILDER_TIMESTAMP": timestamp,
"POLY_BUILDER_API_KEY": BUILDER_CREDENTIALS.key,
"POLY_BUILDER_PASSPHRASE": BUILDER_CREDENTIALS.passphrase,
}
```
</CodeGroup>
**Your client** points to your signing server:
<CodeGroup>
```typescript Client (TypeScript) theme={null}
import { RelayClient } from "@polymarket/builder-relayer-client";
import { BuilderConfig } from "@polymarket/builder-signing-sdk";
const builderConfig = new BuilderConfig({
remoteBuilderConfig: {
url: "https://your-server.com/sign",
},
});
const client = new RelayClient(
"https://relayer-v2.polymarket.com/",
137,
wallet,
builderConfig,
);
```
```python Client (Python) theme={null}
from py_builder_relayer_client.client import RelayClient
from py_builder_signing_sdk import BuilderConfig, RemoteBuilderConfig
builder_config = BuilderConfig(
remote_builder_config=RemoteBuilderConfig(
url="https://your-server.com/sign"
)
)
client = RelayClient(
"https://relayer-v2.polymarket.com",
137,
private_key,
builder_config
)
```
</CodeGroup>
</Tab>
</Tabs>
client = RelayClient(
host="https://relayer-v2.polymarket.com",
chain=137,
signer=os.getenv("PRIVATE_KEY"),
relayer_api_key=os.environ["RELAYER_API_KEY"],
relayer_api_key_address=os.environ["RELAYER_API_KEY_ADDRESS"],
)
```
</CodeGroup>
<Warning>
Never expose Builder API credentials in client-side code. Use environment
Never expose your Relayer API Key in client-side code. Use environment
variables or a secrets manager.
</Warning>
@@ -286,13 +125,14 @@ Choose a wallet type when initializing the client:
```typescript Safe Wallet (TypeScript) theme={null}
import { RelayClient, RelayerTxType } from "@polymarket/builder-relayer-client";
const client = new RelayClient(
"https://relayer-v2.polymarket.com/",
137,
wallet,
builderConfig,
RelayerTxType.SAFE,
);
const client = new RelayClient({
host: "https://relayer-v2.polymarket.com/",
chain: 137,
signer: wallet,
relayerApiKey: process.env.RELAYER_API_KEY!,
relayerApiKeyAddress: process.env.RELAYER_API_KEY_ADDRESS!,
txType: RelayerTxType.SAFE,
});
// Deploy before first transaction
const response = await client.deploy();
@@ -303,7 +143,7 @@ Choose a wallet type when initializing the client:
```python Safe Wallet (Python) theme={null}
from py_builder_relayer_client.client import RelayClient
# client initialized with builder_config (see Client Setup above)
# client initialized with relayer credentials (see Client Setup above)
# Deploy before first transaction
response = client.deploy()
@@ -314,13 +154,14 @@ Choose a wallet type when initializing the client:
```typescript Proxy Wallet (TypeScript) theme={null}
import { RelayClient, RelayerTxType } from "@polymarket/builder-relayer-client";
const client = new RelayClient(
"https://relayer-v2.polymarket.com/",
137,
wallet,
builderConfig,
RelayerTxType.PROXY,
);
const client = new RelayClient({
host: "https://relayer-v2.polymarket.com/",
chain: 137,
signer: wallet,
relayerApiKey: process.env.RELAYER_API_KEY!,
relayerApiKeyAddress: process.env.RELAYER_API_KEY_ADDRESS!,
txType: RelayerTxType.PROXY,
});
// No deploy needed - auto-deploys on first transaction
```
@@ -328,7 +169,7 @@ Choose a wallet type when initializing the client:
```python Proxy Wallet (Python) theme={null}
from py_builder_relayer_client.client import RelayClient
# client initialized with builder_config (see Client Setup above)
# client initialized with relayer credentials (see Client Setup above)
# No deploy needed - auto-deploys on first transaction
```
</CodeGroup>
@@ -356,11 +197,11 @@ Approve contracts to spend tokens:
```typescript TypeScript theme={null}
import { encodeFunctionData, maxUint256 } from "viem";
const USDC = "0x2791Bca1f2de4661ED88A30C99A7a9449Aa84174";
const pUSD = "0xC011a7E12a19f7B1f670d46F03B03f3342E82DFB";
const CTF = "0x4D97DCd97eC945f40cF65F87097ACe5EA0476045";
const approveTx = {
to: USDC,
to: pUSD,
data: encodeFunctionData({
abi: [
{
@@ -379,21 +220,21 @@ Approve contracts to spend tokens:
value: "0",
};
const response = await client.execute([approveTx], "Approve USDC.e for CTF");
const response = await client.execute([approveTx], "Approve pUSD for CTF");
await response.wait();
```
```python Python theme={null}
from web3 import Web3
USDC = "0x2791Bca1f2de4661ED88A30C99A7a9449Aa84174"
pUSD = "0xC011a7E12a19f7B1f670d46F03B03f3342E82DFB"
CTF = "0x4D97DCd97eC945f40cF65F87097ACe5EA0476045"
MAX_UINT256 = 2**256 - 1
approve_tx = {
"to": USDC,
"to": pUSD,
"data": Web3().eth.contract(
address=USDC,
address=pUSD,
abi=[{
"name": "approve",
"type": "function",
@@ -407,14 +248,14 @@ Approve contracts to spend tokens:
"value": "0"
}
response = client.execute([approve_tx], "Approve USDC.e for CTF")
response = client.execute([approve_tx], "Approve pUSD for CTF")
response.wait()
```
</CodeGroup>
### Redeem Positions
Exchange winning tokens for USDC.e after market resolution:
Exchange winning tokens for pUSD after market resolution:
<CodeGroup>
```typescript TypeScript theme={null}
@@ -483,7 +324,7 @@ Execute multiple operations atomically in a single call:
<CodeGroup>
```typescript TypeScript theme={null}
const approveTx = {
to: USDC,
to: pUSD,
data: encodeFunctionData({
abi: erc20Abi,
functionName: "approve",
@@ -493,7 +334,7 @@ Execute multiple operations atomically in a single call:
};
const transferTx = {
to: USDC,
to: pUSD,
data: encodeFunctionData({
abi: erc20Abi,
functionName: "transfer",
@@ -512,7 +353,7 @@ Execute multiple operations atomically in a single call:
```python Python theme={null}
approve_tx = {
"to": USDC,
"to": pUSD,
"data": contract.encode_abi(
abi_element_identifier="approve",
args=[CTF, MAX_UINT256]
@@ -521,7 +362,7 @@ Execute multiple operations atomically in a single call:
}
transfer_tx = {
"to": USDC,
"to": pUSD,
"data": contract.encode_abi(
abi_element_identifier="transfer",
args=[recipient_address, 50 * 10**6]
@@ -555,14 +396,12 @@ Track transaction progress through these states:
## Contract Addresses
See [Contract Addresses](/resources/contract-addresses) for all Polymarket smart contract addresses on Polygon.
See [Contracts](/resources/contracts) for all Polymarket smart contract addresses on Polygon.
## Resources
* [Builder Relayer Client (TypeScript)](https://github.com/Polymarket/builder-relayer-client)
* [Builder Relayer Client (Python)](https://github.com/Polymarket/py-builder-relayer-client)
* [Builder Signing SDK (TypeScript)](https://github.com/Polymarket/builder-signing-sdk)
* [Builder Signing SDK (Python)](https://github.com/Polymarket/py-builder-signing-sdk)
## Next Steps
docs/trading/orderbook.md
+6 -6
View File
@@ -10,15 +10,15 @@ The orderbook is a public endpoint — no authentication required. You can read
<CodeGroup>
```typescript TypeScript theme={null}
import { ClobClient } from "@polymarket/clob-client";
import { ClobClient } from "@polymarket/clob-client-v2";
const client = new ClobClient("https://clob.polymarket.com", 137);
const client = new ClobClient({ host: "https://clob.polymarket.com", chain: 137 });
```
```python Python theme={null}
from py_clob_client.client import ClobClient
client = ClobClient("https://clob.polymarket.com", chain_id=137)
client = ClobClient("https://clob.polymarket.com", chain=137)
```
```rust Rust theme={null}
@@ -230,7 +230,7 @@ Fetch historical price data for a token over various time intervals:
<CodeGroup>
```typescript TypeScript theme={null}
import { PriceHistoryInterval } from "@polymarket/clob-client";
import { PriceHistoryInterval } from "@polymarket/clob-client-v2";
const history = await client.getPricesHistory({
market: "TOKEN_ID", // Note: this param is named "market" but takes a token ID
@@ -302,7 +302,7 @@ Calculate the effective price you'd pay for a market order of a given size, acco
<CodeGroup>
```typescript TypeScript theme={null}
import { Side, OrderType } from "@polymarket/clob-client";
import { Side, OrderType } from "@polymarket/clob-client-v2";
// What price would I pay to buy $500 worth?
const price = await client.calculateMarketPrice(
@@ -366,7 +366,7 @@ All orderbook queries have batch variants for fetching data across multiple toke
<CodeGroup>
```typescript TypeScript theme={null}
import { Side } from "@polymarket/clob-client";
import { Side } from "@polymarket/clob-client-v2";
// Fetch prices for multiple tokens
const prices = await client.getPrices([
docs/trading/orders/attribution.md
+54 -301
View File
@@ -4,301 +4,93 @@
# Order Attribution
> Attribute orders to your builder key for volume credit
> Attribute orders to your builder code for volume credit and fee rewards
Order attribution adds builder authentication headers when placing orders through the CLOB, enabling Polymarket to credit trades to your builder account. This allows you to:
Order attribution credits trades to your builder account by attaching your **builder code** to every order. This enables:
* Track volume on the [Builder Leaderboard](https://builders.polymarket.com/)
* Earn rewards through the [Builder Program](/builders/overview)
* Monitor performance via the Data API
* Volume tracking on the [Builder Leaderboard](https://builders.polymarket.com/)
* Fee rewards through the [Builder Program](/builders/overview)
* Performance monitoring via the Data API
***
## Builder API Credentials
## Builder Code
Each builder receives API credentials from their [Builder Profile](https://polymarket.com/settings?tab=builder):
Your **builder code** is a `bytes32` identifier tied to your builder profile. Find it at [polymarket.com/settings?tab=builder](https://polymarket.com/settings?tab=builder).
| Credential | Description |
| ------------ | ------------------------------------ |
| `key` | Your builder API key identifier |
| `secret` | Secret key for signing requests |
| `passphrase` | Additional authentication passphrase |
That's the only credential you need for attribution — no HMAC signing, no separate API key, no special headers.
<Warning>
Builder API credentials are **not** the same as user API credentials. Builder
credentials are for order attribution only — you still need user credentials
for authentication. Never expose builder credentials in client-side code or
commit them to version control.
</Warning>
<Note>
Builder codes are public identifiers — they appear onchain in the `builder` field of every order you attribute. Only you control which orders include your code, so keep it scoped to apps you own.
</Note>
***
## Remote Signing
## Attaching the Builder Code
Remote signing keeps your builder credentials secure on a server you control. The user's client sends order details to your server, which adds the builder headers before forwarding to the CLOB.
### Server Implementation
Your signing server receives request details and returns the authentication headers:
Pass `builderCode` in the order struct on every order you submit. The SDK serializes it into the onchain order's `builder` field, and the protocol attributes every matched trade to your profile.
<CodeGroup>
```typescript TypeScript theme={null}
import {
buildHmacSignature,
BuilderApiKeyCreds,
} from "@polymarket/builder-signing-sdk";
import { ClobClient, Side, OrderType } from "@polymarket/clob-client-v2";
const BUILDER_CREDENTIALS: BuilderApiKeyCreds = {
key: process.env.POLY_BUILDER_API_KEY!,
secret: process.env.POLY_BUILDER_SECRET!,
passphrase: process.env.POLY_BUILDER_PASSPHRASE!,
};
const client = new ClobClient({
host: "https://clob.polymarket.com",
chain: 137,
signer,
creds: apiCreds,
signatureType: 2,
funderAddress,
});
// POST /sign - receives { method, path, body } from the client SDK
export async function handleSignRequest(request) {
const { method, path, body } = await request.json();
const timestamp = Date.now().toString();
const signature = buildHmacSignature(
BUILDER_CREDENTIALS.secret,
parseInt(timestamp),
method,
path,
body,
);
return {
POLY_BUILDER_SIGNATURE: signature,
POLY_BUILDER_TIMESTAMP: timestamp,
POLY_BUILDER_API_KEY: BUILDER_CREDENTIALS.key,
POLY_BUILDER_PASSPHRASE: BUILDER_CREDENTIALS.passphrase,
};
}
```
```python Python theme={null}
import os
import time
from py_builder_signing_sdk.signing.hmac import build_hmac_signature
from py_builder_signing_sdk import BuilderApiKeyCreds
BUILDER_CREDENTIALS = BuilderApiKeyCreds(
key=os.environ["POLY_BUILDER_API_KEY"],
secret=os.environ["POLY_BUILDER_SECRET"],
passphrase=os.environ["POLY_BUILDER_PASSPHRASE"],
)
# POST /sign - receives { method, path, body } from the client SDK
def handle_sign_request(method: str, path: str, body: str):
timestamp = str(int(time.time()))
signature = build_hmac_signature(
BUILDER_CREDENTIALS.secret,
timestamp,
method,
path,
body
)
return {
"POLY_BUILDER_SIGNATURE": signature,
"POLY_BUILDER_TIMESTAMP": timestamp,
"POLY_BUILDER_API_KEY": BUILDER_CREDENTIALS.key,
"POLY_BUILDER_PASSPHRASE": BUILDER_CREDENTIALS.passphrase,
}
```
</CodeGroup>
### Client Configuration
Point the CLOB client to your signing server:
<CodeGroup>
```typescript TypeScript theme={null}
import { ClobClient } from "@polymarket/clob-client";
import { BuilderConfig } from "@polymarket/builder-signing-sdk";
const builderConfig = new BuilderConfig({
remoteBuilderConfig: {
url: "https://your-server.com/sign",
token: "optional-auth-token", // optional
const response = await client.createAndPostOrder(
{
tokenID: "0x...",
price: 0.55,
size: 100,
side: Side.BUY,
builderCode: "0xabc123...", // your builder code from polymarket.com/settings?tab=builder
},
});
const client = new ClobClient(
"https://clob.polymarket.com",
137,
signer,
apiCreds,
2, // signature type
funderAddress,
undefined,
false,
builderConfig,
{ tickSize: "0.01", negRisk: false },
OrderType.GTC,
);
// Orders automatically include builder headers
const response = await client.createAndPostOrder(/* ... */);
```
```python Python theme={null}
from py_clob_client.client import ClobClient
from py_builder_signing_sdk import BuilderConfig, RemoteBuilderConfig
builder_config = BuilderConfig(
remote_builder_config=RemoteBuilderConfig(
url="https://your-server.com/sign",
token="optional-auth-token", # optional
)
)
from py_clob_client.clob_types import OrderArgs, OrderType
from py_clob_client.order_builder.constants import BUY
client = ClobClient(
host="https://clob.polymarket.com",
chain_id=137,
chain=137,
key=private_key,
creds=api_creds,
signature_type=2,
funder=funder_address,
builder_config=builder_config
)
# Orders automatically include builder headers
response = client.create_and_post_order(...)
```
```rust Rust theme={null}
use polymarket_client_sdk::auth::builder::Config as BuilderConfig;
use polymarket_client_sdk::clob::types::SignatureType;
// First, authenticate as a normal user
let client = Client::new("https://clob.polymarket.com", Config::default())?
.authentication_builder(&signer)
.signature_type(SignatureType::GnosisSafe)
.authenticate()
.await?;
// Then promote to builder with remote signing
let builder_config = BuilderConfig::remote(
"https://your-server.com/sign",
Some("optional-auth-token".to_owned()),
)?;
let client = client.promote_to_builder(builder_config).await?;
// Orders automatically include builder headers
response = client.create_and_post_order(
OrderArgs(
token_id="0x...",
price=0.55,
size=100,
side=BUY,
builder_code="0xabc123...", # your builder code from polymarket.com/settings?tab=builder
),
options={"tick_size": "0.01", "neg_risk": False},
order_type=OrderType.GTC,
)
```
</CodeGroup>
***
## Local Signing
Sign orders locally when you control the entire order placement flow (e.g., your backend places orders on behalf of users):
<CodeGroup>
```typescript TypeScript theme={null}
import { ClobClient } from "@polymarket/clob-client";
import {
BuilderConfig,
BuilderApiKeyCreds,
} from "@polymarket/builder-signing-sdk";
const builderCreds: BuilderApiKeyCreds = {
key: process.env.POLY_BUILDER_API_KEY!,
secret: process.env.POLY_BUILDER_SECRET!,
passphrase: process.env.POLY_BUILDER_PASSPHRASE!,
};
const builderConfig = new BuilderConfig({
localBuilderCreds: builderCreds,
});
const client = new ClobClient(
"https://clob.polymarket.com",
137,
signer,
apiCreds,
2,
funderAddress,
undefined,
false,
builderConfig,
);
// Orders automatically include builder headers
const response = await client.createAndPostOrder(/* ... */);
```
```python Python theme={null}
import os
from py_clob_client.client import ClobClient
from py_builder_signing_sdk import BuilderConfig, BuilderApiKeyCreds
builder_creds = BuilderApiKeyCreds(
key=os.environ["POLY_BUILDER_API_KEY"],
secret=os.environ["POLY_BUILDER_SECRET"],
passphrase=os.environ["POLY_BUILDER_PASSPHRASE"],
)
builder_config = BuilderConfig(
local_builder_creds=builder_creds,
)
client = ClobClient(
host="https://clob.polymarket.com",
chain_id=137,
key=private_key,
creds=api_creds,
signature_type=2,
funder=funder_address,
builder_config=builder_config
)
# Orders automatically include builder headers
response = client.create_and_post_order(...)
```
```rust Rust theme={null}
use polymarket_client_sdk::auth::{Credentials, builder::Config as BuilderConfig};
let builder_creds = Credentials::new(
std::env::var("POLY_BUILDER_API_KEY")?.parse()?,
std::env::var("POLY_BUILDER_SECRET")?,
std::env::var("POLY_BUILDER_PASSPHRASE")?,
);
let builder_config = BuilderConfig::local(builder_creds);
let client = client.promote_to_builder(builder_config).await?;
// Orders automatically include builder headers
```
</CodeGroup>
***
## Authentication Headers
The SDK automatically generates and attaches these headers to each request:
| Header | Description |
| ------------------------- | ------------------------------------ |
| `POLY_BUILDER_API_KEY` | Your builder API key |
| `POLY_BUILDER_TIMESTAMP` | Unix timestamp of signature creation |
| `POLY_BUILDER_PASSPHRASE` | Your builder passphrase |
| `POLY_BUILDER_SIGNATURE` | HMAC signature of the request |
<Info>
With **local signing**, the SDK constructs and attaches these headers
automatically. With **remote signing**, your server returns these headers and
the SDK attaches them.
</Info>
Every order placed with `builderCode` attached is credited to your builder profile — no additional configuration needed.
***
## Verifying Attribution
### Get Builder Trades
Query trades attributed to your builder account to verify attribution is working:
Query trades attributed to your builder code:
<CodeGroup>
```typescript TypeScript theme={null}
@@ -317,62 +109,23 @@ Query trades attributed to your builder account to verify attribution is working
market="0xbd31dc8a..."
)
```
```rust Rust theme={null}
use polymarket_client_sdk::clob::types::request::TradesRequest;
let trades = client.builder_trades(&TradesRequest::default(), None).await?;
// Filtered by market
let request = TradesRequest::builder()
.market("0xbd31dc8a...".parse()?)
.build();
let market_trades = client.builder_trades(&request, None).await?;
```
</CodeGroup>
Each `BuilderTrade` includes: `id`, `market`, `assetId`, `side`, `size`, `price`, `status`, `outcome`, `owner`, `maker`, `transactionHash`, `matchTime`, `fee`, and `feeUsdc`.
### Revoke Builder API Key
If your credentials are compromised, revoke them immediately:
<CodeGroup>
```typescript TypeScript theme={null}
await client.revokeBuilderApiKey();
```
```python Python theme={null}
client.revoke_builder_api_key()
```
```rust Rust theme={null}
client.revoke_builder_api_key().await?;
```
</CodeGroup>
After revoking, generate new credentials from your [Builder Profile](https://polymarket.com/settings?tab=builder).
Each `BuilderTrade` includes: `id`, `market`, `assetId`, `side`, `size`, `price`, `status`, `outcome`, `owner`, `maker`, `builder`, `transactionHash`, `matchTime`, `fee`, and `feeUsdc`.
***
## Troubleshooting
<AccordionGroup>
<Accordion title="Invalid Signature Errors">
* Verify the request body is passed correctly as JSON - Check that `path`,
`body`, and `method` match what the client sends - Ensure your server and
client use the same Builder API credentials
<Accordion title="Volume not appearing on the leaderboard">
* Confirm your `builderCode` is correctly attached to every order
* Check that orders are being matched (not just placed)
* Allow up to 24 hours for volume to appear on the leaderboard
</Accordion>
<Accordion title="Missing Credentials">
Ensure your environment variables are set: - `POLY_BUILDER_API_KEY` -
`POLY_BUILDER_SECRET` - `POLY_BUILDER_PASSPHRASE`
</Accordion>
<Accordion title="Volume not appearing on leaderboard">
* Confirm your builder credentials are valid and not revoked - Check that
orders are being placed with the builder config attached - Allow up to 24
hours for volume to appear on the leaderboard
<Accordion title="Invalid builder code">
Verify the code matches what's shown on [your Builder Profile](https://polymarket.com/settings?tab=builder). Builder codes are `bytes32` hex values starting with `0x`.
</Accordion>
</AccordionGroup>
docs/trading/orders/cancel.md
-10
View File
@@ -149,16 +149,6 @@ Cancel all orders for a specific market, optionally filtered to a single token.
***
## Onchain Cancellation
If the API is unavailable, you can cancel orders directly on the [Exchange contract](https://github.com/Polymarket/ctf-exchange/tree/main/src) by calling `cancelOrder(Order order)` onchain. Pass the full order struct that was signed when placing the order.
Use the `CTFExchange` or `NegRiskCTFExchange` contract depending on the market type. See [Contract Addresses](/resources/contract-addresses) for addresses.
This is a fallback mechanism — API cancellation is instant while onchain cancellation requires a transaction.
***
## Querying Orders
### Get a Single Order
docs/trading/orders/create.md
+7 -17
View File
@@ -39,7 +39,7 @@ The simplest way to place a limit order — create, sign, and submit in one call
<CodeGroup>
```typescript TypeScript theme={null}
import { ClobClient, Side, OrderType } from "@polymarket/clob-client";
import { ClobClient, Side, OrderType } from "@polymarket/clob-client-v2";
const response = await client.createAndPostOrder(
{
@@ -238,7 +238,7 @@ Market orders execute immediately against resting liquidity using FOK or FAK typ
<CodeGroup>
```typescript TypeScript theme={null}
import { Side, OrderType } from "@polymarket/clob-client";
import { Side, OrderType } from "@polymarket/clob-client-v2";
// FOK BUY: spend exactly $100 or cancel entirely
const buyOrder = await client.createMarketOrder(
@@ -413,7 +413,7 @@ Place up to **15 orders** in a single request:
<CodeGroup>
```typescript TypeScript theme={null}
import { OrderType, Side, PostOrdersArgs } from "@polymarket/clob-client";
import { OrderType, Side, PostOrdersArgs } from "@polymarket/clob-client-v2";
const orders: PostOrdersArgs[] = [
{
@@ -559,7 +559,7 @@ Multi-outcome events (3+ outcomes) use the Neg Risk CTF Exchange. Pass `negRisk:
Before placing an order, your funder address must have approved the Exchange contract to spend the relevant tokens:
* **BUY orders**: USDC.e allowance >= spending amount
* **BUY orders**: pUSD allowance >= spending amount
* **SELL orders**: conditional token allowance >= selling amount
Order size is limited by your available balance minus amounts reserved by existing open orders:
@@ -569,21 +569,11 @@ $$
$$
<Warning>
Orders are continuously monitored for validity — balances, allowances, and
onchain cancellations are tracked in real time. Any maker caught intentionally
abusing these checks will be blacklisted.
Orders are continuously monitored for validity — balances and allowances are
tracked in real time. Any maker caught intentionally abusing these checks
will be blacklisted.
</Warning>
### Advanced Parameters
These optional fields can be passed in the `UserOrder` object for fine-grained control:
| Parameter | Type | Description |
| ------------ | ------ | ----------------------------------------------- |
| `feeRateBps` | number | Fee rate in basis points (default: market rate) |
| `nonce` | number | Custom nonce for order uniqueness |
| `taker` | string | Restrict the order to a specific taker address |
### Sports Markets
Sports markets have additional behaviors:
docs/trading/orders/overview.md
+14 -15
View File
@@ -8,7 +8,7 @@
All orders on Polymarket are expressed as **limit orders**. Market orders are supported by submitting a limit order with a marketable price — your order executes immediately at the best available price on the book.
The underlying order primitive is structured, hashed, and signed using the [EIP-712](https://eips.ethereum.org/EIPS/eip-712) standard, then executed onchain via the Exchange contract. Preparing orders manually is involved, so we recommend using the open-source [TypeScript](https://github.com/Polymarket/clob-client) or [Python](https://github.com/Polymarket/py-clob-client) SDK clients, which handle signing and submission for you.
The underlying order primitive is structured, hashed, and signed using the [EIP-712](https://eips.ethereum.org/EIPS/eip-712) standard, then executed onchain via the Exchange contract. Preparing orders manually is involved, so we recommend using the open-source [TypeScript](https://github.com/Polymarket/clob-client-v2) or [Python](https://github.com/Polymarket/py-clob-client-v2) SDK clients, which handle signing and submission for you.
<Info>
If you prefer to use the REST API directly, you'll need to manage order
@@ -158,7 +158,7 @@ You can check whether a market uses negative risk via the SDK or the market obje
Before placing an order, your funder address must have approved the Exchange contract to spend the relevant tokens:
* **Buying**: the funder must have set a **USDC.e** allowance greater than or equal to the spending amount.
* **Buying**: the funder must have set a **pUSD** allowance greater than or equal to the spending amount.
* **Selling**: the funder must have set a **conditional token** allowance greater than or equal to the selling amount.
This allows the Exchange contract to execute settlement according to your signed order instructions.
@@ -171,13 +171,12 @@ Orders are continually monitored to make sure they remain valid. This includes t
* Underlying balances
* Allowances
* Onchain order cancellations
<Warning>
Any maker caught intentionally abusing these checks will be blacklisted.
</Warning>
There are also limits on order placement per market. You can only place orders that sum to less than or equal to your available balance for each market. For example, if you have 500 USDC.e in your funding wallet, you can place one order to buy 1000 YES at \$0.50 — but any additional buy orders in that market will be rejected since your entire balance is reserved for the first order.
There are also limits on order placement per market. You can only place orders that sum to less than or equal to your available balance for each market. For example, if you have 500 pUSD in your funding wallet, you can place one order to buy 1000 YES at \$0.50 — but any additional buy orders in that market will be rejected since your entire balance is reserved for the first order.
The max size you can place for an order is:
@@ -475,16 +474,16 @@ Check if your resting orders are eligible for [maker rebates](/market-makers/mak
When a trade is settled onchain, the Exchange contract emits an `OrderFilled` event with the following fields:
| Field | Description |
| ------------------- | ----------------------------------------------------------------------------------------------- |
| `orderHash` | Unique hash for the filled order |
| `maker` | The user who generated the order and source of funds |
| `taker` | The user filling the order, or the Exchange contract if multiple limit orders are filled |
| `makerAssetId` | ID of the asset given out. If `0`, the order is a **BUY** (giving USDC.e for outcome tokens) |
| `takerAssetId` | ID of the asset received. If `0`, the order is a **SELL** (receiving USDC.e for outcome tokens) |
| `makerAmountFilled` | Amount of the asset given out |
| `takerAmountFilled` | Amount of the asset received |
| `fee` | Fees paid by the order maker |
| Field | Description |
| ------------------- | --------------------------------------------------------------------------------------------- |
| `orderHash` | Unique hash for the filled order |
| `maker` | The user who generated the order and source of funds |
| `taker` | The user filling the order, or the Exchange contract if multiple limit orders are filled |
| `makerAssetId` | ID of the asset given out. If `0`, the order is a **BUY** (giving pUSD for outcome tokens) |
| `takerAssetId` | ID of the asset received. If `0`, the order is a **SELL** (receiving pUSD for outcome tokens) |
| `makerAmountFilled` | Amount of the asset given out |
| `takerAmountFilled` | Amount of the asset received |
| `fee` | Fees paid by the order maker |
***
@@ -525,7 +524,7 @@ When an order is successfully placed, the response includes a `status` field:
Polymarket's Exchange contract has been audited by Chainsecurity ([View Audit](https://github.com/Polymarket/ctf-exchange/blob/main/audit/ChainSecurity_Polymarket_Exchange_audit.pdf)).
The operator's privileges are limited to order matching and ensuring correct ordering. Operators cannot set prices or execute unauthorized trades. Users can cancel orders onchain independently if trust issues arise.
The operator's privileges are limited to order matching and ensuring correct ordering. Operators cannot set prices or execute unauthorized trades.
***
docs/trading/overview.md
+19 -19
View File
@@ -6,22 +6,22 @@
> Trading on the Polymarket CLOB
Polymarket's CLOB (Central Limit Order Book) is a hybrid-decentralized trading system — offchain order matching with onchain settlement via the [Exchange contract](https://github.com/Polymarket/ctf-exchange/tree/main/src) ([audited by Chainsecurity](https://github.com/Polymarket/ctf-exchange/blob/main/audit/ChainSecurity_Polymarket_Exchange_audit.pdf)). All trading is non-custodial. Orders are [EIP-712](https://eips.ethereum.org/EIPS/eip-712) signed messages, and matched trades settle atomically on Polygon. The operator cannot set prices or execute unauthorized trades — users can always cancel orders onchain independently.
Polymarket's CLOB (Central Limit Order Book) is a hybrid-decentralized trading system — offchain order matching with onchain settlement via the [Exchange contract](https://github.com/Polymarket/ctf-exchange/tree/main/src) ([audited by Chainsecurity](https://github.com/Polymarket/ctf-exchange/blob/main/audit/ChainSecurity_Polymarket_Exchange_audit.pdf)). All trading is non-custodial. Orders are [EIP-712](https://eips.ethereum.org/EIPS/eip-712) signed messages, and matched trades settle atomically on Polygon. The operator cannot set prices or execute unauthorized trades.
We recommend using the open-source SDK clients, which handle order signing, authentication, and submission:
<CardGroup cols={3}>
<Card title="TypeScript Client" icon="github" href="https://github.com/Polymarket/clob-client">
<Card title="TypeScript Client" icon="github" href="https://github.com/Polymarket/clob-client-v2">
<p className="font-mono text-[0.8rem]">
npm install @polymarket/clob-client
npm install @polymarket/clob-client-v2
</p>
</Card>
<Card title="Python Client" icon="github" href="https://github.com/Polymarket/py-clob-client">
<p className="font-mono text-[0.8rem]">pip install py-clob-client</p>
<Card title="Python Client" icon="github" href="https://github.com/Polymarket/py-clob-client-v2">
<p className="font-mono text-[0.8rem]">pip install py-clob-client-v2</p>
</Card>
<Card title="Rust Client" icon="github" href="https://github.com/Polymarket/rs-clob-client">
<Card title="Rust Client" icon="github" href="https://github.com/Polymarket/rs-clob-client-v2">
<p className="font-mono text-[0.8rem]">cargo add polymarket-client-sdk</p>
</Card>
</CardGroup>
@@ -29,9 +29,9 @@ We recommend using the open-source SDK clients, which handle order signing, auth
<Info>
You can also use the REST API directly, but you'll need to manage [EIP-712
order
signing](https://github.com/Polymarket/clob-client/blob/main/src/signing/eip712.ts)
signing](https://github.com/Polymarket/clob-client-v2/blob/main/src/signing/eip712.ts)
and [HMAC authentication
headers](https://github.com/Polymarket/clob-client/blob/main/src/signing/hmac.ts)
headers](https://github.com/Polymarket/clob-client-v2/blob/main/src/signing/hmac.ts)
yourself. See [REST API Headers](#rest-api-headers) below.
</Info>
@@ -50,13 +50,13 @@ You use your private key once to derive **L2 credentials** (API key, secret, pas
<CodeGroup>
```typescript TypeScript theme={null}
import { ClobClient } from "@polymarket/clob-client";
import { ClobClient } from "@polymarket/clob-client-v2";
import { Wallet } from "ethers"; // v5.8.0
const signer = new Wallet(process.env.PRIVATE_KEY);
// Derive L2 API credentials
const tempClient = new ClobClient("https://clob.polymarket.com", 137, signer);
const tempClient = new ClobClient({ host: "https://clob.polymarket.com", chain: 137, signer });
const apiCreds = await tempClient.createOrDeriveApiKey();
```
@@ -67,7 +67,7 @@ You use your private key once to derive **L2 credentials** (API key, secret, pas
private_key = os.getenv("PRIVATE_KEY")
# Derive L2 API credentials
temp_client = ClobClient("https://clob.polymarket.com", key=private_key, chain_id=137)
temp_client = ClobClient("https://clob.polymarket.com", key=private_key, chain=137)
api_creds = temp_client.create_or_derive_api_creds()
```
@@ -111,21 +111,21 @@ When initializing the trading client, you must specify your wallet's **signature
<CodeGroup>
```typescript TypeScript theme={null}
const client = new ClobClient(
"https://clob.polymarket.com",
137,
const client = new ClobClient({
host: "https://clob.polymarket.com",
chain: 137,
signer,
apiCreds,
2, // GNOSIS_SAFE
"0x...", // Your proxy wallet address
);
creds: apiCreds,
signatureType: 2, // GNOSIS_SAFE
funderAddress: "0x...", // Your proxy wallet address
});
```
```python Python theme={null}
client = ClobClient(
"https://clob.polymarket.com",
key=private_key,
chain_id=137,
chain=137,
creds=api_creds,
signature_type=2, # GNOSIS_SAFE
funder="0x..." # Your proxy wallet address
docs/trading/quickstart.md
+19 -19
View File
@@ -12,11 +12,11 @@ This guide walks you through placing an order on Polymarket end-to-end.
<Step title="Install the SDK">
<CodeGroup>
```bash TypeScript theme={null}
npm install @polymarket/clob-client ethers@5
npm install @polymarket/clob-client-v2 ethers@5
```
```bash Python theme={null}
pip install py-clob-client
pip install py-clob-client-v2
```
```bash Rust theme={null}
@@ -30,7 +30,7 @@ This guide walks you through placing an order on Polymarket end-to-end.
<CodeGroup>
```typescript TypeScript theme={null}
import { ClobClient } from "@polymarket/clob-client";
import { ClobClient } from "@polymarket/clob-client-v2";
import { Wallet } from "ethers"; // v5.8.0
const HOST = "https://clob.polymarket.com";
@@ -38,18 +38,18 @@ This guide walks you through placing an order on Polymarket end-to-end.
const signer = new Wallet(process.env.PRIVATE_KEY);
// Derive API credentials
const tempClient = new ClobClient(HOST, CHAIN_ID, signer);
const tempClient = new ClobClient({ host: HOST, chain: CHAIN_ID, signer });
const apiCreds = await tempClient.createOrDeriveApiKey();
// Initialize trading client
const client = new ClobClient(
HOST,
CHAIN_ID,
const client = new ClobClient({
host: HOST,
chain: CHAIN_ID,
signer,
apiCreds,
0, // EOA
signer.address,
);
creds: apiCreds,
signatureType: 0, // EOA
funderAddress: signer.address,
});
```
```python Python theme={null}
@@ -57,18 +57,18 @@ This guide walks you through placing an order on Polymarket end-to-end.
import os
host = "https://clob.polymarket.com"
chain_id = 137 # Polygon mainnet
chain = 137 # Polygon mainnet
private_key = os.getenv("PRIVATE_KEY")
# Derive API credentials
temp_client = ClobClient(host, key=private_key, chain_id=chain_id)
temp_client = ClobClient(host, key=private_key, chain=chain)
api_creds = temp_client.create_or_derive_api_creds()
# Initialize trading client
client = ClobClient(
host,
key=private_key,
chain_id=chain_id,
chain=chain,
creds=api_creds,
signature_type=0, # EOA
funder="YOUR_WALLET_ADDRESS"
@@ -100,7 +100,7 @@ This guide walks you through placing an order on Polymarket end-to-end.
</Note>
<Warning>
Before trading, your funder address needs **USDC.e** (for buying outcome
Before trading, your funder address needs **pUSD** (for buying outcome
tokens) and **POL** (for gas, if using EOA type `0`). Proxy wallet users
(types `1` and `2`) can use Polymarket's gasless relayer instead.
</Warning>
@@ -111,7 +111,7 @@ This guide walks you through placing an order on Polymarket end-to-end.
<CodeGroup>
```typescript TypeScript theme={null}
import { Side, OrderType } from "@polymarket/clob-client";
import { Side, OrderType } from "@polymarket/clob-client-v2";
const response = await client.createAndPostOrder(
{
@@ -237,7 +237,7 @@ This guide walks you through placing an order on Polymarket end-to-end.
<Accordion title="L2 AUTH NOT AVAILABLE - Invalid Signature">
Wrong private key, signature type, or funder address for the derived API credentials.
* Check that `signatureType` matches your account type (`0`, `1`, or `2`)
* Check that `signatureType` matches your account type (`0`, `1`, `2`, or `3`)
* Ensure `funder` is correct for your wallet type
* Re-derive credentials with `createOrDeriveApiKey()` if unsure
</Accordion>
@@ -245,9 +245,9 @@ This guide walks you through placing an order on Polymarket end-to-end.
<Accordion title="Order rejected - insufficient balance">
Your funder address doesn't have enough tokens:
* **BUY orders**: need USDC.e in your funder address
* **BUY orders**: need pUSD in your funder address
* **SELL orders**: need outcome tokens in your funder address
* Ensure you have more USDC.e than what's committed in open orders
* Ensure you have more pUSD than what's committed in open orders
</Accordion>
<Accordion title="Order rejected - insufficient allowance">