From ff4882db02b851482b62e80362bc64b6262b802e Mon Sep 17 00:00:00 2001 From: Etherdrake Date: Mon, 20 Apr 2026 01:19:37 +0200 Subject: [PATCH] docs: sync with official Polymarket docs - 2026-04-20 --- docs/advanced/neg-risk.md | 2 +- .../bridge/create-deposit-addresses.md | 2 +- docs/api-reference/bridge/get-a-quote.md | 4 +- .../bridge/get-transaction-status.md | 8 +- docs/api-reference/clients-sdks.md | 39 +- .../get-current-rebated-fees-for-a-maker.md | 4 +- .../relayer/submit-a-transaction.md | 2 +- .../get-raw-rewards-for-a-specific-market.md | 2 +- .../api-reference/trade/get-builder-trades.md | 38 +- .../trade/get-single-order-by-id.md | 24 -- docs/api-reference/trade/get-user-orders.md | 24 -- docs/api-reference/trade/post-a-new-order.md | 36 +- .../trade/post-multiple-orders.md | 43 ++- docs/builders/api-keys.md | 130 +++---- docs/builders/overview.md | 34 +- docs/changelog/changelog.md | 200 ---------- docs/concepts/order-lifecycle.md | 11 +- docs/concepts/positions-tokens.md | 14 +- docs/concepts/resolution.md | 6 +- docs/index.md | 6 +- docs/market-makers/getting-started.md | 59 +-- docs/market-makers/inventory.md | 76 ++-- docs/market-makers/overview.md | 18 +- docs/market-makers/trading.md | 18 +- docs/polymarket-101.md | 12 +- docs/quickstart.md | 32 +- docs/quickstart/overview.md | 291 -------------- docs/resources/contract-addresses.md | 106 ------ docs/resources/error-codes.md | 6 +- docs/trading/bridge/deposit.md | 10 +- docs/trading/bridge/quote.md | 2 +- docs/trading/bridge/status.md | 2 +- docs/trading/bridge/supported-assets.md | 2 +- docs/trading/bridge/withdraw.md | 16 +- docs/trading/clients/builder.md | 189 +++------- docs/trading/clients/l1.md | 62 +-- docs/trading/clients/l2.md | 42 +-- docs/trading/clients/public.md | 97 ++++- docs/trading/ctf/merge.md | 12 +- docs/trading/ctf/overview.md | 24 +- docs/trading/ctf/redeem.md | 12 +- docs/trading/ctf/split.md | 18 +- docs/trading/gasless.md | 321 ++++------------ docs/trading/orderbook.md | 12 +- docs/trading/orders/attribution.md | 355 +++--------------- docs/trading/orders/cancel.md | 10 - docs/trading/orders/create.md | 24 +- docs/trading/orders/overview.md | 29 +- docs/trading/overview.md | 38 +- docs/trading/quickstart.md | 38 +- 50 files changed, 705 insertions(+), 1857 deletions(-) diff --git a/docs/advanced/neg-risk.md b/docs/advanced/neg-risk.md index e7e593e..579d57c 100644 --- a/docs/advanced/neg-risk.md +++ b/docs/advanced/neg-risk.md @@ -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 diff --git a/docs/api-reference/bridge/create-deposit-addresses.md b/docs/api-reference/bridge/create-deposit-addresses.md index 5de286c..4ca5487 100644 --- a/docs/api-reference/bridge/create-deposit-addresses.md +++ b/docs/api-reference/bridge/create-deposit-addresses.md @@ -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: diff --git a/docs/api-reference/bridge/get-a-quote.md b/docs/api-reference/bridge/get-a-quote.md index 57376cc..10970e2 100644 --- a/docs/api-reference/bridge/get-a-quote.md +++ b/docs/api-reference/bridge/get-a-quote.md @@ -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: diff --git a/docs/api-reference/bridge/get-transaction-status.md b/docs/api-reference/bridge/get-transaction-status.md index 238c519..f4c340d 100644 --- a/docs/api-reference/bridge/get-transaction-status.md +++ b/docs/api-reference/bridge/get-transaction-status.md @@ -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: > diff --git a/docs/api-reference/clients-sdks.md b/docs/api-reference/clients-sdks.md index 9429b70..5656870 100644 --- a/docs/api-reference/clients-sdks.md +++ b/docs/api-reference/clients-sdks.md @@ -12,11 +12,11 @@ Polymarket provides official open-source clients in TypeScript, Python, and Rust ```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 ```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: diff --git a/docs/api-reference/rebates/get-current-rebated-fees-for-a-maker.md b/docs/api-reference/rebates/get-current-rebated-fees-for-a-maker.md index c9a14f7..74d3ce3 100644 --- a/docs/api-reference/rebates/get-current-rebated-fees-for-a-maker.md +++ b/docs/api-reference/rebates/get-current-rebated-fees-for-a-maker.md @@ -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 diff --git a/docs/api-reference/relayer/submit-a-transaction.md b/docs/api-reference/relayer/submit-a-transaction.md index 44a0e2a..77e6b30 100644 --- a/docs/api-reference/relayer/submit-a-transaction.md +++ b/docs/api-reference/relayer/submit-a-transaction.md @@ -123,7 +123,7 @@ paths: $ref: '#/components/schemas/SubmitRequest' example: from: '0x6e0c80c90ea6c15917308F820Eac91Ce2724B5b5' - to: '0x2791Bca1f2de4661ED88A30C99A7a9449Aa84174' + to: '0xC011a7E12a19f7B1f670d46F03B03f3342E82DFB' proxyWallet: '0x6d8c4e9aDF5748Af82Dabe2C6225207770d6B4fa' data: 0x... nonce: '60' diff --git a/docs/api-reference/rewards/get-raw-rewards-for-a-specific-market.md b/docs/api-reference/rewards/get-raw-rewards-for-a-specific-market.md index 88afa90..51f7a92 100644 --- a/docs/api-reference/rewards/get-raw-rewards-for-a-specific-market.md +++ b/docs/api-reference/rewards/get-raw-rewards-for-a-specific-market.md @@ -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' diff --git a/docs/api-reference/trade/get-builder-trades.md b/docs/api-reference/trade/get-builder-trades.md index 39369db..cb727f5 100644 --- a/docs/api-reference/trade/get-builder-trades.md +++ b/docs/api-reference/trade/get-builder-trades.md @@ -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 ```` \ No newline at end of file diff --git a/docs/api-reference/trade/get-single-order-by-id.md b/docs/api-reference/trade/get-single-order-by-id.md index df7b79f..5a781a5 100644 --- a/docs/api-reference/trade/get-single-order-by-id.md +++ b/docs/api-reference/trade/get-single-order-by-id.md @@ -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 ```` \ No newline at end of file diff --git a/docs/api-reference/trade/get-user-orders.md b/docs/api-reference/trade/get-user-orders.md index 7eaaa48..b3210d7 100644 --- a/docs/api-reference/trade/get-user-orders.md +++ b/docs/api-reference/trade/get-user-orders.md @@ -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 ```` \ No newline at end of file diff --git a/docs/api-reference/trade/post-a-new-order.md b/docs/api-reference/trade/post-a-new-order.md index 13b6d9f..347ce6d 100644 --- a/docs/api-reference/trade/post-a-new-order.md +++ b/docs/api-reference/trade/post-a-new-order.md @@ -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 diff --git a/docs/api-reference/trade/post-multiple-orders.md b/docs/api-reference/trade/post-multiple-orders.md index fc6fc2a..013c8f9 100644 --- a/docs/api-reference/trade/post-multiple-orders.md +++ b/docs/api-reference/trade/post-multiple-orders.md @@ -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 diff --git a/docs/builders/api-keys.md b/docs/builders/api-keys.md index 649d611..3847a2a 100644 --- a/docs/builders/api-keys.md +++ b/docs/builders/api-keys.md @@ -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 Click your profile image → Select "Builders" -## 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` | - - - The `secret` and `passphrase` are only displayed once when created. If you - lose them, you'll need to generate a new key. - - -## Managing Keys - -Create separate keys for different environments: - -| Environment | Purpose | -| ----------- | ----------------------------- | -| Development | Testing and local development | -| Staging | Pre-production testing | -| Production | Live trading | + + 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. + ## 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: ```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 ``` ```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!; ``` ```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"], - ) - ``` - - - - ```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"] ``` -## 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: - - **Never expose Builder API credentials in client-side code.** Your secret and - passphrase must stay on your server. - + + ```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}, + ) + ``` + + +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 - - **Cause:** The secret and passphrase are only shown once when created. + + **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. @@ -150,7 +132,7 @@ Store your credentials as environment variables: - Configure your client to credit trades to your account. + Attach your builder code to orders for volume credit. diff --git a/docs/builders/overview.md b/docs/builders/overview.md index c0cd24c..e9c5b78 100644 --- a/docs/builders/overview.md +++ b/docs/builders/overview.md @@ -41,12 +41,13 @@ A **builder** is a person, group, or organization that routes orders from users User places an order through your application. - - Your app signs the request with Builder API credentials. + + Your app adds your `builderCode` to the order struct. - 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. @@ -54,7 +55,8 @@ A **builder** is a person, group, or organization that routes orders from users - Volume is credited to your builder account. + Volume is credited to your builder account for every matched trade where + your code is attached. @@ -64,12 +66,12 @@ A **builder** is a person, group, or organization that routes orders from users Go to [polymarket.com/settings?tab=builder](https://polymarket.com/settings?tab=builder) - and generate your API keys. + and copy your builder code. - - Set up your CLOB client to include builder authentication headers with every - order. + + Pass `builderCode` on every order you submit — see [Order + Attribution](/trading/orders/attribution). @@ -86,11 +88,11 @@ A **builder** is a person, group, or organization that routes orders from users ## SDKs and Libraries - + Place orders with builder attribution - + Place orders with builder attribution @@ -102,17 +104,9 @@ A **builder** is a person, group, or organization that routes orders from users Gasless onchain transactions - + Place orders with builder attribution - - - Sign builder authentication headers - - - - Sign builder authentication headers - ## Examples @@ -177,7 +171,7 @@ For existing Magic Link users from Polymarket.com: * 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 diff --git a/docs/changelog/changelog.md b/docs/changelog/changelog.md index 55fe553..e69de29 100644 --- a/docs/changelog/changelog.md +++ b/docs/changelog/changelog.md @@ -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. - - - 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. - - - - * **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). - - - - * **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. - - - - * **`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`. - - - - * **Fee calculation source**: Fees should now be calculated using the `feeSchedule` object within a market. - - - - * **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). - - - - * **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) - - - - * **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. - - - - * **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. - - - - * **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. - - - - * **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. - - - - * RTDS docs updated to reflect RTDS supports **comments** and **crypto prices** only. - * Removed legacy CLOB references and `clob_auth` from RTDS docs. - - - - * **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. - - - - * **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 - - - - * **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. - - - - * **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). - - - - * 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. - - - - * Reduced maximum values for query parameters on Data-API /trades and /activity: - * `limit`: 500 - * `offset`: 1,000 - - - - * The batch orders limit has been increased from 5 -> 15. Read more about the batch orders functionality [here](/trading/orders/create). - - - - * 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. - - - - * 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. - - - - * 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. - - - - * 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` - - - - 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. - - - - 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 - diff --git a/docs/concepts/order-lifecycle.md b/docs/concepts/order-lifecycle.md index 5807aa7..32afa58 100644 --- a/docs/concepts/order-lifecycle.md +++ b/docs/concepts/order-lifecycle.md @@ -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. @@ -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. @@ -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 | diff --git a/docs/concepts/positions-tokens.md b/docs/concepts/positions-tokens.md index 7ab3b59..6086a1b 100644 --- a/docs/concepts/positions-tokens.md +++ b/docs/concepts/positions-tokens.md @@ -27,15 +27,15 @@ Tokens are **ERC1155** assets on Polygon, using the [Gnosis Conditional Token Fr 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. ### 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 diff --git a/docs/concepts/resolution.md b/docs/concepts/resolution.md index d03bb1c..f5d0251 100644 --- a/docs/concepts/resolution.md +++ b/docs/concepts/resolution.md @@ -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 diff --git a/docs/index.md b/docs/index.md index 611dcc1..4d1098e 100644 --- a/docs/index.md +++ b/docs/index.md @@ -67,9 +67,9 @@ export const IconCard = ({ icon, title, description, href, color }) => { ```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} diff --git a/docs/market-makers/getting-started.md b/docs/market-makers/getting-started.md index 6a0b9d1..5297a00 100644 --- a/docs/market-makers/getting-started.md +++ b/docs/market-makers/getting-started.md @@ -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. - - Market makers need USDC.e on Polygon to fund their trading operations. + + 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() ``` @@ -169,9 +170,9 @@ Before you can start market making, you need to complete these one-time setup st ```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() ``` diff --git a/docs/market-makers/inventory.md b/docs/market-makers/inventory.md index 2c9d2f1..dbe7148 100644 --- a/docs/market-makers/inventory.md +++ b/docs/market-makers/inventory.md @@ -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. 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. ```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); ``` -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. ```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?; ``` -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], diff --git a/docs/market-makers/overview.md b/docs/market-makers/overview.md index 960dc68..77bd86e 100644 --- a/docs/market-makers/overview.md +++ b/docs/market-makers/overview.md @@ -21,7 +21,7 @@ Market makers are essential to Polymarket's ecosystem — they provide liquidity - 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. @@ -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) | *** diff --git a/docs/market-makers/trading.md b/docs/market-makers/trading.md index 2a993b2..be34a29 100644 --- a/docs/market-makers/trading.md +++ b/docs/market-makers/trading.md @@ -22,16 +22,16 @@ The core market making workflow is posting a bid and ask around your fair value. ```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: ``` -See [Cancel Orders](/trading/orders/cancel) for full details including onchain cancellation. +See [Cancel Orders](/trading/orders/cancel) for full details. ### Monitoring Open Orders diff --git a/docs/polymarket-101.md b/docs/polymarket-101.md index 2ff550c..bae1845 100644 --- a/docs/polymarket-101.md +++ b/docs/polymarket-101.md @@ -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. For details on signature types (`EOA`, `POLY_PROXY`, `GNOSIS_SAFE`) and how to diff --git a/docs/quickstart.md b/docs/quickstart.md index b24cf2c..0c7d85a 100644 --- a/docs/quickstart.md +++ b/docs/quickstart.md @@ -77,11 +77,11 @@ Get up and running with the Polymarket API in minutes — fetch market data and ```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 ```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 + }); ``` @@ -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 - 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`). @@ -184,7 +184,7 @@ Get up and running with the Polymarket API in minutes — fetch market data and ```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"); diff --git a/docs/quickstart/overview.md b/docs/quickstart/overview.md index b24cf2c..e69de29 100644 --- a/docs/quickstart/overview.md +++ b/docs/quickstart/overview.md @@ -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. - - - - All data endpoints are public — no API key or authentication needed. Use the markets endpoint to find a market and get its token IDs: - - - - ```bash theme={null} - curl "https://gamma-api.polymarket.com/markets?active=true&closed=false&limit=1" - ``` - - - - ```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] - ``` - - - - ```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] - ``` - - - - ```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] - ``` - - - - 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. - - - - - ```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 - ``` - - - - - Derive API credentials and initialize the trading client: - - - - ```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 - ); - ``` - - - - ```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 - ) - ``` - - - - ```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?; - ``` - - - - - 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. - - - - Before trading, your funder address needs **USDC.e** (for buying outcome - tokens) and **POL** (for gas, if using EOA type `0`). - - - - - Use the `token_id` from Step 1 to place a limit order: - - - - ```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); - ``` - - - - ```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"]) - ``` - - - - ```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); - ``` - - - - - -*** - -## Next Steps - - - - Understand L1/L2 auth, signature types, and API credentials. - - - - Detailed trading guide with order management and troubleshooting. - - - - Strategies for discovering markets by slug, tag, or category. - - - - Understand markets, events, prices, and positions. - - diff --git a/docs/resources/contract-addresses.md b/docs/resources/contract-addresses.md index 7a272ae..e69de29 100644 --- a/docs/resources/contract-addresses.md +++ b/docs/resources/contract-addresses.md @@ -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 - - - - Order matching and settlement contracts - - - - Gnosis Conditional Token Framework (ERC1155) - - - -*** - -## Usage in Code - - - ```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) - ``` - diff --git a/docs/resources/error-codes.md b/docs/resources/error-codes.md index 0c8a543..b31cf59 100644 --- a/docs/resources/error-codes.md +++ b/docs/resources/error-codes.md @@ -205,11 +205,7 @@ These errors are returned when an order passes initial validation but fails duri - `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. - - - - `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. diff --git a/docs/trading/bridge/deposit.md b/docs/trading/bridge/deposit.md index 48ac45c..ecc0c1e 100644 --- a/docs/trading/bridge/deposit.md +++ b/docs/trading/bridge/deposit.md @@ -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 \ -## 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 diff --git a/docs/trading/bridge/quote.md b/docs/trading/bridge/quote.md index cfd0d95..6ada685 100644 --- a/docs/trading/bridge/quote.md +++ b/docs/trading/bridge/quote.md @@ -19,7 +19,7 @@ curl -X POST https://bridge.polymarket.com/quote \ "fromTokenAddress": "0x3c499c542cEF5E3811e1192ce70d8cC03d5c3359", "recipientAddress": "0x17eC161f126e82A8ba337f4022d574DBEaFef575", "toChainId": "137", - "toTokenAddress": "0x2791Bca1f2de4661ED88A30C99A7a9449Aa84174" + "toTokenAddress": "0xC011a7E12a19f7B1f670d46F03B03f3342E82DFB" }' ``` diff --git a/docs/trading/bridge/status.md b/docs/trading/bridge/status.md index 344f581..63dea26 100644 --- a/docs/trading/bridge/status.md +++ b/docs/trading/bridge/status.md @@ -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 diff --git a/docs/trading/bridge/supported-assets.md b/docs/trading/bridge/supported-assets.md index e035a02..e07c49f 100644 --- a/docs/trading/bridge/supported-assets.md +++ b/docs/trading/bridge/supported-assets.md @@ -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 diff --git a/docs/trading/bridge/withdraw.md b/docs/trading/bridge/withdraw.md index 4c97eed..8357f4e 100644 --- a/docs/trading/bridge/withdraw.md +++ b/docs/trading/bridge/withdraw.md @@ -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 - 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. @@ -81,8 +81,8 @@ Withdrawals are **instant** and **free** — Polymarket does not charge withdraw and recipient. - - Transfer USDC.e from your Polymarket wallet to the appropriate deposit + + Transfer pUSD from your Polymarket wallet to the appropriate deposit address. diff --git a/docs/trading/clients/builder.md b/docs/trading/clients/builder.md index b0e76a7..ebe006e 100644 --- a/docs/trading/clients/builder.md +++ b/docs/trading/clients/builder.md @@ -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. - - - - ```typescript TypeScript theme={null} - import { ClobClient } from "@polymarket/clob-client"; - import { BuilderConfig, BuilderApiKeyCreds } from "@polymarket/builder-signing-sdk"; + + ```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 - ) - ``` - - - - - - ```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 - ) - ``` - - - + # 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}, + ) + ``` + - See [Order Attribution](/trading/orders/attribution) for more information on builder signing. + See [Order Attribution](/trading/orders/attribution) for the full attribution flow. *** @@ -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 ``` - - When a `BuilderConfig` is present, the client automatically sends builder headers. If builder auth is unavailable, it falls back to standard L2 headers. - - ```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) ``` @@ -150,7 +99,7 @@ async getOrder(orderID: string): Promise ### 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( - Address of the builder who attributed this trade. + Builder code attributed to this trade. @@ -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 -``` - - - Response from the revocation request. - - -*** - ## See Also @@ -357,7 +292,7 @@ async revokeBuilderApiKey(): Promise - Attribute orders to your builder account. + Attach your builder code to orders for volume credit. diff --git a/docs/trading/clients/l1.md b/docs/trading/clients/l1.md index d871974..85d6da7 100644 --- a/docs/trading/clients/l1.md +++ b/docs/trading/clients/l1.md @@ -13,16 +13,16 @@ L1 methods require the client to initialize with a signer. ```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). - - Optional fee rate in basis points. Optional. - - - - Optional nonce for the order. Optional. - - Optional expiration timestamp for the order. Optional. - - Optional taker address for the order. Optional. - - The tick size used for order validation (CreateOrderOptions). @@ -197,10 +185,6 @@ async createOrder( The signer's address. - - The taker's address in the signed order. - - The token ID in the signed order. @@ -221,14 +205,6 @@ async createOrder( The expiration timestamp as a string. - - The nonce as a string. - - - - The fee rate in basis points as a string. - - The type identifier for the signature scheme used. @@ -266,18 +242,6 @@ async createMarketOrder( Optional price limit for the market order. Optional. - - Optional fee rate in basis points. Optional. - - - - Optional nonce for the order. Optional. - - - - Optional taker address for the order. Optional. - - Optional order type, either FOK (Fill-Or-Kill) or FAK (Fill-And-Kill). Optional. @@ -294,10 +258,6 @@ async createMarketOrder( The signer's address. - - The taker's address in the signed order. - - The token ID in the signed order. @@ -318,14 +278,6 @@ async createMarketOrder( The expiration timestamp as a string. - - The nonce as a string. - - - - The fee rate in basis points as a string. - - The type identifier for the signature scheme used. diff --git a/docs/trading/clients/l2.md b/docs/trading/clients/l2.md index 1d8d9cc..8b1e988 100644 --- a/docs/trading/clients/l2.md +++ b/docs/trading/clients/l2.md @@ -13,7 +13,7 @@ L2 methods require the client to initialize with a signer, signature type, API c ```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). - - Optional fee rate in basis points. - - - - Optional nonce for the order. - - Optional expiration timestamp for the order. - - Optional taker address. - - Tick size for the order. One of `"0.1"`, `"0.01"`, `"0.001"`, `"0.0001"`. @@ -187,18 +175,6 @@ async createAndPostMarketOrder( Optional price hint for the market order. - - Optional fee rate in basis points. - - - - Optional nonce for the order. - - - - Optional taker address. - - Optional order type override. Defaults to FOK. diff --git a/docs/trading/clients/public.md b/docs/trading/clients/public.md index 354425d..a77b5c9 100644 --- a/docs/trading/clients/public.md +++ b/docs/trading/clients/public.md @@ -13,12 +13,12 @@ Public methods require the client to initialize with the host URL and Polygon ch ```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 *** +### 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 +``` + + + The condition ID of the market. + + +**Response (`ClobMarketDetails`)** + + + Game start time (used for sports markets), ISO 8601 timestamp or `null`. + + + + Rewards configuration for the market. + + + + Tokens for this market. Each entry has: + + * `t` (string) — token ID + * `o` (string) — outcome label (e.g. `Yes`, `No`) + + + + Minimum order size. + + + + Minimum tick size (price increment). + + + + Maker base fee in basis points. + + + + Taker base fee in basis points. + + + + Whether RFQ (Request for Quote) is enabled for this market. + + + + Whether taker order delay is enabled. + + + + Whether Blockaid check is enabled. + + + + Fee curve parameters: + + * `r` (number) — fee rate + * `e` (number) — fee curve exponent + * `to` (boolean) — whether fees apply to takers only + + + + Minimum order age in seconds. + + +*** + ### getFeeRateBps Get the fee rate in basis points for a token. @@ -598,6 +669,20 @@ async getFeeRateBps(tokenID: string): Promise *** +### 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 +``` + + + The fee curve exponent for the specified token's market. + + +*** + ### getTickSize Get the tick size (minimum price increment) for a market. diff --git a/docs/trading/ctf/merge.md b/docs/trading/ctf/merge.md index 664a3f2..b287b2b 100644 --- a/docs/trading/ctf/merge.md +++ b/docs/trading/ctf/merge.md @@ -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 - USDC.e (Bridged USDC) contract address: `0x2791Bca1f2de4661ED88A30C99A7a9449Aa84174` + pUSD (Polymarket USD) contract address: `0xC011a7E12a19f7B1f670d46F03B03f3342E82DFB` @@ -54,7 +54,7 @@ The operation is atomic — if you don't have enough of both tokens, the transac - Exchange winning tokens for USDC.e after resolution + Exchange winning tokens for pUSD after resolution diff --git a/docs/trading/ctf/overview.md b/docs/trading/ctf/overview.md index 3e6a76e..110ab18 100644 --- a/docs/trading/ctf/overview.md +++ b/docs/trading/ctf/overview.md @@ -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: - Convert USDC.e into Yes + No token pairs + Convert pUSD into Yes + No token pairs - Convert Yes + No pairs back to USDC.e + Convert Yes + No pairs back to pUSD - Exchange winning tokens for USDC.e after resolution + Exchange winning tokens for pUSD after resolution @@ -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 - Create outcome token pairs from USDC.e + Create outcome token pairs from pUSD - Convert token pairs back to USDC.e + Convert token pairs back to pUSD diff --git a/docs/trading/ctf/redeem.md b/docs/trading/ctf/redeem.md index 40d0539..bc287ca 100644 --- a/docs/trading/ctf/redeem.md +++ b/docs/trading/ctf/redeem.md @@ -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 @@ -44,7 +44,7 @@ Before redeeming: ## Function Parameters - USDC.e (Bridged USDC) contract address: `0x2791Bca1f2de4661ED88A30C99A7a9449Aa84174` + pUSD (Polymarket USD) contract address: `0xC011a7E12a19f7B1f670d46F03B03f3342E82DFB` @@ -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 diff --git a/docs/trading/ctf/split.md b/docs/trading/ctf/split.md index 8869e8c..c9a88ec 100644 --- a/docs/trading/ctf/split.md +++ b/docs/trading/ctf/split.md @@ -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`) @@ -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 - USDC.e (Bridged USDC) contract address: `0x2791Bca1f2de4661ED88A30C99A7a9449Aa84174` + pUSD (Polymarket USD) contract address: `0xC011a7E12a19f7B1f670d46F03B03f3342E82DFB` @@ -60,7 +60,7 @@ The operation is atomic — if any step fails, the entire transaction reverts. - Convert token pairs back to USDC.e + Convert token pairs back to pUSD diff --git a/docs/trading/gasless.md b/docs/trading/gasless.md index b262a96..53c924d 100644 --- a/docs/trading/gasless.md +++ b/docs/trading/gasless.md @@ -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 - - Gasless transactions require authentication with **Builder API Keys** or **Relayer API Keys**. - - ## 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 ```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 ``` ## Client Setup -Initialize the relayer client with your signing configuration: +Initialize the relayer client with your Relayer API Key: - - - Use local signing when your backend handles all transactions securely. + + ```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"; - - ```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 - ) - ``` - - - - - Use remote signing to keep credentials on a secure server you control. - - **Your signing server** receives request details and returns authentication headers: - - - ```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, - } - ``` - - - **Your client** points to your signing server: - - - ```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 - ) - ``` - - - + 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"], + ) + ``` + - 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. @@ -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 ``` @@ -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() ``` ### Redeem Positions -Exchange winning tokens for USDC.e after market resolution: +Exchange winning tokens for pUSD after market resolution: ```typescript TypeScript theme={null} @@ -483,7 +324,7 @@ Execute multiple operations atomically in a single call: ```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 diff --git a/docs/trading/orderbook.md b/docs/trading/orderbook.md index 9c55291..4aa5ef3 100644 --- a/docs/trading/orderbook.md +++ b/docs/trading/orderbook.md @@ -10,15 +10,15 @@ The orderbook is a public endpoint — no authentication required. You can read ```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: ```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 ```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 ```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([ diff --git a/docs/trading/orders/attribution.md b/docs/trading/orders/attribution.md index 3a9ea49..99f740f 100644 --- a/docs/trading/orders/attribution.md +++ b/docs/trading/orders/attribution.md @@ -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. - - 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. - + + 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. + *** -## 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. ```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, - } - ``` - - -### Client Configuration - -Point the CLOB client to your signing server: - - - ```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, + ) ``` -*** - -## Local Signing - -Sign orders locally when you control the entire order placement flow (e.g., your backend places orders on behalf of users): - - - ```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 - ``` - - -*** - -## 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 | - - - With **local signing**, the SDK constructs and attaches these headers - automatically. With **remote signing**, your server returns these headers and - the SDK attaches them. - +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: ```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?; - ``` -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: - - - ```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?; - ``` - - -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 - - * 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 + + * 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 - - Ensure your environment variables are set: - `POLY_BUILDER_API_KEY` - - `POLY_BUILDER_SECRET` - `POLY_BUILDER_PASSPHRASE` - - - - * 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 + + 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`. diff --git a/docs/trading/orders/cancel.md b/docs/trading/orders/cancel.md index 1a09c68..6b6b1ad 100644 --- a/docs/trading/orders/cancel.md +++ b/docs/trading/orders/cancel.md @@ -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 diff --git a/docs/trading/orders/create.md b/docs/trading/orders/create.md index 300b915..330ac59 100644 --- a/docs/trading/orders/create.md +++ b/docs/trading/orders/create.md @@ -39,7 +39,7 @@ The simplest way to place a limit order — create, sign, and submit in one call ```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 ```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: ```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 @@ $$ $$ - 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. -### 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: diff --git a/docs/trading/orders/overview.md b/docs/trading/orders/overview.md index cfe85ac..0c6954f 100644 --- a/docs/trading/orders/overview.md +++ b/docs/trading/orders/overview.md @@ -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. 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 Any maker caught intentionally abusing these checks will be blacklisted. -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. *** diff --git a/docs/trading/overview.md b/docs/trading/overview.md index b2e3a56..ceb401a 100644 --- a/docs/trading/overview.md +++ b/docs/trading/overview.md @@ -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: - +

- npm install @polymarket/clob-client + npm install @polymarket/clob-client-v2

- -

pip install py-clob-client

+ +

pip install py-clob-client-v2

 - +

cargo add polymarket-client-sdk

 @@ -29,9 +29,9 @@ We recommend using the open-source SDK clients, which handle order signing, auth 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. @@ -50,13 +50,13 @@ You use your private key once to derive **L2 credentials** (API key, secret, pas ```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 ```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 diff --git a/docs/trading/quickstart.md b/docs/trading/quickstart.md index f00df25..d2f65de 100644 --- a/docs/trading/quickstart.md +++ b/docs/trading/quickstart.md @@ -12,11 +12,11 @@ This guide walks you through placing an order on Polymarket end-to-end. ```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. ```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. - 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. @@ -111,7 +111,7 @@ This guide walks you through placing an order on Polymarket end-to-end. ```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. 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 @@ -245,9 +245,9 @@ This guide walks you through placing an order on Polymarket end-to-end. 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