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

docs/api-reference/builders/get-aggregated-builder-leaderboard.md

@@ -93,6 +93,12 @@ components:
         builder:
           type: string
           description: The builder name or identifier
+        builderCode:
+          type: string
+          description: >-
+            The builder's onchain attribution code as attached to orders via
+            `builderCode` (see CLOB V2). Empty string for legacy builders
+            without a registered code.
         volume:
           type: number
           description: Total trading volume attributed to this builder

docs/api-reference/builders/get-daily-builder-volume-time-series.md

@@ -79,6 +79,12 @@ components:
         builder:
           type: string
           description: The builder name or identifier
+        builderCode:
+          type: string
+          description: >-
+            The builder's onchain attribution code as attached to orders via
+            `builderCode` (see CLOB V2). Empty string for legacy builders
+            without a registered code.
         builderLogo:
           type: string
           description: URL to the builder's logo image

docs/api-reference/data/get-midpoint-price.md

@@ -101,5 +101,11 @@ components:
         error:
           type: string
           description: Error message
+        code:
+          type: string
+          description: Machine-readable error code, when provided
+        retry_after_seconds:
+          type: integer
+          description: Number of seconds to wait before retrying, when provided
 
 ````

docs/api-reference/data/get-server-time.md

@@ -77,5 +77,11 @@ components:
         error:
           type: string
           description: Error message
+        code:
+          type: string
+          description: Machine-readable error code, when provided
+        retry_after_seconds:
+          type: integer
+          description: Number of seconds to wait before retrying, when provided
 
 ````

docs/api-reference/geoblock.md

@@ -119,7 +119,7 @@ The geoblocking system includes:
 
 <Tip>
   **Direct co-location available.** Users who complete the [KYC/KYB
-  form](https://forms.gle/Qy39FtiizodXbdLNA) can get access to co-locate
+  form](https://docs.google.com/forms/d/e/1FAIpQLSfY-3Dl3yxq8HKFjFad8YzKZmm0k3Gdg29HD6gL-K-AmI6KXw/viewform) can get access to co-locate
   directly in `eu-west-2` for the lowest possible latency to Polymarket's
   primary servers.
 </Tip>

docs/api-reference/market-data/get-fee-rate-by-path-parameter.md

@@ -111,5 +111,11 @@ components:
         error:
           type: string
           description: Error message
+        code:
+          type: string
+          description: Machine-readable error code, when provided
+        retry_after_seconds:
+          type: integer
+          description: Number of seconds to wait before retrying, when provided
 
 ````

docs/api-reference/market-data/get-fee-rate.md

@@ -114,5 +114,11 @@ components:
         error:
           type: string
           description: Error message
+        code:
+          type: string
+          description: Machine-readable error code, when provided
+        retry_after_seconds:
+          type: integer
+          description: Number of seconds to wait before retrying, when provided
 
 ````

docs/api-reference/market-data/get-last-trade-price.md

@@ -110,5 +110,11 @@ components:
         error:
           type: string
           description: Error message
+        code:
+          type: string
+          description: Machine-readable error code, when provided
+        retry_after_seconds:
+          type: integer
+          description: Number of seconds to wait before retrying, when provided
 
 ````

docs/api-reference/market-data/get-last-trade-prices-query-parameters.md

@@ -130,5 +130,11 @@ components:
         error:
           type: string
           description: Error message
+        code:
+          type: string
+          description: Machine-readable error code, when provided
+        retry_after_seconds:
+          type: integer
+          description: Number of seconds to wait before retrying, when provided
 
 ````

docs/api-reference/market-data/get-last-trade-prices-request-body.md

@@ -147,5 +147,11 @@ components:
         error:
           type: string
           description: Error message
+        code:
+          type: string
+          description: Machine-readable error code, when provided
+        retry_after_seconds:
+          type: integer
+          description: Number of seconds to wait before retrying, when provided
 
 ````

docs/api-reference/market-data/get-market-price.md

@@ -129,5 +129,11 @@ components:
         error:
           type: string
           description: Error message
+        code:
+          type: string
+          description: Machine-readable error code, when provided
+        retry_after_seconds:
+          type: integer
+          description: Number of seconds to wait before retrying, when provided
 
 ````

docs/api-reference/market-data/get-market-prices-query-parameters.md

@@ -126,5 +126,11 @@ components:
         error:
           type: string
           description: Error message
+        code:
+          type: string
+          description: Machine-readable error code, when provided
+        retry_after_seconds:
+          type: integer
+          description: Number of seconds to wait before retrying, when provided
 
 ````

docs/api-reference/market-data/get-market-prices-request-body.md

@@ -141,5 +141,11 @@ components:
         error:
           type: string
           description: Error message
+        code:
+          type: string
+          description: Machine-readable error code, when provided
+        retry_after_seconds:
+          type: integer
+          description: Number of seconds to wait before retrying, when provided
 
 ````

docs/api-reference/market-data/get-midpoint-prices-query-parameters.md

@@ -100,5 +100,11 @@ components:
         error:
           type: string
           description: Error message
+        code:
+          type: string
+          description: Machine-readable error code, when provided
+        retry_after_seconds:
+          type: integer
+          description: Number of seconds to wait before retrying, when provided
 
 ````

docs/api-reference/market-data/get-midpoint-prices-request-body.md

@@ -119,5 +119,11 @@ components:
         error:
           type: string
           description: Error message
+        code:
+          type: string
+          description: Machine-readable error code, when provided
+        retry_after_seconds:
+          type: integer
+          description: Number of seconds to wait before retrying, when provided
 
 ````

docs/api-reference/market-data/get-order-book.md

@@ -175,6 +175,12 @@ components:
         error:
           type: string
           description: Error message
+        code:
+          type: string
+          description: Machine-readable error code, when provided
+        retry_after_seconds:
+          type: integer
+          description: Number of seconds to wait before retrying, when provided
     OrderSummary:
       type: object
       required:

docs/api-reference/market-data/get-order-books-request-body.md

@@ -175,6 +175,12 @@ components:
         error:
           type: string
           description: Error message
+        code:
+          type: string
+          description: Machine-readable error code, when provided
+        retry_after_seconds:
+          type: integer
+          description: Number of seconds to wait before retrying, when provided
     OrderSummary:
       type: object
       required:

docs/api-reference/market-data/get-spread.md

@@ -99,5 +99,11 @@ components:
         error:
           type: string
           description: Error message
+        code:
+          type: string
+          description: Machine-readable error code, when provided
+        retry_after_seconds:
+          type: integer
+          description: Number of seconds to wait before retrying, when provided
 
 ````

docs/api-reference/market-data/get-spreads.md

@@ -117,5 +117,11 @@ components:
         error:
           type: string
           description: Error message
+        code:
+          type: string
+          description: Machine-readable error code, when provided
+        retry_after_seconds:
+          type: integer
+          description: Number of seconds to wait before retrying, when provided
 
 ````

docs/api-reference/market-data/get-tick-size-by-path-parameter.md

@@ -111,5 +111,11 @@ components:
         error:
           type: string
           description: Error message
+        code:
+          type: string
+          description: Machine-readable error code, when provided
+        retry_after_seconds:
+          type: integer
+          description: Number of seconds to wait before retrying, when provided
 
 ````

docs/api-reference/market-data/get-tick-size.md

@@ -115,5 +115,11 @@ components:
         error:
           type: string
           description: Error message
+        code:
+          type: string
+          description: Machine-readable error code, when provided
+        retry_after_seconds:
+          type: integer
+          description: Number of seconds to wait before retrying, when provided
 
 ````

docs/api-reference/markets/get-batch-prices-history.md

@@ -125,6 +125,12 @@ components:
         error:
           type: string
           description: Error message
+        code:
+          type: string
+          description: Machine-readable error code, when provided
+        retry_after_seconds:
+          type: integer
+          description: Number of seconds to wait before retrying, when provided
     MarketPrice:
       type: object
       properties:

docs/api-reference/markets/get-prices-history.md

@@ -124,6 +124,12 @@ components:
         error:
           type: string
           description: Error message
+        code:
+          type: string
+          description: Machine-readable error code, when provided
+        retry_after_seconds:
+          type: integer
+          description: Number of seconds to wait before retrying, when provided
     MarketPrice:
       type: object
       properties:

docs/api-reference/markets/list-markets-keyset-pagination.md

@@ -55,11 +55,11 @@ paths:
       parameters:
         - name: limit
           in: query
-          description: Maximum number of results to return (max 1000)
+          description: Maximum number of results to return (max 100)
           schema:
             type: integer
             minimum: 1
-            maximum: 1000
+            maximum: 100
             default: 20
         - name: order
           in: query

docs/api-reference/rate-limits.md

@@ -104,6 +104,16 @@ Trading endpoints have both **burst** limits (short spikes allowed) and **sustai
 
 ***
 
+## Bridge API
+
+Base URL: `https://bridge.polymarket.com`
+
+| Endpoint | Limit        |
+| -------- | ------------ |
+| General  | 50 req / 10s |
+
+***
+
 ## Other
 
 | Endpoint          | Limit          |

docs/api-reference/rebates/get-current-rebated-fees-for-a-maker.md

@@ -154,5 +154,11 @@ components:
         error:
           type: string
           description: Error message
+        code:
+          type: string
+          description: Machine-readable error code, when provided
+        retry_after_seconds:
+          type: integer
+          description: Number of seconds to wait before retrying, when provided
 
 ````

docs/api-reference/rewards/get-current-active-rewards-configurations.md

@@ -159,6 +159,12 @@ components:
         error:
           type: string
           description: Error message
+        code:
+          type: string
+          description: Machine-readable error code, when provided
+        retry_after_seconds:
+          type: integer
+          description: Number of seconds to wait before retrying, when provided
     CurrentReward:
       type: object
       description: Current active reward configuration for a market

docs/api-reference/rewards/get-earnings-for-user-by-date.md

@@ -197,6 +197,12 @@ components:
         error:
           type: string
           description: Error message
+        code:
+          type: string
+          description: Machine-readable error code, when provided
+        retry_after_seconds:
+          type: integer
+          description: Number of seconds to wait before retrying, when provided
     UserEarning:
       type: object
       description: User earnings for a specific market on a given day

docs/api-reference/rewards/get-multiple-markets-with-rewards.md

@@ -279,6 +279,12 @@ components:
         error:
           type: string
           description: Error message
+        code:
+          type: string
+          description: Machine-readable error code, when provided
+        retry_after_seconds:
+          type: integer
+          description: Number of seconds to wait before retrying, when provided
     MultiMarketInfo:
       type: object
       description: Market with rewards configuration and trading metrics

docs/api-reference/rewards/get-raw-rewards-for-a-specific-market.md

@@ -188,6 +188,12 @@ components:
         error:
           type: string
           description: Error message
+        code:
+          type: string
+          description: Machine-readable error code, when provided
+        retry_after_seconds:
+          type: integer
+          description: Number of seconds to wait before retrying, when provided
     MarketReward:
       type: object
       description: Market with raw reward configurations

docs/api-reference/rewards/get-reward-percentages-for-user.md

@@ -145,6 +145,12 @@ components:
         error:
           type: string
           description: Error message
+        code:
+          type: string
+          description: Machine-readable error code, when provided
+        retry_after_seconds:
+          type: integer
+          description: Number of seconds to wait before retrying, when provided
   securitySchemes:
     polyApiKey:
       type: apiKey

docs/api-reference/rewards/get-total-earnings-for-user-by-date.md

@@ -190,6 +190,12 @@ components:
         error:
           type: string
           description: Error message
+        code:
+          type: string
+          description: Machine-readable error code, when provided
+        retry_after_seconds:
+          type: integer
+          description: Number of seconds to wait before retrying, when provided
   securitySchemes:
     polyApiKey:
       type: apiKey

docs/api-reference/rewards/get-user-earnings-and-markets-configuration.md

@@ -335,6 +335,12 @@ components:
         error:
           type: string
           description: Error message
+        code:
+          type: string
+          description: Machine-readable error code, when provided
+        retry_after_seconds:
+          type: integer
+          description: Number of seconds to wait before retrying, when provided
     UserRewardsMarket:
       type: object
       description: Market with user rewards earnings and configuration

docs/api-reference/trade/cancel-all-orders.md

@@ -140,6 +140,12 @@ components:
         error:
           type: string
           description: Error message
+        code:
+          type: string
+          description: Machine-readable error code, when provided
+        retry_after_seconds:
+          type: integer
+          description: Number of seconds to wait before retrying, when provided
   securitySchemes:
     polyApiKey:
       type: apiKey

docs/api-reference/trade/cancel-multiple-orders.md

@@ -180,6 +180,12 @@ components:
         error:
           type: string
           description: Error message
+        code:
+          type: string
+          description: Machine-readable error code, when provided
+        retry_after_seconds:
+          type: integer
+          description: Number of seconds to wait before retrying, when provided
   securitySchemes:
     polyApiKey:
       type: apiKey

docs/api-reference/trade/cancel-orders-for-a-market.md

@@ -175,6 +175,12 @@ components:
         error:
           type: string
           description: Error message
+        code:
+          type: string
+          description: Machine-readable error code, when provided
+        retry_after_seconds:
+          type: integer
+          description: Number of seconds to wait before retrying, when provided
   securitySchemes:
     polyApiKey:
       type: apiKey

docs/api-reference/trade/cancel-single-order.md

@@ -164,6 +164,12 @@ components:
         error:
           type: string
           description: Error message
+        code:
+          type: string
+          description: Machine-readable error code, when provided
+        retry_after_seconds:
+          type: integer
+          description: Number of seconds to wait before retrying, when provided
   securitySchemes:
     polyApiKey:
       type: apiKey

docs/api-reference/trade/get-builder-trades.md

@@ -198,6 +198,12 @@ components:
         error:
           type: string
           description: Error message
+        code:
+          type: string
+          description: Machine-readable error code, when provided
+        retry_after_seconds:
+          type: integer
+          description: Number of seconds to wait before retrying, when provided
     BuilderTrade:
       type: object
       description: Builder trade information

docs/api-reference/trade/get-order-scoring-status.md

@@ -158,6 +158,12 @@ components:
         error:
           type: string
           description: Error message
+        code:
+          type: string
+          description: Machine-readable error code, when provided
+        retry_after_seconds:
+          type: integer
+          description: Number of seconds to wait before retrying, when provided
   securitySchemes:
     polyApiKey:
       type: apiKey

docs/api-reference/trade/get-single-order-by-id.md

@@ -227,6 +227,12 @@ components:
         error:
           type: string
           description: Error message
+        code:
+          type: string
+          description: Machine-readable error code, when provided
+        retry_after_seconds:
+          type: integer
+          description: Number of seconds to wait before retrying, when provided
   securitySchemes:
     polyApiKey:
       type: apiKey

docs/api-reference/trade/get-trades.md

@@ -209,6 +209,12 @@ components:
         error:
           type: string
           description: Error message
+        code:
+          type: string
+          description: Machine-readable error code, when provided
+        retry_after_seconds:
+          type: integer
+          description: Number of seconds to wait before retrying, when provided
     Trade:
       type: object
       description: Trade information

docs/api-reference/trade/get-user-orders.md

@@ -197,6 +197,12 @@ components:
         error:
           type: string
           description: Error message
+        code:
+          type: string
+          description: Machine-readable error code, when provided
+        retry_after_seconds:
+          type: integer
+          description: Number of seconds to wait before retrying, when provided
     OpenOrder:
       type: object
       required:

docs/api-reference/trade/post-a-new-order.md

@@ -76,6 +76,7 @@ paths:
                   owner: f4f247b7-4ac7-ff29-a152-04fda0a8755a
                   orderType: GTC
                   deferExec: false
+                  postOnly: false
       responses:
         '200':
           description: Order successfully processed
@@ -168,6 +169,11 @@ paths:
                 error: could not insert order
         '503':
           description: Service unavailable - Trading disabled or cancel-only mode
+          headers:
+            Retry-After:
+              description: Seconds to wait before retrying when provided by post-only mode.
+              schema:
+                type: integer
           content:
             application/json:
               schema:
@@ -185,6 +191,14 @@ paths:
                     error: >-
                       Trading is currently cancel-only. New orders are not
                       accepted, but cancels are allowed.
+                post_only_mode:
+                  summary: Post-only mode
+                  value:
+                    error: >-
+                      post-only mode: only post-only orders and cancels are
+                      allowed
+                    code: post_only_mode
+                    retry_after_seconds: 79
       security:
         - polyApiKey: []
           polyAddress: []
@@ -218,6 +232,12 @@ components:
           type: boolean
           description: Whether to defer execution
           default: false
+        postOnly:
+          type: boolean
+          description: >-
+            Whether the order must rest on the book and not match immediately.
+            Only supported for GTC and GTD orders.
+          default: false
     SendOrderResponse:
       type: object
       required:
@@ -272,6 +292,12 @@ components:
         error:
           type: string
           description: Error message
+        code:
+          type: string
+          description: Machine-readable error code, when provided
+        retry_after_seconds:
+          type: integer
+          description: Number of seconds to wait before retrying, when provided
     Order:
       type: object
       description: >

docs/api-reference/trade/post-multiple-orders.md

@@ -83,6 +83,7 @@ paths:
                     owner: f4f247b7-4ac7-ff29-a152-04fda0a8755a
                     orderType: GTC
                     deferExec: false
+                    postOnly: false
                   - order:
                       maker: '0x1234567890123456789012345678901234567890'
                       signer: '0x1234567890123456789012345678901234567890'
@@ -101,6 +102,7 @@ paths:
                     owner: f4f247b7-4ac7-ff29-a152-04fda0a8755a
                     orderType: GTC
                     deferExec: false
+                    postOnly: false
       responses:
         '200':
           description: >-
@@ -136,6 +138,25 @@ paths:
                       orderID: ''
                       status: delayed
                       errorMsg: 'Rate limit exceeded for tokenId: 0xdef456abc789...'
+                post_only_mode:
+                  summary: Post-only mode results
+                  value:
+                    - errorMsg: >-
+                        post-only mode: only post-only orders and cancels are
+                        allowed
+                      orderID: ''
+                      takingAmount: ''
+                      makingAmount: ''
+                      status: ''
+                      success: true
+                    - errorMsg: >-
+                        post-only mode: only post-only orders and cancels are
+                        allowed
+                      orderID: ''
+                      takingAmount: ''
+                      makingAmount: ''
+                      status: ''
+                      success: true
         '400':
           description: Bad request - Invalid order payload or validation error
           content:
@@ -191,6 +212,11 @@ paths:
                 error: could not insert order
         '503':
           description: Service unavailable - Trading disabled or cancel-only mode
+          headers:
+            Retry-After:
+              description: Seconds to wait before retrying when provided by post-only mode.
+              schema:
+                type: integer
           content:
             application/json:
               schema:
@@ -208,6 +234,14 @@ paths:
                     error: >-
                       Trading is currently cancel-only. New orders are not
                       accepted, but cancels are allowed.
+                post_only_mode:
+                  summary: Post-only mode
+                  value:
+                    error: >-
+                      post-only mode: only post-only orders and cancels are
+                      allowed
+                    code: post_only_mode
+                    retry_after_seconds: 79
       security:
         - polyApiKey: []
           polyAddress: []
@@ -241,6 +275,12 @@ components:
           type: boolean
           description: Whether to defer execution
           default: false
+        postOnly:
+          type: boolean
+          description: >-
+            Whether the order must rest on the book and not match immediately.
+            Only supported for GTC and GTD orders.
+          default: false
     SendOrderResponse:
       type: object
       required:
@@ -295,6 +335,12 @@ components:
         error:
           type: string
           description: Error message
+        code:
+          type: string
+          description: Machine-readable error code, when provided
+        retry_after_seconds:
+          type: integer
+          description: Number of seconds to wait before retrying, when provided
     Order:
       type: object
       description: >

docs/api-reference/trade/send-heartbeat.md

@@ -110,6 +110,12 @@ components:
         error:
           type: string
           description: Error message
+        code:
+          type: string
+          description: Machine-readable error code, when provided
+        retry_after_seconds:
+          type: integer
+          description: Number of seconds to wait before retrying, when provided
   securitySchemes:
     polyApiKey:
       type: apiKey

docs/market-makers/inventory.md

@@ -26,10 +26,11 @@ Split converts pUSD into equal amounts of YES and NO tokens — creating the inv
   import { Interface } from "ethers/lib/utils";
   import { RelayClient, Transaction } from "@polymarket/builder-relayer-client";
 
-  const CTF_ADDRESS = "0x4D97DCd97eC945f40cF65F87097ACe5EA0476045";
+  const CTF_COLLATERAL_ADAPTER_ADDRESS =
+    "0xAdA100Db00Ca00073811820692005400218FcE1f";
   const pUSD_ADDRESS = "0xC011a7E12a19f7B1f670d46F03B03f3342E82DFB";
 
-  const ctfInterface = new Interface([
+  const collateralAdapterInterface = new Interface([
     "function splitPosition(address collateralToken, bytes32 parentCollectionId, bytes32 conditionId, uint[] partition, uint amount)",
   ]);
 
@@ -37,8 +38,8 @@ Split converts pUSD into equal amounts of YES and NO tokens — creating the inv
   const amount = ethers.utils.parseUnits("1000", 6); // pUSD has 6 decimals
 
   const splitTx: Transaction = {
-    to: CTF_ADDRESS,
-    data: ctfInterface.encodeFunctionData("splitPosition", [
+    to: CTF_COLLATERAL_ADAPTER_ADDRESS,
+    data: collateralAdapterInterface.encodeFunctionData("splitPosition", [
       pUSD_ADDRESS, // collateralToken
       ethers.constants.HashZero, // parentCollectionId (always zero for Polymarket)
       conditionId, // conditionId from market
@@ -56,10 +57,10 @@ Split converts pUSD into equal amounts of YES and NO tokens — creating the inv
   ```python Python theme={null}
   from web3 import Web3
 
-  CTF_ADDRESS = "0x4D97DCd97eC945f40cF65F87097ACe5EA0476045"
+  CTF_COLLATERAL_ADAPTER_ADDRESS = "0xAdA100Db00Ca00073811820692005400218FcE1f"
   pUSD_ADDRESS = "0xC011a7E12a19f7B1f670d46F03B03f3342E82DFB"
 
-  ctf_abi = [{
+  collateral_adapter_abi = [{
       "name": "splitPosition",
       "type": "function",
       "inputs": [
@@ -76,9 +77,9 @@ Split converts pUSD into equal amounts of YES and NO tokens — creating the inv
   amount = 1000 * 10**6  # pUSD has 6 decimals
 
   split_tx = {
-      "to": CTF_ADDRESS,
+      "to": CTF_COLLATERAL_ADAPTER_ADDRESS,
       "data": Web3().eth.contract(
-          address=CTF_ADDRESS, abi=ctf_abi
+          address=CTF_COLLATERAL_ADAPTER_ADDRESS, abi=collateral_adapter_abi
       ).encode_abi(
           abi_element_identifier="splitPosition",
           args=[
@@ -95,24 +96,6 @@ Split converts pUSD into equal amounts of YES and NO tokens — creating the inv
   response = client.execute([split_tx], "Split pUSD into tokens")
   response.wait()
   ```
-
-  ```rust Rust theme={null}
-  use polymarket_client_sdk_v2::ctf::Client as CtfClient;
-  use polymarket_client_sdk_v2::ctf::types::SplitPositionRequest;
-  use polymarket_client_sdk_v2::types::{U256, address};
-
-  let ctf_client = CtfClient::new(provider, 137)?;
-
-  // Split $1000 pUSD into YES/NO tokens
-  let request = SplitPositionRequest::builder()
-      .collateral_token(address!("0xC011a7E12a19f7B1f670d46F03B03f3342E82DFB"))
-      .condition_id(condition_id)
-      .partition(vec![U256::from(1), U256::from(2)])
-      .amount(U256::from(1000_000_000u64)) // 1000 pUSD (6 decimals)
-      .build();
-  let result = ctf_client.split_position(&request).await?;
-  println!("Split tx: {:?}", result.transaction_hash);
-  ```
 </CodeGroup>
 
 After splitting 1000 pUSD, you receive 1000 YES tokens and 1000 NO tokens. Your pUSD balance decreases by 1000.
@@ -125,7 +108,7 @@ Merge converts equal amounts of YES and NO tokens back into pUSD — useful for
 
 <CodeGroup>
   ```typescript TypeScript theme={null}
-  const ctfInterface = new Interface([
+  const collateralAdapterInterface = new Interface([
     "function mergePositions(address collateralToken, bytes32 parentCollectionId, bytes32 conditionId, uint[] partition, uint amount)",
   ]);
 
@@ -133,8 +116,8 @@ Merge converts equal amounts of YES and NO tokens back into pUSD — useful for
   const amount = ethers.utils.parseUnits("500", 6);
 
   const mergeTx: Transaction = {
-    to: CTF_ADDRESS,
-    data: ctfInterface.encodeFunctionData("mergePositions", [
+    to: CTF_COLLATERAL_ADAPTER_ADDRESS,
+    data: collateralAdapterInterface.encodeFunctionData("mergePositions", [
       pUSD_ADDRESS,
       ethers.constants.HashZero,
       conditionId,
@@ -166,9 +149,9 @@ Merge converts equal amounts of YES and NO tokens back into pUSD — useful for
   amount = 500 * 10**6
 
   merge_tx = {
-      "to": CTF_ADDRESS,
+      "to": CTF_COLLATERAL_ADAPTER_ADDRESS,
       "data": Web3().eth.contract(
-          address=CTF_ADDRESS, abi=merge_abi
+          address=CTF_COLLATERAL_ADAPTER_ADDRESS, abi=merge_abi
       ).encode_abi(
           abi_element_identifier="mergePositions",
           args=[pUSD_ADDRESS, bytes(32), condition_id, [1, 2], amount]
@@ -179,19 +162,6 @@ Merge converts equal amounts of YES and NO tokens back into pUSD — useful for
   response = client.execute([merge_tx], "Merge tokens to pUSD")
   response.wait()
   ```
-
-  ```rust Rust theme={null}
-  use polymarket_client_sdk_v2::ctf::types::MergePositionsRequest;
-
-  // Merge 500 YES + 500 NO back to 500 pUSD
-  let request = MergePositionsRequest::builder()
-      .collateral_token(address!("0xC011a7E12a19f7B1f670d46F03B03f3342E82DFB"))
-      .condition_id(condition_id)
-      .partition(vec![U256::from(1), U256::from(2)])
-      .amount(U256::from(500_000_000u64)) // 500 pUSD (6 decimals)
-      .build();
-  let result = ctf_client.merge_positions(&request).await?;
-  ```
 </CodeGroup>
 
 After merging 500 of each, your YES and NO balances decrease by 500 and your pUSD balance increases by 500.
@@ -234,13 +204,13 @@ Once a market resolves, redeem winning tokens for pUSD. Each winning token is wo
 
 <CodeGroup>
   ```typescript TypeScript theme={null}
-  const ctfInterface = new Interface([
+  const collateralAdapterInterface = new Interface([
     "function redeemPositions(address collateralToken, bytes32 parentCollectionId, bytes32 conditionId, uint[] indexSets)",
   ]);
 
   const redeemTx: Transaction = {
-    to: CTF_ADDRESS,
-    data: ctfInterface.encodeFunctionData("redeemPositions", [
+    to: CTF_COLLATERAL_ADAPTER_ADDRESS,
+    data: collateralAdapterInterface.encodeFunctionData("redeemPositions", [
       pUSD_ADDRESS,
       ethers.constants.HashZero,
       conditionId,
@@ -267,9 +237,9 @@ Once a market resolves, redeem winning tokens for pUSD. Each winning token is wo
   }]
 
   redeem_tx = {
-      "to": CTF_ADDRESS,
+      "to": CTF_COLLATERAL_ADAPTER_ADDRESS,
       "data": Web3().eth.contract(
-          address=CTF_ADDRESS, abi=redeem_abi
+          address=CTF_COLLATERAL_ADAPTER_ADDRESS, abi=redeem_abi
       ).encode_abi(
           abi_element_identifier="redeemPositions",
           args=[pUSD_ADDRESS, bytes(32), condition_id, [1, 2]]
@@ -280,28 +250,18 @@ Once a market resolves, redeem winning tokens for pUSD. Each winning token is wo
   response = client.execute([redeem_tx], "Redeem winning tokens")
   response.wait()
   ```
-
-  ```rust Rust theme={null}
-  use polymarket_client_sdk_v2::ctf::types::RedeemPositionsRequest;
-
-  let request = RedeemPositionsRequest::builder()
-      .collateral_token(address!("0xC011a7E12a19f7B1f670d46F03B03f3342E82DFB"))
-      .condition_id(condition_id)
-      .index_sets(vec![U256::from(1), U256::from(2)]) // Redeem both (only winners pay)
-      .build();
-  let result = ctf_client.redeem_positions(&request).await?;
-  ```
 </CodeGroup>
 
 ***
 
 ## Negative Risk Markets
 
-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:
+Multi-outcome markets use the Neg Risk CTF Exchange for trading and the Neg Risk CTF Collateral Adapter for pUSD-native split, merge, and redeem actions. 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_COLLATERAL_ADAPTER =
+  "0xadA2005600Dec949baf300f4C6120000bDB6eAab";
 ```
 
 See [Negative Risk Markets](/advanced/neg-risk) for details on how multi-outcome token mechanics differ.
@@ -339,8 +299,8 @@ Execute multiple inventory operations in a single relayer call for efficiency:
 const transactions: Transaction[] = [
   // Split on Market A
   {
-    to: CTF_ADDRESS,
-    data: ctfInterface.encodeFunctionData("splitPosition", [
+    to: CTF_COLLATERAL_ADAPTER_ADDRESS,
+    data: collateralAdapterInterface.encodeFunctionData("splitPosition", [
       pUSD_ADDRESS,
       ethers.constants.HashZero,
       conditionIdA,
@@ -351,8 +311,8 @@ const transactions: Transaction[] = [
   },
   // Split on Market B
   {
-    to: CTF_ADDRESS,
-    data: ctfInterface.encodeFunctionData("splitPosition", [
+    to: CTF_COLLATERAL_ADAPTER_ADDRESS,
+    data: collateralAdapterInterface.encodeFunctionData("splitPosition", [
       pUSD_ADDRESS,
       ethers.constants.HashZero,
       conditionIdB,

docs/resources/error-codes.md

@@ -32,10 +32,6 @@ These errors can occur on **any authenticated endpoint**.
   `Trading is currently disabled. Check polymarket.com for updates` — The exchange is temporarily paused. No orders (including cancels) are accepted.
 </ResponseField>
 
-<ResponseField name="503" type="Service Unavailable">
-  `Trading is currently cancel-only. New orders are not accepted, but cancels are allowed.` — The exchange is in cancel-only mode. You can cancel existing orders but cannot place new ones.
-</ResponseField>
-
 <ResponseField name="429" type="Too Many Requests">
   `Too Many Requests` — You've exceeded the [rate limit](/api-reference/rate-limits). Back off and retry with exponential backoff.
 </ResponseField>
@@ -168,6 +164,26 @@ Errors from order placement endpoints.
   `'{address}' address in closed only mode`
 </ResponseField>
 
+<ResponseField name="503" type="Service Unavailable">
+  `Trading is currently cancel-only. New orders are not accepted, but cancels are allowed.` — The exchange is in cancel-only mode. You can cancel existing orders but cannot place new orders.
+</ResponseField>
+
+<ResponseField name="503" type="Service Unavailable">
+  `post-only mode: only post-only orders and cancels are allowed` — The exchange is in post-only mode. You can cancel orders and place orders with `postOnly: true`; non-post-only orders are rejected. The response includes `code: "post_only_mode"` and `retry_after_seconds`, and the same retry delay is also sent in the `Retry-After` HTTP header.
+</ResponseField>
+
+Example response:
+
+```json theme={null}
+{
+  "error": "post-only mode: only post-only orders and cancels are allowed",
+  "code": "post_only_mode",
+  "retry_after_seconds": 79
+}
+```
+
+The retry delay is also sent in the `Retry-After` HTTP header.
+
 ### POST orders
 
 All errors from `POST /order` apply, plus:
@@ -178,6 +194,29 @@ All errors from `POST /order` apply, plus:
 
 Per-order errors are returned in the `200` response array, with individual error messages for each failed order.
 
+In post-only mode, non-post-only orders in a batch return per-order errors:
+
+```json theme={null}
+[
+  {
+    "errorMsg": "post-only mode: only post-only orders and cancels are allowed",
+    "orderID": "",
+    "takingAmount": "",
+    "makingAmount": "",
+    "status": "",
+    "success": true
+  },
+  {
+    "errorMsg": "post-only mode: only post-only orders and cancels are allowed",
+    "orderID": "",
+    "takingAmount": "",
+    "makingAmount": "",
+    "status": "",
+    "success": true
+  }
+]
+```
+
 ***
 
 ## Order Processing Errors
@@ -536,7 +575,7 @@ Errors from order query endpoints.
 | `425`  | Too Early             | Matching engine is restarting — retry with backoff. See [Matching Engine](/trading/matching-engine) |
 | `429`  | Too Many Requests     | Rate limit exceeded — implement exponential backoff                                                 |
 | `500`  | Internal Server Error | Unexpected server error — retry with backoff                                                        |
-| `503`  | Service Unavailable   | Exchange paused or in cancel-only mode                                                              |
+| `503`  | Service Unavailable   | Exchange paused, or order placement blocked by cancel-only / post-only mode                         |
 
 <Note>
   The CLOB API has an internal override: any error message containing `"not found"` returns `404`, `"unauthorized"` returns `401`, and `"context canceled"` returns `400`, regardless of the original status code.

docs/trading/clients/l1.md

@@ -63,7 +63,7 @@ L1 methods require the client to initialize with a signer.
 
 ### createApiKey
 
-Creates a new API key (L2 credentials) for the wallet signer. Each wallet can only have one active API key at a time — creating a new key invalidates the previous one.
+Creates a new API key (L2 credentials) for the wallet signer.
 
 ```typescript Signature theme={null}
 async createApiKey(nonce?: number): Promise<ApiKeyCreds>

docs/trading/matching-engine.md

@@ -4,26 +4,9 @@
 
 # Matching Engine Restarts
 
-> Restart schedule, maintenance windows, and how to handle downtime
+> Maintenance windows, restart handling, and post-restart post-only mode
 
-The Polymarket matching engine undergoes periodic restarts for maintenance and upgrades. This page covers the restart schedule, how to detect and handle downtime, and where to get advance notice of changes.
-
-***
-
-## Restart Schedule
-
-The matching engine restarts **weekly on Tuesdays at 7:00 AM ET**. During a restart window, the engine is temporarily unavailable — typically for about **90 seconds**.
-
-|                      | Details                                     |
-| -------------------- | ------------------------------------------- |
-| **Cadence**          | Weekly                                      |
-| **Day & time**       | Tuesday, 7:00 AM ET                         |
-| **Typical duration** | \~90 seconds                                |
-| **What happens**     | Order matching is paused, API returns `425` |
-
-<Note>
-  Unscheduled restarts may occur for critical updates or hotfixes. These are announced with as much advance notice as possible.
-</Note>
+The Polymarket matching engine undergoes restarts for maintenance and upgrades. This page covers how to detect and handle downtime, the post-restart post-only period, and where to get advance notice of changes.
 
 ***
 
@@ -49,6 +32,8 @@ Announcements typically include **what's changing**, the **scheduled time**, and
 
 During a restart window, the CLOB API returns **HTTP 425 (Too Early)** on all order-related endpoints. This tells your client that the matching engine is restarting and will be back shortly.
 
+After every restart, the matching engine enters **post-only mode for 2 minutes**. During this period, cancels are accepted and new orders must use `postOnly: true`; non-post-only orders are rejected.
+
 ### Recommended Retry Strategy
 
 <Steps>
@@ -60,8 +45,8 @@ During a restart window, the CLOB API returns **HTTP 425 (Too Early)** on all or
     Wait and retry with exponential backoff. Start at 1–2 seconds and increase the interval on each retry.
   </Step>
 
-  <Step title="Resume normal operation">
-    Once you receive a successful response, the engine is back online. Resume normal order flow.
+  <Step title="Handle post-only mode">
+    Once `425` responses stop, the engine is back online but remains in post-only mode for 2 minutes. During that period, only cancels and orders with `postOnly: true` are accepted.
   </Step>
 </Steps>
 
@@ -158,9 +143,67 @@ Check the HTTP status code on responses to the CLOB API and retry on `425`:
 
 ***
 
+## Restricted Trading Modes
+
+During restricted trading modes, order placement behavior changes for `POST /order` and `POST /orders`. Cancel endpoints continue to accept cancels unless trading is fully disabled.
+
+### Cancel-Only Mode
+
+In cancel-only mode, new orders are rejected, but cancel requests are still accepted.
+
+`POST /order` and `POST /orders` return `503`:
+
+```json theme={null}
+{
+  "error": "Trading is currently cancel-only. New orders are not accepted, but cancels are allowed."
+}
+```
+
+### Post-Only Mode
+
+After every restart, the matching engine enters post-only mode for **2 minutes**. Cancel requests are accepted and new orders must use `postOnly: true`. Non-post-only orders are rejected.
+
+`POST /order` returns `503` with a retry delay in both the response body and the `Retry-After` HTTP header:
+
+```json theme={null}
+{
+  "error": "post-only mode: only post-only orders and cancels are allowed",
+  "code": "post_only_mode",
+  "retry_after_seconds": 79
+}
+```
+
+`POST /orders` returns per-order errors for non-post-only orders in the batch:
+
+```json theme={null}
+[
+  {
+    "errorMsg": "post-only mode: only post-only orders and cancels are allowed",
+    "orderID": "",
+    "takingAmount": "",
+    "makingAmount": "",
+    "status": "",
+    "success": true
+  },
+  {
+    "errorMsg": "post-only mode: only post-only orders and cancels are allowed",
+    "orderID": "",
+    "takingAmount": "",
+    "makingAmount": "",
+    "status": "",
+    "success": true
+  }
+]
+```
+
+When you receive either restricted-mode response, do not retry the same non-post-only order unchanged. Cancel existing orders, retry after the indicated delay when one is provided, or resubmit eligible maker orders with `postOnly: true`.
+
+***
+
 ## Best Practices
 
 * **Subscribe to announcement channels** — get notified before restarts happen so you can prepare
 * **Handle 425 gracefully** — treat it as a temporary condition, not an error; your retry logic should resume automatically
+* **Handle 503 mode responses on order placement** — cancel-only and post-only responses require changing order flow, not blind retrying
 * **Avoid aggressive retries** — the engine needs time to reload orderbooks; rapid-fire retries won't speed things up and may hit rate limits once the engine is back
 * **Log restart events** — track when your client encounters 425s to correlate with announced maintenance windows

docs/trading/overview.md

@@ -223,7 +223,7 @@ The CLOB matching engine runs in the following regions:
 
 <Tip>
   **Direct co-location available.** Users who complete the [KYC/KYB
-  form](https://forms.gle/Qy39FtiizodXbdLNA) can get access to co-locate
+  form](https://docs.google.com/forms/d/e/1FAIpQLSfY-3Dl3yxq8HKFjFad8YzKZmm0k3Gdg29HD6gL-K-AmI6KXw/viewform) can get access to co-locate
   directly in `eu-west-2` for the lowest possible latency to Polymarket's
   primary servers. See [Geographic
   Restrictions](/api-reference/geoblock#server-infrastructure) for full