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

docs: sync with docs.polymarket.com - 2026-05-08

Browse Source
This commit is contained in:
Etherdrake
2026-05-08 14:59:53 +02:00
parent 2ac62926d8
commit a61457d6fa
227 changed files with 374 additions and 20740 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/trading/bridge/deposit.md
+2 -3
View File
@@ -81,10 +81,9 @@ Each asset has a minimum deposit amount. Deposits below the minimum will not be
## Deposit Recovery
If you deposited the wrong token on Ethereum or Polygon, use these tools to recover your funds:
If you deposited the wrong token, use this tool to recover your funds:
* **Ethereum deposits**: [recovery.polymarket.com](https://recovery.polymarket.com/)
* **Polygon deposits**: [matic-recovery.polymarket.com](https://matic-recovery.polymarket.com/)
[recovery.polymarket.com](https://recovery.polymarket.com/)
<Warning>
Sending unsupported tokens may cause **irrecoverable loss**. Always verify
docs/trading/bridge/overview.md
+1 -1
View File
@@ -1 +1 @@
null
null
docs/trading/clients/l1.md
+11 -5
View File
@@ -51,7 +51,8 @@ L1 methods require the client to initialize with a signer.
</Tabs>
<Warning>
Never commit private keys to version control. Always use environment variables or a secure key management system.
Never commit private keys to version control. Always use environment variables
or a secure key management system.
</Warning>
***
@@ -256,7 +257,8 @@ async createMarketOrder(
</ResponseField>
<ResponseField name="amount" type="number">
The order amount. For BUY orders this is a dollar amount; for SELL orders this is the number of shares.
The order amount. For BUY orders this is a dollar amount; for SELL orders this
is the number of shares.
</ResponseField>
<ResponseField name="side" type="Side">
@@ -268,7 +270,8 @@ async createMarketOrder(
</ResponseField>
<ResponseField name="orderType" type="OrderType.FOK | OrderType.FAK">
Optional order type, either FOK (Fill-Or-Kill) or FAK (Fill-And-Kill). Optional.
Optional order type, either FOK (Fill-Or-Kill) or FAK (Fill-And-Kill).
Optional.
</ResponseField>
<ResponseField name="salt" type="string">
@@ -353,12 +356,15 @@ async createMarketOrder(
<Accordion title="Error - Invalid Funder Address">
Your funder address is incorrect or doesn't match your wallet.
**Solution:** Check your proxy wallet address at [polymarket.com/settings](https://polymarket.com/settings). If it doesn't exist, the user has never logged in to Polymarket.com — deploy the proxy wallet first before creating L2 credentials.
**Solution:** New API users should use the deposit wallet address as the
funder with signature type `3`. Existing Safe and Proxy users should use
their current smart-wallet address.
</Accordion>
<Accordion title="Lost API credentials but have nonce">
Use `deriveApiKey()` with the original nonce:
```typescript theme={null}
// Use deriveApiKey with the original nonce
const recovered = await client.deriveApiKey(originalNonce);
```
</Accordion>
docs/trading/clients/l2.md
+7 -5
View File
@@ -25,14 +25,15 @@ L2 methods require the client to initialize with a signer, signature type, API c
secret: process.env.SECRET,
passphrase: process.env.PASSPHRASE,
};
const depositWalletAddress = process.env.DEPOSIT_WALLET_ADDRESS!;
const client = new ClobClient({
host: "https://clob.polymarket.com",
chain: 137,
signer,
creds: apiCreds,
signatureType: 2, // GNOSIS_SAFE
funderAddress: process.env.FUNDER_ADDRESS,
signatureType: 3, // POLY_1271
funderAddress: depositWalletAddress,
});
// Ready to send authenticated requests
@@ -57,8 +58,8 @@ L2 methods require the client to initialize with a signer, signature type, API c
chain_id=137,
key=os.getenv("PRIVATE_KEY"),
creds=api_creds,
signature_type=2, # GNOSIS_SAFE
funder=os.getenv("FUNDER_ADDRESS")
signature_type=3, # POLY_1271
funder=os.getenv("DEPOSIT_WALLET_ADDRESS")
)
# Ready to send authenticated requests
@@ -518,7 +519,8 @@ async getTrades(
</ResponseField>
<ResponseField name="maker_orders" type="MakerOrder[]">
Array of maker order objects that participated in this trade. Each `MakerOrder` contains the following fields:
Array of maker order objects that participated in this trade. Each
`MakerOrder` contains the following fields:
</ResponseField>
<ResponseField name="maker_orders[].order_id" type="string">
docs/trading/fees.md
+21 -21
View File
@@ -32,7 +32,7 @@ Where **C** = number of shares traded and **p** = price of the shares.
| Category | Taker Fee Rate | Maker Fee Rate | Maker Rebate |
| --------------- | -------------- | -------------- | ------------ |
| Crypto | 0.072 | 0 | 20% |
| Crypto | 0.07 | 0 | 20% |
| Sports | 0.03 | 0 | 25% |
| Finance | 0.04 | 0 | 25% |
| Politics | 0.04 | 0 | 25% |
@@ -59,28 +59,28 @@ Taker fees are calculated in USDC and vary based on the share price. The fee amo
| Price | Trade Value | Taker Fee (USDC) |
| ------ | ----------- | ---------------- |
| \$0.01 | \$1 | \$0.07 |
| \$0.05 | \$5 | \$0.34 |
| \$0.10 | \$10 | \$0.65 |
| \$0.15 | \$15 | \$0.92 |
| \$0.20 | \$20 | \$1.15 |
| \$0.25 | \$25 | \$1.35 |
| \$0.30 | \$30 | \$1.51 |
| \$0.35 | \$35 | \$1.64 |
| \$0.40 | \$40 | \$1.73 |
| \$0.45 | \$45 | \$1.78 |
| \$0.50 | \$50 | \$1.80 |
| \$0.55 | \$55 | \$1.78 |
| \$0.60 | \$60 | \$1.73 |
| \$0.65 | \$65 | \$1.64 |
| \$0.70 | \$70 | \$1.51 |
| \$0.75 | \$75 | \$1.35 |
| \$0.80 | \$80 | \$1.15 |
| \$0.85 | \$85 | \$0.92 |
| \$0.90 | \$90 | \$0.65 |
| \$0.95 | \$95 | \$0.34 |
| \$0.05 | \$5 | \$0.33 |
| \$0.10 | \$10 | \$0.63 |
| \$0.15 | \$15 | \$0.89 |
| \$0.20 | \$20 | \$1.12 |
| \$0.25 | \$25 | \$1.31 |
| \$0.30 | \$30 | \$1.47 |
| \$0.35 | \$35 | \$1.59 |
| \$0.40 | \$40 | \$1.68 |
| \$0.45 | \$45 | \$1.73 |
| \$0.50 | \$50 | \$1.75 |
| \$0.55 | \$55 | \$1.73 |
| \$0.60 | \$60 | \$1.68 |
| \$0.65 | \$65 | \$1.59 |
| \$0.70 | \$70 | \$1.47 |
| \$0.75 | \$75 | \$1.31 |
| \$0.80 | \$80 | \$1.12 |
| \$0.85 | \$85 | \$0.89 |
| \$0.90 | \$90 | \$0.63 |
| \$0.95 | \$95 | \$0.33 |
| \$0.99 | \$99 | \$0.07 |
The fee in USDC **peaks at 50%** probability (\$1.80) and decreases symmetrically toward both extremes.
The fee in USDC **peaks at 50%** probability (\$1.75) and decreases symmetrically toward both extremes.
</Tab>
<Tab title="Sports">
docs/trading/gasless.md
+20 -8
View File
@@ -24,7 +24,7 @@ Polymarket pays gas for all operations routed through the relayer:
| Operation | Description |
| --------------------- | ------------------------------------------------- |
| **Wallet deployment** | Deploy Safe or Proxy wallets for new users |
| **Wallet deployment** | Deploy deposit wallets for new API users |
| **Token approvals** | Approve contracts to spend pUSD or outcome tokens |
| **CTF operations** | Split, merge, and redeem positions |
| **Transfers** | Move tokens between addresses |
@@ -34,7 +34,10 @@ Polymarket pays gas for all operations routed through the relayer:
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.
<Note>
**Already have a builder signing key?** Your existing HMAC-based builder API key keeps working with the Relayer — no need to rotate or reissue. Only order-signing moved to the native `builderCode` field in CLOB V2. See [Migrating to CLOB V2](/v2-migration#builder-program) for context.
**Already have a builder signing key?** Your existing HMAC-based builder API
key keeps working with the Relayer — no need to rotate or reissue. Order
attribution is now associated with the native `builderCode` field in CLOB V2.
See [Migrating to CLOB V2](/v2-migration#builder-program) for context.
</Note>
Include these headers with your requests:
@@ -45,7 +48,8 @@ Include these headers with your requests:
| `RELAYER_API_KEY_ADDRESS` | The address that owns the key |
<Info>
If you want to use the Relayer API Key directly without the SDK, see the [Relayer API Reference](/api-reference/relayer).
If you want to use the Relayer API Key directly without the SDK, see the
[Relayer API Reference](/api-reference/relayer).
</Info>
## Prerequisites
@@ -118,12 +122,20 @@ Initialize the relayer client with your Relayer API Key:
## Wallet Types
Choose a wallet type when initializing the client:
Use deposit wallets for new API users. Existing Safe and Proxy users can keep
using their current wallet type and signature flow.
| Type | Deployment | Best For |
| --------- | ---------------------------------------- | ------------------------- |
| **Safe** | Call `deploy()` before first transaction | Most builder integrations |
| **Proxy** | Auto-deploys on first transaction | Magic Link users |
| Type | Deployment | Best For |
| ------------------ | ---------------------------------------- | ----------------------------------- |
| **Deposit Wallet** | Call `deployDepositWallet()` | New API users |
| **Safe** | Call `deploy()` before first transaction | Existing Safe integrations |
| **Proxy** | Auto-deploys on first transaction | Existing Polymarket.com proxy users |
<Info>
For the new deposit wallet flow, including `WALLET-CREATE`, signed `WALLET`
batches, and `POLY_1271` CLOB orders, see the [Deposit Wallet
Guide](/trading/deposit-wallets).
</Info>
<CodeGroup>
```typescript Safe Wallet (TypeScript) theme={null}
docs/trading/orders/attribution.md
+15 -9
View File
@@ -21,7 +21,9 @@ Your **builder code** is a `bytes32` identifier tied to your builder profile. Fi
That's the only credential you need for attribution — no HMAC signing, no separate API key, no special headers.
<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.
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>
***
@@ -39,8 +41,8 @@ Pass `builderCode` in the order struct on every order you submit. The SDK serial
chain: 137,
signer,
creds: apiCreds,
signatureType: 2,
funderAddress,
signatureType: 3,
funderAddress: depositWalletAddress,
});
const response = await client.createAndPostOrder(
@@ -66,8 +68,8 @@ Pass `builderCode` in the order struct on every order you submit. The SDK serial
chain_id=137,
key=private_key,
creds=api_creds,
signature_type=2,
funder=funder_address,
signature_type=3,
funder=deposit_wallet_address,
)
response = client.create_and_post_order(
@@ -119,13 +121,17 @@ Each `BuilderTrade` includes: `id`, `market`, `assetId`, `side`, `size`, `price`
<AccordionGroup>
<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
<ul>
<li>Confirm your `builderCode` is correctly attached to every order</li>
<li>Check that orders are being matched, not just placed</li>
<li>Allow up to 24 hours for volume to appear on the leaderboard</li>
</ul>
</Accordion>
<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`.
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/create.md
+12 -7
View File
@@ -10,9 +10,10 @@ All orders on Polymarket are expressed as **limit orders**. Market orders are su
<Info>
The SDK handles EIP-712 signing and submission for you. If you prefer the REST
API directly, see [Authentication](/api-reference/authentication) for constructing the
required headers and the [API Reference](/api-reference/introduction) for full endpoint
documentation including the raw order object fields and request/response schemas.
API directly, see [Authentication](/api-reference/authentication) for
constructing the required headers and the [API
Reference](/api-reference/introduction) for full endpoint documentation
including the raw order object fields and request/response schemas.
</Info>
***
@@ -501,7 +502,10 @@ Place up to **15 orders** in a single request:
## Order Options
Every order requires two market-specific options: `tickSize` and `negRisk`. For details on signature types (`0` = EOA, `1` = POLY\_PROXY, `2` = GNOSIS\_SAFE), see [Authentication](/api-reference/authentication#signature-types-and-funder).
Every order requires two market-specific options: `tickSize` and `negRisk`. For
details on signature types (`0` = EOA, `1` = POLY\_PROXY, `2` = GNOSIS\_SAFE,
`3` = POLY\_1271 deposit wallet), see
[Authentication](/api-reference/authentication#signature-types-and-funder).
### Tick Sizes
@@ -550,7 +554,8 @@ Multi-outcome events (3+ outcomes) use the Neg Risk CTF Exchange. Pass `negRisk:
<Tip>
Both values are also available on the market object: `minimum_tick_size` and
`neg_risk`. In Rust, the order builder auto-fetches both — you don't need to look them up manually.
`neg_risk`. In Rust, the order builder auto-fetches both — you don't need to
look them up manually.
</Tip>
***
@@ -570,8 +575,8 @@ $$
<Warning>
Orders are continuously monitored for validity — balances and allowances are
tracked in real time. Any maker caught intentionally abusing these checks
will be blacklisted.
tracked in real time. Any maker caught intentionally abusing these checks will
be blacklisted.
</Warning>
### Sports Markets
docs/trading/overview.md
+29 -15
View File
@@ -22,7 +22,9 @@ We recommend using the open-source SDK clients, which handle order signing, auth
</Card>
<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\_v2 --features clob</p>
<p className="font-mono text-[0.8rem]">
cargo add polymarket\_client\_sdk\_v2 --features clob
</p>
</Card>
</CardGroup>
@@ -58,7 +60,11 @@ You use your private key once to derive **L2 credentials** (API key, secret, pas
const signer = createWalletClient({ account, transport: http() });
// Derive L2 API credentials
const tempClient = new ClobClient({ host: "https://clob.polymarket.com", chain: 137, signer });
const tempClient = new ClobClient({
host: "https://clob.polymarket.com",
chain: 137,
signer,
});
const apiCreds = await tempClient.createOrDeriveApiKey();
```
@@ -97,49 +103,57 @@ You use your private key once to derive **L2 credentials** (API key, secret, pas
When initializing the trading client, you must specify your wallet's **signature type** and **funder address**:
| Wallet Type | ID | When to Use | Funder Address |
| ---------------- | --- | -------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------- |
| **EOA** | `0` | Standalone wallet — you pay your own gas (POL for gas) | Your EOA wallet address |
| **POLY\_PROXY** | `1` | Polymarket account via Magic Link (email/Google login). Requires [exported private key](https://polymarket.com/settings) from Polymarket.com | Your proxy wallet address |
| **GNOSIS\_SAFE** | `2` | Polymarket account via browser wallet (MetaMask, Rabby) or embedded wallet (Privy, Turnkey). Most common type | Your proxy wallet address |
| Wallet Type | ID | When to Use | Funder Address |
| ---------------- | --- | -------------------------------------------------------------------------------------------------------------- | --------------------------- |
| **EOA** | `0` | Standalone wallet — you pay your own gas (POL for gas) | Your EOA wallet address |
| **POLY\_PROXY** | `1` | Existing Polymarket proxy wallet flow | Your proxy wallet address |
| **GNOSIS\_SAFE** | `2` | Existing Gnosis Safe wallet flow | Your Safe wallet address |
| **POLY\_1271** | `3` | Deposit wallet flow for new API users. Orders are signed by the owner/session signer and validated by ERC-1271 | Your deposit wallet address |
<Note>
If you have a Polymarket.com account, your funds are in a proxy wallet visible
in the profile dropdown. Use type `1` or `2`. Type `0` is for standalone EOA
wallets only.
New API users should use deposit wallets with signature type `3`. Existing
Proxy and Safe users are unaffected and can keep using signature types `1` and
`2`. Type `0` is for standalone EOA wallets only.
</Note>
### Initialize the Trading Client
<CodeGroup>
```typescript TypeScript theme={null}
const depositWalletAddress = process.env.DEPOSIT_WALLET_ADDRESS!;
const client = new ClobClient({
host: "https://clob.polymarket.com",
chain: 137,
signer,
creds: apiCreds,
signatureType: 2, // GNOSIS_SAFE
funderAddress: "0x...", // Your proxy wallet address
signatureType: 3, // POLY_1271
funderAddress: depositWalletAddress,
});
```
```python Python theme={null}
deposit_wallet_address = os.getenv("DEPOSIT_WALLET_ADDRESS")
client = ClobClient(
"https://clob.polymarket.com",
key=private_key,
chain_id=137,
creds=api_creds,
signature_type=2, # GNOSIS_SAFE
funder="0x..." # Your proxy wallet address
signature_type=3, # POLY_1271
funder=deposit_wallet_address
)
```
```rust Rust theme={null}
use polymarket_client_sdk_v2::clob::types::SignatureType;
let deposit_wallet = std::env::var("DEPOSIT_WALLET_ADDRESS")?.parse()?;
let client = Client::new("https://clob.polymarket.com", Config::default())?
.authentication_builder(&signer)
.signature_type(SignatureType::GnosisSafe) // Funder auto-derived via CREATE2
.funder(deposit_wallet)
.signature_type(SignatureType::Poly1271)
.authenticate()
.await?;
```
docs/trading/quickstart.md
+31 -19
View File
@@ -26,11 +26,13 @@ This guide walks you through placing an order on Polymarket end-to-end.
</Step>
<Step title="Set Up Your Client">
Derive your API credentials and initialize the trading client. This example uses an EOA wallet (type `0`) — your wallet pays its own gas and acts as the funder:
Derive your API credentials and initialize the trading client. This example uses
a deposit wallet with signature type `3` (`POLY_1271`), which is the wallet path
for new API users:
<CodeGroup>
```typescript TypeScript theme={null}
import { ClobClient } from "@polymarket/clob-client-v2";
import { ClobClient, SignatureTypeV2 } from "@polymarket/clob-client-v2";
import { createWalletClient, http } from "viem";
import { privateKeyToAccount } from "viem/accounts";
@@ -38,6 +40,7 @@ This guide walks you through placing an order on Polymarket end-to-end.
const CHAIN_ID = 137; // Polygon mainnet
const account = privateKeyToAccount(process.env.PRIVATE_KEY as `0x${string}`);
const signer = createWalletClient({ account, transport: http() });
const depositWalletAddress = process.env.DEPOSIT_WALLET_ADDRESS!;
// Derive API credentials
const tempClient = new ClobClient({ host: HOST, chain: CHAIN_ID, signer });
@@ -49,18 +52,19 @@ This guide walks you through placing an order on Polymarket end-to-end.
chain: CHAIN_ID,
signer,
creds: apiCreds,
signatureType: 0, // EOA
funderAddress: account.address,
signatureType: SignatureTypeV2.POLY_1271,
funderAddress: depositWalletAddress,
});
```
```python Python theme={null}
from py_clob_client_v2 import ClobClient
from py_clob_client_v2 import ClobClient, SignatureTypeV2
import os
host = "https://clob.polymarket.com"
chain = 137 # Polygon mainnet
private_key = os.getenv("PRIVATE_KEY")
deposit_wallet_address = os.getenv("DEPOSIT_WALLET_ADDRESS")
# Derive API credentials
temp_client = ClobClient(host, key=private_key, chain_id=chain)
@@ -72,8 +76,8 @@ This guide walks you through placing an order on Polymarket end-to-end.
key=private_key,
chain_id=chain,
creds=api_creds,
signature_type=0, # EOA
funder="YOUR_WALLET_ADDRESS"
signature_type=SignatureTypeV2.POLY_1271,
funder=deposit_wallet_address
)
```
@@ -81,30 +85,35 @@ This guide walks you through placing an order on Polymarket end-to-end.
use std::str::FromStr;
use polymarket_client_sdk_v2::POLYGON;
use polymarket_client_sdk_v2::auth::{LocalSigner, Signer};
use polymarket_client_sdk_v2::clob::types::SignatureType;
use polymarket_client_sdk_v2::clob::{Client, Config};
let private_key = std::env::var("POLYMARKET_PRIVATE_KEY")?;
let signer = LocalSigner::from_str(&private_key)?
.with_chain_id(Some(POLYGON));
let deposit_wallet = std::env::var("DEPOSIT_WALLET_ADDRESS")?.parse()?;
// Derive API credentials and initialize client (EOA by default)
// Derive API credentials and initialize client
let client = Client::new("https://clob.polymarket.com", Config::default())?
.authentication_builder(&signer)
.funder(deposit_wallet)
.signature_type(SignatureType::Poly1271)
.authenticate()
.await?;
```
</CodeGroup>
<Note>
If you have a Polymarket.com account, your funds are in a proxy wallet — use
signature type `1` or `2` instead. See [Signature
Types](/trading/overview#signature-types) for details.
Existing EOA, Safe, and Proxy integrations can keep using their current
signature type and funder address. See [Signature
Types](/trading/overview#signature-types) for all wallet types.
</Note>
<Warning>
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.
Before trading from a deposit wallet, the deposit wallet needs **pUSD** and
the required trading approvals. See the [Deposit Wallet
Guide](/trading/deposit-wallets) for wallet creation, funding, approvals, and
balance sync.
</Warning>
</Step>
@@ -253,18 +262,21 @@ This guide walks you through placing an order on Polymarket end-to-end.
</Accordion>
<Accordion title="Order rejected - insufficient allowance">
You need to approve the Exchange contract to spend your tokens. This is
typically done through the Polymarket UI on your first trade, or using the CTF
contract's `setApprovalForAll()` method.
You need to approve the Exchange contract to spend your tokens. Deposit wallet
approvals must be executed from the deposit wallet through a relayer `WALLET`
batch. Existing Safe and Proxy users should use their current relayer approval
flow.
</Accordion>
<Accordion title="What is my funder address">
Your funder address is the wallet where your funds are held:
* **EOA (type 0)**: Your wallet address directly
* **Proxy wallet (type 1 or 2)**: Go to [polymarket.com/settings](https://polymarket.com/settings) and look for the wallet address in the profile dropdown
* **Deposit wallet (type 3)**: The deposit wallet deployed for the owner or session signer
* **Proxy/Safe wallet (type 1 or 2)**: Existing Polymarket.com wallet address
If the proxy wallet doesn't exist, log into Polymarket.com first (it's deployed on first login).
New API users should create a deposit wallet. Existing Proxy and Safe users
can continue using their current wallet address.
</Accordion>
<Accordion title="Blocked by Cloudflare or Geoblock">