feat(v2): flip ClobClient to V2 — order struct, EIP-712 v2, match-time fees

[smypmsa]

Context

With the V2 parallel stack ready and collateral plumbing migrated (issues earlier in this series), this issue flips the production trading path to py-clob-client-v2 and adapts to the V2 order structure, signing scheme, and fee model.

• Cutover: 2026-04-28 ~11:00 UTC
• All open V1 limit orders wiped at cutover; no backward compatibility

References:

• V2 Migration Guide
• py-clob-client-v2 1.0.0
• Changelog: CLOB V2 Upgrade
• Pre-cutover endpoint: https://clob-v2.polymarket.com

Order-struct deltas (V1 → V2)

• Drop fields: feeRateBps, nonce, taker
• Add fields: timestamp (milliseconds), metadata, builder (builder code — leave empty/null unless we register one)
• EIP-712 Exchange domain version: \"1\" → \"2\"
• SDK constructor: positional args → options object; chainId renamed to chain

Fee model change

V2 calculates taker fees at match time via getClobMarketInfo(). Orders no longer carry feeRateBps. The feeSchedule plumbing introduced earlier remains useful for pre-trade cost display, but the signing path must change:

• Stop setting feeRateBps on signed V2 orders
• Keep feeSchedule enrichment in pipeline outputs for UI cost estimates
• Revisit _calculate_pnl to deduct realized taker fees from proceeds (either from the V2 fill response or from the cached feeSchedule as an approximation)

Scope

Production code (behind POLYMARKET_V2_ENABLED):

• backend/core/trading/clob_client.py — V2 ClobClient becomes the production path when the flag is set
• backend/core/trading/clob.py — post_order builds the new order struct (drop/add fields above), no manual fee math
• backend/core/fees.py — split into display_fee (uses feeSchedule) and remove the signed-order fee path
• backend/core/positions/service.py _calculate_pnl — adapt to match-time fees

Experiments to mirror:

• experiments/trading/03_buy_position.py — V2 order placement when flag is set

Validation

• Manual paper sell against https://clob-v2.polymarket.com succeeds with the new order struct
• EIP-712 signature verifies against domain version \"2\"
• Unit test for the order-builder asserts removed/added fields
• P&L on a closed test position reflects the match-time fee within ~1 bps of expected

Out of scope

• Removing V1 client and V1 fee path — separate post-cutover cleanup issue.
• HeartBeats / Post Only orders — not part of this bot's strategy today.

Deadline

Land + validated by 2026-04-27 EOD. Cutover flip (POLYMARKET_V2_ENABLED=true) executes at 2026-04-28 11:00 UTC.

Prerequisites

• feat(v2-prep): parallel V2 stack — py-clob-client-v2, V2 contracts, pUSD config #27 must merge first — provides V2 SDK, V2 ClobClient init scaffold, and feature flag.
• feat(v2): collateral plumbing — USDC.e → pUSD #28 must merge first — collateral must be pUSD before V2 orders are signed; otherwise signed orders reference the wrong asset.

Blocks

• chore(v2): retire V1 paths post-cutover #37 (V1 retirement) — V2 must be live and stable before V1 paths are removed.