polynode 0.7.4__py3-none-any.whl → 0.9.0__py3-none-any.whl

polynode/_version.py

@@ -1 +1 @@
-__version__ = "0.7.4"
+__version__ = "0.9.0"

polynode/trading/V2_ORDER_FLOW.md

@@ -0,0 +1,264 @@
+# V2 Order Flow — Reference
+
+End-to-end recipe for placing a Polymarket V2 CLOB order with builder attribution.
+Verified 2026-04-21 with matched order `0xaecd1060f7c978d0ab947eacc12a17106b7a5d087aefe04c275f3d83d2aa6281` (tx `0xb86168562057efd161a1f9ac77ecf3728653cf9668a21567c4923a298cb24d77`).
+
+## TL;DR
+
+```
+1. Approve pUSD to: CTF_EXCHANGE_V2, NEG_RISK_EXCHANGE_V2_A, NEG_RISK_ADAPTER (V1!)
+2. setApprovalForAll CTF → same three addresses
+3. GET /balance-allowance/update — force CLOB cache refresh after approvals
+4. Sign EIP-712 Order (domain name "Polymarket CTF Exchange", version "2")
+5. POST /order with L2 HMAC headers
+```
+
+## Required Approvals (V2 CLOB balance-allowance check)
+
+The V2 CLOB checks **three** pUSD allowances for orders:
+
+| Address | Name | Why |
+|---|---|---|
+| `0xE111180000d2663C0091e4f400237545B87B996B` | `CTF_EXCHANGE_V2` | Standard market orders |
+| `0xe2222d279d744050d28e00520010520000310F59` | `NEG_RISK_EXCHANGE_V2_A` | Neg-risk market orders |
+| `0xd91E80cF2E7be2e162c6513ceD06f1dD0dA35296` | `NegRiskAdapter` (V1) | Settlement delegation |
+
+**The V1 `NegRiskAdapter` MUST be approved for pUSD even though it's a V1 contract.** The V2 neg-risk exchange delegates settlement to it. Without this allowance set, the CLOB rejects every order with:
+
+```
+{"error":"not enough balance / allowance"}
+```
+
+## Order Flow Step-by-Step
+
+### 1. On-chain approvals (gasless via relayer for Safe wallets)
+
+For **every** spender above:
+- `pUSD.approve(spender, MAX_UINT256)`
+- `CTF.setApprovalForAll(spender, true)` — only needed for SELL orders, but safe to set
+
+Batch all 6 TXs into one Safe multisend via `RelayClient.execute(...)`.
+
+### 2. Refresh CLOB balance/allowance cache
+
+```
+GET https://clob-v2.polymarket.com/balance-allowance/update?asset_type=COLLATERAL&signature_type=2
+  Headers: POLY_ADDRESS, POLY_SIGNATURE, POLY_TIMESTAMP, POLY_API_KEY, POLY_PASSPHRASE
+  HMAC path: /balance-allowance/update  (NO query string in HMAC)
+```
+
+The CLOB caches balance/allowance per-API-key. Approvals on-chain are invisible until this endpoint is pinged. **Call this after every approval change.** Wait ~1s before placing orders.
+
+Verify:
+```
+GET /balance-allowance?asset_type=COLLATERAL&signature_type=2
+```
+Response:
+```json
+{
+  "balance": "2179236",
+  "allowances": {
+    "0xE111180000d2663C0091e4f400237545B87B996B": "115792089...",
+    "0xd91E80cF2E7be2e162c6513ceD06f1dD0dA35296": "115792089...",
+    "0xe2222d279d744050d28e00520010520000310F59": "115792089..."
+  }
+}
+```
+All three allowances must be non-zero.
+
+### 3. Determine `neg_risk` and pick exchange address
+
+```
+GET /neg-risk?token_id={tokenId}
+```
+Response is `{"neg_risk": true|false}`. Do NOT use `!!response` — the **object itself** is always truthy, you need to read the `.neg_risk` field.
+
+- `neg_risk: false` → sign against `CTF_EXCHANGE_V2` (`0xe111180000d2663c0091e4f400237545b87b996b`)
+- `neg_risk: true`  → sign against `NEG_RISK_EXCHANGE_V2_A` (`0xe2222d279d744050d28e00520010520000310f59`)
+
+### 4. Compute raw amounts (string-based, no floats)
+
+V2 CLOB requires clean decimal places:
+
+| Order class | maker amount | taker amount |
+|---|---|---|
+| LIMIT BUY  (tick 0.01) | ≤ 4 decimals | ≤ 2 decimals |
+| LIMIT SELL (tick 0.01) | ≤ 2 decimals | ≤ 4 decimals |
+| MARKET BUY (FAK/FOK)   | ≤ 2 decimals | ≤ 4 decimals |
+
+Use string-based conversion to avoid float precision bugs:
+
+```ts
+// BUY 4 tokens at $0.43 (cost $1.72)
+const usdcAmount  = (0.43 * 4).toFixed(4);   // "1.7200"
+const tokenAmount = (4).toFixed(2);          // "4.00"
+// → parseUnits(usdcAmount, 6) = 1720000n   (raw makerAmount)
+// → parseUnits(tokenAmount, 6) = 4000000n  (raw takerAmount)
+```
+
+`Math.trunc(0.18 * 10 * 1e6)` returns `1799999` (not `1800000`) due to IEEE 754 — DO NOT use float math.
+
+### 5. EIP-712 sign
+
+Domain:
+```json
+{
+  "name": "Polymarket CTF Exchange",
+  "version": "2",
+  "chainId": 137,
+  "verifyingContract": "<exchange address from step 3>"
+}
+```
+
+Order struct (uint256 for amounts, uint8 for side/signatureType, bytes32 for metadata/builder):
+```ts
+Order: [
+  { name: 'salt',          type: 'uint256' },
+  { name: 'maker',         type: 'address' },
+  { name: 'signer',        type: 'address' },
+  { name: 'tokenId',       type: 'uint256' },
+  { name: 'makerAmount',   type: 'uint256' },
+  { name: 'takerAmount',   type: 'uint256' },
+  { name: 'side',          type: 'uint8'   },   // 0 = BUY, 1 = SELL
+  { name: 'signatureType', type: 'uint8'   },   // 0 = EOA, 1 = PROXY, 2 = SAFE
+  { name: 'timestamp',     type: 'uint256' },
+  { name: 'metadata',      type: 'bytes32' },
+  { name: 'builder',       type: 'bytes32' },
+]
+```
+
+`taker` and `expiration` are **NOT** in the signed struct — they are post-signing payload fields.
+
+### 6. POST /order
+
+Endpoint: `POST https://clob-v2.polymarket.com/order`
+
+Exact payload shape (matches `@polymarket/clob-client-v2`):
+```json
+{
+  "order": {
+    "salt": 1776743397975,
+    "maker": "0xbdc1453718AEc6836F03964c254A5F08bFB3c038",
+    "signer": "0x3d5BB69B72E731Ac7510b6ae451D523dAd55555e",
+    "tokenId": "102941331082550455210851718765952983636922827683407411724225360467552735563141",
+    "makerAmount": "1720000",
+    "takerAmount": "4000000",
+    "side": "BUY",
+    "signatureType": 2,
+    "timestamp": "1776743397975",
+    "metadata": "0x0000000000000000000000000000000000000000000000000000000000000000",
+    "builder": "0x5472fdd700a9b2b6613d103095048c92304e97215a2607f73a9d5aa3701f3f09",
+    "signature": "0x9f52a79de5cf438330f8c894a8a111e70de944d165b5e774f91a14906302c71a2b8cb5a1194aef4291827985885d54e201a7574b6c0aa1f002436ffda185344b1b",
+    "taker": "0x0000000000000000000000000000000000000000",
+    "expiration": "0"
+  },
+  "owner": "<YOUR_CLOB_API_KEY_UUID>",
+  "orderType": "FAK",
+  "postOnly": false,
+  "deferExec": false
+}
+```
+
+Field notes:
+- `owner` = the API key UUID (not the wallet address, not the apiKey UUID of the BUILDER)
+- `orderType` = `GTC` | `GTD` | `FAK` | `FOK`
+- `taker` = zero address for public orders (private orders set this to the intended counterparty)
+- `expiration` = unix seconds, `"0"` = no expiration
+- `postOnly: true` is incompatible with `FOK`/`FAK`
+- `deferExec: false` is standard — true defers on-chain execution to a later bucket
+
+### 7. L2 HMAC headers
+
+```
+POLY_ADDRESS   = EOA that signed the API key (NOT the Safe/funder)
+POLY_API_KEY   = UUID from creds.apiKey
+POLY_PASSPHRASE= creds.apiPassphrase
+POLY_TIMESTAMP = unix seconds (string)
+POLY_SIGNATURE = base64url(HMAC-SHA256(base64_decode(secret), timestamp + method + path + body))
+                 where base64url = base64 with "+" → "-", "/" → "_"
+```
+
+Path in HMAC is `/order` only (no query string).
+
+## Fees and Budget Math
+
+Every market has a `base_fee` (in basis points of a 1.0 coefficient):
+```
+GET /fee-rate?token_id={tokenId}  → {"base_fee": 1000}   // 10%
+```
+
+Effective fee per trade (from `@polymarket/clob-client-v2`):
+```
+platformFeeRate = feeRate * (price * (1 - price)) ** feeExponent
+platformFee     = (amount / price) * platformFeeRate
+totalCost       = amount + platformFee + amount * builderTakerFeeRate
+```
+
+For a BUY of `size` tokens at `price`:
+- `amount = price * size` (raw USDC in 6 decimals)
+- `tokens_out = size`
+- Fee on trade ≈ `(price * size) * feeRate * (price * (1-price))^exponent`
+
+**You need `balance >= amount + platformFee`.** The CLOB rejects orders with "not enough balance / allowance" if balance can't cover cost + fee.
+
+Example: our 5-tokens-at-$0.42 attempts failed because `5 * 0.42 + fee = $2.15-2.20` and balance was `$2.179`. Dropping to 4 tokens put notional at `$1.72` with $0.07 fee — room to spare.
+
+Minimum notional for a MARKETABLE BUY is `$1` (not checked for non-crossing limits). Minimum size `min_order_size` in the book response is a per-market floor that the matching engine enforces at fill time, but the CLOB accepts smaller notional orders (we tested size 4 against a market with `min_order_size: 5`).
+
+## Verifying Builder Attribution
+
+After a match, the builder code flows to `/builder/trades`:
+```
+GET /builder/trades?builder_code=0x5472fdd700a9b2b6613d103095048c92304e97215a2607f73a9d5aa3701f3f09
+```
+
+Response entry confirms the on-chain settlement:
+```json
+{
+  "id": "019dae25-6845-7df6-8811-8e1bae76cf6a",
+  "tradeType": "TAKER",
+  "takerOrderHash": "0xaecd1060f7c978d0ab947eacc12a17106b7a5d087aefe04c275f3d83d2aa6281",
+  "market": "0xd76e7cbb6d6442801ca88e8433d1721c33a34a2f6d85d334e1d8331c76bf6c55",
+  "side": "BUY",
+  "size": "4.095237",
+  "sizeUsdc": "1.719999",
+  "price": "0.42",
+  "status": "TRADE_STATUS_MATCHED",
+  "transactionHash": "0xb86168562057efd161a1f9ac77ecf3728653cf9668a21567c4923a298cb24d77",
+  "feeUsdc": "0.07182",
+  "builderFee": "0",
+  "builderCode": "0x5472fdd700a9b2b6613d103095048c92304e97215a2607f73a9d5aa3701f3f09"
+}
+```
+
+The `builderCode` field ties the on-chain trade to the attribution record — the exchange contract reads it from the signed order struct, so it's cryptographically bound and can't be stripped by any intermediate.
+
+## Common Failure Modes
+
+| Error | Cause |
+|---|---|
+| `"not enough balance / allowance"` | (a) V1 NegRiskAdapter not approved for pUSD; (b) balance-allowance cache stale — run `/balance-allowance/update`; (c) balance < notional + fee |
+| `"invalid signature"` | Wrong exchange address in EIP-712 domain. Almost always caused by `neg_risk` misdetection — check the `.neg_risk` field, don't `!!` the response object |
+| `"invalid amounts, ... max accuracy of N decimals"` | Float precision in amount calc. Use `parseUnits(decimalString, 6)`, not `Math.trunc(x * 1e6)` |
+| `"no orders found to match with FAK order"` | The matching engine ran and found no crossing asks. Either (a) book API showing stale asks, or (b) price didn't actually cross — check you're using the correct tick size |
+| `"invalid amount for a marketable BUY order ($0.5), min size: $1"` | Marketable BUY notional is below $1 |
+| `"Unauthorized/Invalid api key"` on GET | HMAC computed over the **base path only** — query string must NOT be in the signing message |
+
+## Working Example
+
+See `/home/polygon/trading-lab/test-v2-real-match.mjs` for a full end-to-end example that placed and matched the order above.
+
+## Exchange Constants (Polygon mainnet, chain 137)
+
+```
+pUSD                         : 0xC011a7E12a19f7B1f670d46F03B03f3342E82DFB
+CTF (ERC-1155)               : 0x4D97DCd97eC945f40cF65F87097ACe5EA0476045
+CTF_EXCHANGE_V2              : 0xe111180000d2663c0091e4f400237545b87b996b
+NEG_RISK_EXCHANGE_V2_A       : 0xe2222d279d744050d28e00520010520000310f59
+NegRiskAdapter (V1)          : 0xd91E80cF2E7be2e162c6513ceD06f1dD0dA35296
+CtfCollateralAdapter         : 0xADa100874d00e3331D00F2007a9c336a65009718
+NegRiskCtfCollateralAdapter  : 0xAdA200001000ef00D07553cEE7006808F895c6F1
+
+CLOB_V2_HOST                 : https://clob-v2.polymarket.com
+RELAYER                      : https://relayer-v2.polymarket.com
+```

polynode/trading/clob_api.py

@@ -187,4 +187,62 @@ async def fetch_neg_risk(
     async with httpx.AsyncClient(timeout=5.0) as http:
         resp = await http.get(f"{host}/neg-risk?token_id={token_id}")
         data = resp.json()
-        return bool(data.get("neg_risk", data) if isinstance(data, dict) else data)
+        if isinstance(data, dict):
+            # Read the .neg_risk field directly — `bool(dict)` is always True for non-empty dicts.
+            return bool(data.get("neg_risk", False))
+        return bool(data)
+
+
+async def refresh_balance_allowance(
+    credentials: dict[str, str],
+    wallet_address: str,
+    signature_type: int,
+    asset_type: str = "COLLATERAL",
+) -> tuple[bool, int]:
+    """Ask the V2 CLOB to refresh its cached balance/allowance view.
+
+    The CLOB caches on-chain balance + allowance per-API-key. Changes on-chain
+    are invisible until this endpoint is pinged. Call after setting approvals.
+
+    Returns (ok, status_code).
+    """
+    path = "/balance-allowance/update"
+    headers = build_l2_headers(
+        credentials["apiKey"],
+        credentials["apiSecret"],
+        credentials["apiPassphrase"],
+        wallet_address,
+        "GET",
+        path,  # HMAC uses base path only (NO query string)
+    )
+    url = f"{CLOB_HOST_V2}{path}?asset_type={asset_type}&signature_type={signature_type}"
+    async with httpx.AsyncClient(timeout=10.0) as http:
+        resp = await http.get(url, headers=headers)
+        return resp.is_success, resp.status_code
+
+
+async def get_balance_allowance(
+    credentials: dict[str, str],
+    wallet_address: str,
+    signature_type: int,
+    asset_type: str = "COLLATERAL",
+) -> dict[str, Any] | None:
+    """Read the V2 CLOB's current cached view of balance + allowance.
+
+    Returns dict with {balance, allowances} or None on failure.
+    """
+    path = "/balance-allowance"
+    headers = build_l2_headers(
+        credentials["apiKey"],
+        credentials["apiSecret"],
+        credentials["apiPassphrase"],
+        wallet_address,
+        "GET",
+        path,  # HMAC uses base path only
+    )
+    url = f"{CLOB_HOST_V2}{path}?asset_type={asset_type}&signature_type={signature_type}"
+    async with httpx.AsyncClient(timeout=10.0) as http:
+        resp = await http.get(url, headers=headers)
+        if not resp.is_success:
+            return None
+        return resp.json()

polynode/trading/constants.py

@@ -32,7 +32,21 @@ PROXY_INIT_CODE_HASH = "0xd21df8dc65880a8606f09fe0ce3df9b8869287ab0b058be05aa9e8
 
 # All spender contracts that need approval
 SPENDERS = [CTF_EXCHANGE, NEG_RISK_CTF_EXCHANGE, NEG_RISK_ADAPTER]
-V2_SPENDERS = [CTF_EXCHANGE_V2, NEG_RISK_CTF_EXCHANGE_V2_A, NEG_RISK_CTF_EXCHANGE_V2_B]
+
+# V2 spenders that need pUSD approval.
+# Order matters: [0..2] are the three spenders the V2 CLOB validates during order placement.
+# [0] CTF_EXCHANGE_V2              — standard market orders
+# [1] NEG_RISK_CTF_EXCHANGE_V2_A   — neg-risk market orders
+# [2] NEG_RISK_ADAPTER (V1!)       — V2 neg-risk delegates settlement to V1 NRA, so the CLOB
+#                                    requires pUSD allowance here even though it's a V1 contract.
+#                                    Without this, every order fails with "not enough balance / allowance".
+# [3] NEG_RISK_CTF_EXCHANGE_V2_B   — reserved variant
+V2_SPENDERS = [
+    CTF_EXCHANGE_V2,
+    NEG_RISK_CTF_EXCHANGE_V2_A,
+    NEG_RISK_ADAPTER,
+    NEG_RISK_CTF_EXCHANGE_V2_B,
+]
 
 # PolyUSD wrapping contracts
 POLY_USD = "0xc011a7e12a19f7b1f670d46f03b03f3342e82dfb"

polynode/trading/eip712.py

@@ -318,12 +318,14 @@ async def create_signed_order_v2(
         "salt": payload.message["salt"],  # number
         "maker": funder_address,
         "signer": signer_address,
+        "taker": "0x0000000000000000000000000000000000000000",  # zero = public order (post-sign field)
         "tokenId": token_id,
         "makerAmount": str(maker_amount),
         "takerAmount": str(taker_amount),
         "side": side,  # string "BUY"/"SELL"
         "signatureType": int(signature_type),  # number
         "timestamp": str(payload.message["timestamp"]),  # string
+        "expiration": "0",  # "0" = no expiration (matches @polymarket/clob-client-v2)
         "metadata": payload.message["metadata"],
         "builder": payload.message["builder"],
         "signature": signature,

polynode/trading/onboarding.py

@@ -156,11 +156,14 @@ async def check_approvals(
     erc1155_abi = [{"inputs": [{"name": "account", "type": "address"}, {"name": "operator", "type": "address"}], "name": "isApprovedForAll", "outputs": [{"name": "", "type": "bool"}], "stateMutability": "view", "type": "function"}]
 
     if version == ExchangeVersion.V2:
+        # V2 CLOB validates three pUSD allowances during order placement:
+        # CTF_EXCHANGE_V2 (standard), NEG_RISK_CTF_EXCHANGE_V2_A (neg-risk),
+        # and V1 NEG_RISK_ADAPTER (V2 neg-risk delegates settlement to it).
         collateral_token = POLY_USD
         spender_list = [
             (CTF_EXCHANGE_V2, "ctf_exchange_v2"),
             (NEG_RISK_CTF_EXCHANGE_V2_A, "neg_risk_ctf_exchange_v2_a"),
-            (NEG_RISK_CTF_EXCHANGE_V2_B, "neg_risk_ctf_exchange_v2_b"),
+            (NEG_RISK_ADAPTER, "neg_risk_adapter"),
         ]
     else:
         collateral_token = USDC
@@ -284,8 +287,12 @@ async def set_approvals(
     return tx_hashes
 
 
-async def check_balance(funder_address: str, rpc_url: str) -> BalanceInfo:
-    """Check USDC and MATIC balance."""
+async def check_balance(
+    funder_address: str,
+    rpc_url: str,
+    version: ExchangeVersion = ExchangeVersion.V1,
+) -> BalanceInfo:
+    """Check collateral and MATIC balance. V1 reads USDC.e, V2 reads pUSD."""
     try:
         from web3 import Web3
     except ImportError:
@@ -294,10 +301,11 @@ async def check_balance(funder_address: str, rpc_url: str) -> BalanceInfo:
     w3 = Web3(Web3.HTTPProvider(rpc_url))
     erc20_abi = [{"inputs": [{"name": "account", "type": "address"}], "name": "balanceOf", "outputs": [{"name": "", "type": "uint256"}], "stateMutability": "view", "type": "function"}]
 
-    usdc_contract = w3.eth.contract(address=Web3.to_checksum_address(USDC), abi=erc20_abi)
+    collateral_token = POLY_USD if version == ExchangeVersion.V2 else USDC
+    token_contract = w3.eth.contract(address=Web3.to_checksum_address(collateral_token), abi=erc20_abi)
     funder = Web3.to_checksum_address(funder_address)
 
-    usdc_raw = usdc_contract.functions.balanceOf(funder).call()
+    usdc_raw = token_contract.functions.balanceOf(funder).call()
     matic_raw = w3.eth.get_balance(funder)
 
     return BalanceInfo(

polynode/trading/trader.py

@@ -12,8 +12,10 @@ from .clob_api import (
     cancel_order as clob_cancel_order,
     fetch_neg_risk,
     fetch_tick_size,
+    get_balance_allowance as clob_get_balance_allowance,
     get_open_orders as clob_get_open_orders,
     post_order,
+    refresh_balance_allowance as clob_refresh_balance_allowance,
 )
 from .constants import (
     COLLATERAL_OFFRAMP,
@@ -172,6 +174,26 @@ class PolyNodeTrader:
         self._active_signer = normalized
         self._active_wallet = normalized.address
 
+        # V2: force the CLOB to refresh its cached balance/allowance view. Without this,
+        # orders get rejected with "not enough balance / allowance" until the CLOB
+        # eventually notices on-chain approvals on its own.
+        if self._exchange_version == ExchangeVersion.V2 and any(
+            a.startswith("approvals") and "already" not in a for a in actions
+        ):
+            try:
+                ok, _ = await clob_refresh_balance_allowance(
+                    {
+                        "apiKey": stored.api_key,
+                        "apiSecret": stored.api_secret,
+                        "apiPassphrase": stored.api_passphrase,
+                    },
+                    normalized.address,
+                    int(sig_type),
+                )
+                actions.append("clob_cache_refreshed" if ok else "clob_cache_refresh_failed")
+            except Exception:
+                actions.append("clob_cache_refresh_failed")
+
         return ReadyStatus(
             wallet=normalized.address,
             funder_address=funder,
@@ -343,7 +365,55 @@ class PolyNodeTrader:
 
     async def check_balance(self, wallet: str | None = None) -> BalanceInfo:
         creds = self._get_stored_creds(wallet)
-        return await check_balance_onchain(creds.funder_address or creds.wallet_address, self._rpc_url)
+        return await check_balance_onchain(
+            creds.funder_address or creds.wallet_address,
+            self._rpc_url,
+            self._exchange_version,
+        )
+
+    async def refresh_balance_allowance(
+        self,
+        asset_type: str = "COLLATERAL",
+        wallet: str | None = None,
+    ) -> tuple[bool, int]:
+        """Ask the V2 CLOB to refresh its cached balance/allowance view.
+
+        No-op for V1. Call after changing on-chain approvals — without this,
+        the CLOB rejects orders with "not enough balance / allowance".
+        """
+        if self._exchange_version != ExchangeVersion.V2:
+            return True, 0
+        creds = self._get_stored_creds(wallet)
+        return await clob_refresh_balance_allowance(
+            {
+                "apiKey": creds.api_key,
+                "apiSecret": creds.api_secret,
+                "apiPassphrase": creds.api_passphrase,
+            },
+            creds.wallet_address,
+            int(creds.signature_type),
+            asset_type,
+        )
+
+    async def get_balance_allowance(
+        self,
+        asset_type: str = "COLLATERAL",
+        wallet: str | None = None,
+    ) -> dict[str, Any] | None:
+        """Read the V2 CLOB's current cached balance + allowance view. None for V1."""
+        if self._exchange_version != ExchangeVersion.V2:
+            return None
+        creds = self._get_stored_creds(wallet)
+        return await clob_get_balance_allowance(
+            {
+                "apiKey": creds.api_key,
+                "apiSecret": creds.api_secret,
+                "apiPassphrase": creds.api_passphrase,
+            },
+            creds.wallet_address,
+            int(creds.signature_type),
+            asset_type,
+        )
 
     # ── PolyUSD Wrap / Unwrap ──
 
@@ -540,6 +610,7 @@ class PolyNodeTrader:
                 signature_type=creds.signature_type,
                 tick_size=meta.tick_size,
                 neg_risk=meta.neg_risk,
+                builder=params.builder or "0x" + "00" * 32,
             )
         else:
             signed_order = await create_signed_order(
@@ -557,12 +628,16 @@ class PolyNodeTrader:
                 expiration=params.expiration or 0,
             )
 
-        payload = {
+        payload: dict[str, Any] = {
             "order": signed_order,
             "owner": creds.api_key,
             "orderType": params.type,
         }
-        if params.post_only:
+        if self._exchange_version == ExchangeVersion.V2:
+            # V2 CLOB wire format requires these top-level fields (matches @polymarket/clob-client-v2).
+            payload["postOnly"] = bool(params.post_only)
+            payload["deferExec"] = False
+        elif params.post_only:
             payload["postOnly"] = True
 
         body_str = json.dumps(payload, separators=(",", ":"))

polynode/trading/types.py

@@ -137,6 +137,9 @@ class OrderParams:
     expiration: int | None = None
     post_only: bool = False
     fee_config: FeeConfig | None = None
+    # V2 builder attribution bytes32. Mint at polymarket.com/settings?tab=builder.
+    # Defaults to zero (no attribution). Ignored on V1.
+    builder: str | None = None
 
 
 @dataclass

{polynode-0.7.4.dist-info → polynode-0.9.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: polynode
-Version: 0.7.4
+Version: 0.9.0
 Summary: Python SDK for the PolyNode real-time prediction market data platform
 Project-URL: Homepage, https://polynode.dev
 Project-URL: Documentation, https://docs.polynode.dev
@@ -109,10 +109,15 @@ asyncio.run(main())
 
 ```python
 import asyncio
-from polynode.trading import PolyNodeTrader, TraderConfig, OrderParams
+from polynode.trading import PolyNodeTrader, TraderConfig, OrderParams, ExchangeVersion
 
 async def main():
-    trader = PolyNodeTrader(TraderConfig(polynode_key="pn_live_..."))
+    # Default is V1 (USDC.e). Pass exchange_version=ExchangeVersion.V2 for the V2 CLOB
+    # (pUSD collateral, clob-v2.polymarket.com, builder attribution).
+    trader = PolyNodeTrader(TraderConfig(
+        polynode_key="pn_live_...",
+        exchange_version=ExchangeVersion.V2,
+    ))
     status = await trader.ensure_ready("0xYourPrivateKey...")
 
     result = await trader.order(OrderParams(
@@ -120,6 +125,7 @@ async def main():
         side="BUY",
         price=0.55,
         size=100,
+        builder="0x<your_builder_code_bytes32>",  # V2 only; omit for V1
     ))
     print(result)
 
@@ -128,6 +134,8 @@ async def main():
 asyncio.run(main())
 ```
 
+For the V2 order flow — required approvals, EIP-712 struct, fee math, and common failure modes — see `polynode/trading/V2_ORDER_FLOW.md` in the installed package.
+
 ## Documentation
 
 Full docs at [docs.polynode.dev](https://docs.polynode.dev)

{polynode-0.7.4.dist-info → polynode-0.9.0.dist-info}/RECORD

@@ -1,5 +1,5 @@
 polynode/__init__.py,sha256=ucqXzFPMdEcfGEAdbgOeJczREEiSCNBX1G3Il7y8-UI,1127
-polynode/_version.py,sha256=A6fZ_oURo3l_Fa_K29LgV21A4Onqu3NquwGYzL05E1Y,22
+polynode/_version.py,sha256=H9NWRZb7NbeRRPLP_V1fARmLNXranorVM-OOY-8_2ug,22
 polynode/client.py,sha256=eSCKpuZFg2ssQC5tmsfRYF3cTqCk1Gdw4KPjbd5MFHQ,21831
 polynode/engine.py,sha256=DSXBmx3DXPh-PN0ihkXn7LSiyxeOoo0iY3z4YinQ3XI,6488
 polynode/errors.py,sha256=5qUCI7K76VKbF5R5G5UYhPzcnOPlGLCA8-sJnKbrK-4,925
@@ -11,19 +11,20 @@ polynode/subscription.py,sha256=O2yKfdllI0px-1qrVK-0Qq9S4KUmIiXjjYCNC7QW0jM,4121
 polynode/testing.py,sha256=bSSgV18ZSaRoLZPlNRCCLmRNwNIQDS35qi7NhuTg8Bg,2802
 polynode/ws.py,sha256=VZdn2dkUJH2-CYBu_L45YnvCU0kQejxHcy2Ji2pRu60,9653
 polynode/cache/__init__.py,sha256=A9lXcIE3ISKKo1r0o3o-CkmQpBhLdKwdQfCR0eW5i9o,519
+polynode/trading/V2_ORDER_FLOW.md,sha256=Ppd7iwZjtmVwok-fP4Ofo4UBQ9pIAg0t57RJ-OzqRHs,10926
 polynode/trading/__init__.py,sha256=sPv30j9eyvqjnUBxGAYaKpAPQZ2jTw3UwA4DZXYZ21s,923
-polynode/trading/clob_api.py,sha256=ygaOoMIg4PGtMzNBT70wk4XrSbVX0EyCCU6PmXK3xrs,5308
-polynode/trading/constants.py,sha256=_DDwutJkOfeyPkClrTcyJCOYMoqDymZzDpjYWeHbfG0,1862
+polynode/trading/clob_api.py,sha256=Sfb8XLN9MMzVE6jARNqEQxiD608OC_6Xjc7uiJbDQEc,7274
+polynode/trading/constants.py,sha256=aW8F9Q2W0TRNVX0JNh39k0qxbb03ijUAGbWjrJFjf_o,2513
 polynode/trading/cosigner.py,sha256=Fww9OgaKdHQAHd8Kom1AJBtmMGC8FbNZxdFaFALNBY8,3058
-polynode/trading/eip712.py,sha256=pZf0Pf4DDIPpK4qbz4DWfcdOeU8PlCQhJPpKSQ97pC4,9553
+polynode/trading/eip712.py,sha256=PKLfMt58Diy419jiQXysnX1kSlU_QcWDRofGEb3u_JI,9744
 polynode/trading/escrow.py,sha256=bU_ohyOlx2r6KjBYxUNdjROvrmunWV1Ey99AuSOt9Z8,4590
-polynode/trading/onboarding.py,sha256=-Ub5tsJA4vqPJmkNLx2OE_szUY08UmXYi_9ATThajkA,14670
+polynode/trading/onboarding.py,sha256=oXtFz1HF1vGvMnb5o44SwuADd2mdU5ws1v7n30rk6fg,15066
 polynode/trading/position_management.py,sha256=z2pYls4ErhyRE6thQdOs45BF4llKvKNNruQgcMEFT_U,3827
 polynode/trading/privy.py,sha256=iiUQZsBqjj29C7oUiFFktoT2muZY06bcMzABKstFKqE,4523
 polynode/trading/signer.py,sha256=piifRquwnwFwrKLL24jsRQYMh_cdkz8wNz99Vx8_KTY,3413
 polynode/trading/sqlite_backend.py,sha256=zfo4WevuunWV-7i6Z3gQi_e7Tonw-7m1TsEd88O5I4w,9486
-polynode/trading/trader.py,sha256=eAdFhZz0KLr_oXBb5LsW7JHUuNCSfZuWaCn4XIqVByM,31798
-polynode/trading/types.py,sha256=JxhjsRRhh8WA127VNNPLf7QJKn5e_PZucaG7WAfdOsM,5528
+polynode/trading/trader.py,sha256=VpOwZ0TEwkOSRSLSAZ1LxjEJfxPkH3RO-XFrH6RG5Ys,34845
+polynode/trading/types.py,sha256=mo5zJRlfQLWuXwrkS9AaGqKWrt7FMf6bPGRE-0T62J0,5698
 polynode/types/__init__.py,sha256=0v_CByqG-zT1xucbT2So_77YDmsPj9u956at94nyrLM,280
 polynode/types/enums.py,sha256=2cx9l10A-LUeDNBJZn7l0XBTka2YfxRQcXW0s7s3_4k,1082
 polynode/types/events.py,sha256=MJGZqxBFKfT1y44dZ96bHbwvoPpGvtutBwYE6OTT6nU,6880
@@ -31,6 +32,6 @@ polynode/types/orderbook.py,sha256=MwD6P3poo3F70bONUZ5i3ajk1sgw39hHTOw6D0fP5_8,1
 polynode/types/rest.py,sha256=ftJKQZH0wBrR_l199rDMqnVS8cyt8YnCvo9cKIsTcCw,7012
 polynode/types/short_form.py,sha256=xfGklDi587u6K2aXaRWiwbxqkipW8BiEPeNIDT45v2Y,799
 polynode/types/ws.py,sha256=EzE9Vzrb6cILemfssmnqM8fbHt4USn3latpUHKatwk4,994
-polynode-0.7.4.dist-info/METADATA,sha256=YMkUQnSt2Vpc8Sd7vIlttfD8oenHGDk_xKHMqpf2JEg,3302
-polynode-0.7.4.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
-polynode-0.7.4.dist-info/RECORD,,
+polynode-0.9.0.dist-info/METADATA,sha256=mzGKeGUGX-EvRNytrdz2FS7uq-N4-m944fpaW2GujoU,3777
+polynode-0.9.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+polynode-0.9.0.dist-info/RECORD,,