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/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.