polynode 0.7.3__tar.gz → 0.9.2__tar.gz

{polynode-0.7.3 → polynode-0.9.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: polynode
-Version: 0.7.3
+Version: 0.9.2
 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.3 → polynode-0.9.2}/README.md

@@ -76,10 +76,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(
@@ -87,6 +92,7 @@ async def main():
         side="BUY",
         price=0.55,
         size=100,
+        builder="0x<your_builder_code_bytes32>",  # V2 only; omit for V1
     ))
     print(result)
 
@@ -95,6 +101,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.9.2/polynode/_version.py

@@ -0,0 +1 @@
+__version__ = "0.9.1"

polynode-0.9.2/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-0.7.3 → polynode-0.9.2}/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-0.7.3 → polynode-0.9.2}/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"
@@ -40,7 +54,10 @@ COLLATERAL_ONRAMP = "0x93070a847efef7f70739046a929d47a521f5b8ee"
 COLLATERAL_OFFRAMP = "0x2957922eb93258b93368531d39facca3b4dc5854"
 
 # Fee Escrow
+# V1 (USDC.e collateral, paired with the V1 CLOB)
 FEE_ESCROW_ADDRESS = "0xa11D28433B79D0A88F3119b16A090075752258EA"
+# V2 (pUSD collateral, paired with the V2 CLOB). Deployed 2026-04-24.
+FEE_ESCROW_ADDRESS_V2 = "0x3A43D88ef8Aae4dF5a50B3abf67122CAAeEF7c9F"
 
 # Metadata cache TTL (5 minutes)
 META_TTL_SECONDS = 300

{polynode-0.7.3 → polynode-0.9.2}/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-0.7.3 → polynode-0.9.2}/polynode/trading/escrow.py

@@ -14,10 +14,15 @@ from typing import Any
 
 import httpx
 
-from .constants import CHAIN_ID, FEE_ESCROW_ADDRESS
-from .types import Eip712Payload
+from .constants import CHAIN_ID, FEE_ESCROW_ADDRESS, FEE_ESCROW_ADDRESS_V2
+from .types import Eip712Payload, ExchangeVersion
 
 # ── EIP-712 Types ──
+#
+# Both V1 and V2 FeeEscrow share the same FeeAuth struct typehash. They differ only in
+# the EIP-712 domain: V1 is ("PolyNodeFeeEscrow", "1", V1 contract); V2 is
+# ("PolyNodeFeeEscrowV2", "2", V2 contract). Signing against the wrong domain produces
+# a digest the contract won't accept — `pullFee` reverts with `InvalidSignature`.
 
 FEE_AUTH_DOMAIN = {
     "name": "PolyNodeFeeEscrow",
@@ -26,6 +31,13 @@ FEE_AUTH_DOMAIN = {
     "verifyingContract": FEE_ESCROW_ADDRESS,
 }
 
+FEE_AUTH_DOMAIN_V2 = {
+    "name": "PolyNodeFeeEscrowV2",
+    "version": "2",
+    "chainId": CHAIN_ID,
+    "verifyingContract": FEE_ESCROW_ADDRESS_V2,
+}
+
 FEE_AUTH_TYPES = {
     "FeeAuth": [
         {"name": "orderId", "type": "bytes32"},
@@ -40,6 +52,16 @@ FEE_AUTH_TYPES = {
 ZERO_ADDRESS = "0x0000000000000000000000000000000000000000"
 
 
+def fee_auth_domain_for(version: ExchangeVersion) -> dict:
+    """Return the EIP-712 FeeAuth domain for a given exchange version."""
+    return FEE_AUTH_DOMAIN_V2 if version == ExchangeVersion.V2 else FEE_AUTH_DOMAIN
+
+
+def fee_escrow_address_for(version: ExchangeVersion) -> str:
+    """Return the FeeEscrow contract address for a given exchange version."""
+    return FEE_ESCROW_ADDRESS_V2 if version == ExchangeVersion.V2 else FEE_ESCROW_ADDRESS
+
+
 # ── Fee Calculation ──
 
 def calculate_fee(price: float, size: float, fee_bps: int) -> int:
@@ -67,8 +89,17 @@ def generate_escrow_order_id() -> str:
 
 # ── Nonce Fetching ──
 
-async def fetch_escrow_nonce(rpc_url: str, signer_address: str) -> int:
-    """Fetch the current nonce for a signer from the FeeEscrow contract via eth_call."""
+async def fetch_escrow_nonce(
+    rpc_url: str,
+    signer_address: str,
+    escrow_address: str = FEE_ESCROW_ADDRESS,
+) -> int:
+    """Fetch the current nonce for a signer from a FeeEscrow contract via eth_call.
+
+    Pass `fee_escrow_address_for(exchange_version)` for the `escrow_address` argument
+    when the caller's exchange version is known (V2 customers must read nonces from
+    the V2 contract — nonces on V1 and V2 are tracked independently).
+    """
     # getNonce(address) selector = 0x2d0335ab
     addr = signer_address.lower().replace("0x", "").zfill(64)
     data = "0x2d0335ab" + addr
@@ -80,7 +111,7 @@ async def fetch_escrow_nonce(rpc_url: str, signer_address: str) -> int:
                 "jsonrpc": "2.0",
                 "id": 1,
                 "method": "eth_call",
-                "params": [{"to": FEE_ESCROW_ADDRESS, "data": data}, "latest"],
+                "params": [{"to": escrow_address, "data": data}, "latest"],
             },
         )
         result = resp.json()
@@ -103,6 +134,9 @@ class FeeAuthRequest:
     signature: str
     affiliate: str
     affiliate_share_bps: int
+    # V2-routing hint for the cosigner. Set when exchange_version == V2 so the
+    # cosigner picks the V2 operator; absent for V1 (preserves backwards compat).
+    escrow_contract: str | None = None
 
 
 async def sign_fee_auth(
@@ -116,19 +150,22 @@ async def sign_fee_auth(
     nonce: int,
     affiliate: str | None = None,
     affiliate_share_bps: int | None = None,
+    exchange_version: ExchangeVersion = ExchangeVersion.V1,
 ) -> FeeAuthRequest:
     """Sign a FeeAuth EIP-712 message.
 
     Args:
         sign_typed_data: Callable that signs an Eip712Payload and returns a hex signature.
         escrow_order_id: Random bytes32 hex string.
-        payer: Safe wallet address (where USDC is pulled from).
+        payer: Safe wallet address (where collateral is pulled from — USDC.e on V1, pUSD on V2).
         signer_address: EOA address (signs the message).
-        fee_amount: Fee in raw USDC (6 decimals).
+        fee_amount: Fee in raw collateral units (6 decimals).
         deadline: Unix timestamp — authorization expires after this.
         nonce: Signer's current nonce from the escrow contract.
         affiliate: Partner wallet address.
         affiliate_share_bps: Partner's share of fee in bps.
+        exchange_version: V1 (default, USDC.e) or V2 (pUSD). Selects the EIP-712 domain
+            and the escrow contract address the cosigner should route to.
 
     Returns:
         FeeAuthRequest ready for the cosigner.
@@ -143,7 +180,7 @@ async def sign_fee_auth(
     }
 
     payload = Eip712Payload(
-        domain=FEE_AUTH_DOMAIN,
+        domain=fee_auth_domain_for(exchange_version),
         types=FEE_AUTH_TYPES,
         primary_type="FeeAuth",
         message=message,
@@ -153,6 +190,10 @@ async def sign_fee_auth(
     if not signature.startswith("0x"):
         signature = f"0x{signature}"
 
+    escrow_contract = (
+        FEE_ESCROW_ADDRESS_V2 if exchange_version == ExchangeVersion.V2 else None
+    )
+
     return FeeAuthRequest(
         escrow_order_id=escrow_order_id,
         payer=payer,
@@ -163,4 +204,5 @@ async def sign_fee_auth(
         signature=signature,
         affiliate=affiliate or ZERO_ADDRESS,
         affiliate_share_bps=affiliate_share_bps if affiliate_share_bps is not None else 10000,
+        escrow_contract=escrow_contract,
     )