polynode 0.14.0__tar.gz → 0.15.0__tar.gz

{polynode-0.14.0 → polynode-0.15.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: polynode
-Version: 0.14.0
+Version: 0.15.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
@@ -36,7 +36,11 @@ Description-Content-Type: text/markdown
 
 Python SDK for the [Polynode](https://polynode.dev) real-time prediction market data platform.
 
-**New in v0.14.0:** Web platforms can take a user from wallet authorization through an exact browser-signed user-owned order without exposing backend credentials. The SDK imports the shared versioned browser bundle into memory, produces a credential-free signing request with a complete order preview, supports one-time multi-worker state, validates canonical signatures and wallet identity, checks BUY collateral before prompting, and submits with exact zero builder attribution.
+**New in v0.15.0:** Polymarket Protocol V2 markets (October 2026). Upgrade before 2026-11-02 if you trade: `order()` looks up each market's protocol and signs Protocol V2 orders for the right exchange automatically, and split, merge and the new redeem work on them too. Nothing changes for current markets or for streaming and REST users. This is not the April 2026 "V2" (CTF Exchange V2 and pUSD) described elsewhere in this README; see [Polymarket Protocol V2 markets](#polymarket-protocol-v2-markets).
+
+**In v0.14.1:** Every prepared user-owned order exposes its canonical V2 exchange `order_hash` before submission. This is the exact CLOB/open-order ID and fill `order_hash`; deposit-wallet orders hash the standard inner `Order`, not the POLY_1271 wallet-signing wrapper. Record it before the network attempt so timeouts can be reconciled without risking a duplicate.
+
+**In v0.14.0:** Web platforms can take a user from wallet authorization through an exact browser-signed user-owned order without exposing backend credentials. The SDK imports the shared versioned browser bundle into memory, produces a credential-free signing request with a complete order preview, supports one-time multi-worker state, validates canonical signatures and wallet identity, checks BUY collateral before prompting, and submits with exact zero builder attribution.
 
 **In v0.13.0:** Trading added explicit `user_owned` execution. Existing builder mode remains the default; opted-in wallets use zero builder attribution, one wallet-ownership authorization, and strict wallet-bound gasless credentials. Builder credentials and nonzero builder codes fail closed in this mode. EOA-controlled Safe and deposit wallets are supported; legacy Magic/proxy wallets are intentionally excluded from the first release.
 
@@ -70,7 +74,6 @@ with PolyNode(api_key="pn_live_...") as pn:
     status = pn.status()
     connections = pn.connections()
     markets = pn.markets(count=10)
-    settlements = pn.recent_settlements(count=5)
     wallet_positions = pn.wallet_positions(
         address, redeemable=True, condition_id=condition_id
     )
@@ -125,7 +128,7 @@ asyncio.run(main())
 
 ### Complete V3 API
 
-V3 includes wallets, combos, rewards, credits, identities, markets, builders, profiles, perps, crypto, sports, backtesting, and other current product families. `execute()` gives you access to all 120 current V3 operations through one consistent Python interface.
+V3 includes wallets, combos, rewards, credits, identities, markets, events, builders, profiles, perps, crypto, sports, backtesting, and other current product families. `execute()` gives you access to all 129 current V3 operations through one consistent Python interface.
 
 ```python
 import asyncio
@@ -133,7 +136,7 @@ from polynode import AsyncPolyNode
 
 async def read_v3(address: str):
     async with AsyncPolyNode(api_key="pn_live_...") as pn:
-        print(len(pn.v3.operations))  # 120
+        print(len(pn.v3.operations))  # 128
 
         combo_activity = await pn.v3.execute(
             "GET /v3/combos/activity",
@@ -144,11 +147,76 @@ async def read_v3(address: str):
             path_params={"address": address},
             query={"limit": 100},
         )
-        return combo_activity, wallet_rewards
+        scopes = await pn.v3.execute(
+            "GET /v3/leaderboard/scopes",
+            query={"period": "7d", "scope": "category"},
+        )
+        markets = await pn.v3.execute(
+            "GET /v3/markets",
+            query={"status": "open", "limit": 100},
+        )
+        return combo_activity, wallet_rewards, scopes, markets
 
 asyncio.run(read_v3("0xabc..."))
 ```
 
+Use the typed Combo P&L helper for All Time realized, unrealized, and total
+P&L, or realized P&L over a fixed or custom half-open window:
+
+```python
+from polynode import PolyNodeV3
+
+with PolyNodeV3("pn_live_...") as v3:
+    all_time = v3.combo_pnl_leaderboard(
+        period="all",
+        sort_by="total_pnl",
+    )
+    custom = v3.combo_pnl_leaderboard(
+        period="custom",
+        after=1_788_134_400,
+        before=1_788_220_800,
+        sort_by="realized_pnl",
+    )
+```
+
+Wallets with incomplete arbitrary transfer basis or without a current mark are
+omitted rather than returned with zero P&L. Inspect `coverage` on every response
+before presenting the ranking.
+
+Market and event catalogs use opaque cursor pagination. Reward-market list
+rows include nullable title, slug, image, event, category, and tag fields.
+
+Named perps helpers accept the returned opaque cursor:
+
+```python
+from polynode import PolyNodeV3
+
+with PolyNodeV3(api_key="pn_live_...") as v3:
+    first = v3.perps_trades(
+        "BTC-USD",
+        after=1_787_875_200,
+        before=1_787_961_600,
+        limit=100,
+    )
+    if first.get("next_cursor"):
+        second = v3.perps_trades(
+            "BTC-USD",
+            after=1_787_875_200,
+            before=1_787_961_600,
+            limit=100,
+            cursor=first["next_cursor"],
+        )
+
+    events = v3.perps_events(address=address, limit=100)
+    liquidations = v3.perps_liquidations(min_notional=10_000)
+    flows = v3.perps_wallet_flows(address, limit=100)
+```
+
+Reuse the same route and filters on every cursor page. Wallet-flow totals and
+counts remain fixed during one traversal. Cumulative volume delta remains a
+bounded single-page series and has no cursor helper. Async clients expose the
+same methods with `await`.
+
 The SDK encodes path parameters for you. Read requests that are safe to repeat retry transient failures and honor `Retry-After`; requests that change data are never retried automatically. JSON decimals decode as `Decimal`, and `ApiError` exposes the status, request ID, retry details, and a request URL with credentials removed.
 
 Current presets include `dome`, `fills`, `combos`, `redemptions`, and `deposits`. Current filters include `since()`, `combo_condition_ids()`, `leg_position_ids()`, `event_ids()`, `module_ids()`, `action()`, and `direction()`.
@@ -299,6 +367,43 @@ For the V2 order flow, required approvals, and common failure modes, see [docs.p
 
 V2 fees are determined at match time and are not signed into an order, so V2 payloads omit `feeRateBps`, `nonce`, and `taker`. Explicit legacy V1 mode still signs `feeRateBps`; for that path the SDK fetches `/fee-rate` and fails closed if fee, tick-size, or neg-risk metadata is unavailable or malformed.
 
+#### Polymarket Protocol V2 markets
+
+> **Two different "V2"s.** Polymarket Protocol V2 (October 2026) is Polymarket's new position system: positions live in a new ledger (PositionManager), every market type trades on one new exchange (ExchangeV3, order signing domain version `"3"`), and split, merge and redeem go through a Router. It is **not** the April 2026 upgrade (CTF Exchange V2 with pUSD collateral) that `ExchangeVersion.V2` and the rest of this README call "V2". Current markets keep using the April exchanges.
+
+**When.** Polymarket's test markets for Protocol V2 trade from 2026-10-05 to 2026-10-30. New markets move to Protocol V2 from around 2026-11-02 (tentative, per Polymarket). Existing markets stay where they are.
+
+**What you need to do.**
+
+- Streaming and REST only: nothing. Same methods, same response shapes. Rows and events for Protocol V2 markets carry a few optional fields: `protocol_version: "v2"`, `module` (`"binary"` or `"neg_risk"`), `exchange_version: "v3"` on fills, and `payouts_ppm` / `derived` on oracle events. A row without them is a current market.
+- Trading: upgrade to `polynode` 0.15.0 before 2026-11-02 and place orders exactly as before. Older versions keep working on current markets, but Polymarket rejects their orders on Protocol V2 markets (no funds move).
+- Storing ids yourself: keep outcome ids as strings (up to 78 digits). Condition ids are returned in the 66-character form; the 64-character form is accepted as input.
+
+The first order on a Protocol V2 market grants the two approvals it needs (pUSD and PositionManager, both for ExchangeV3): one gasless batch for Safe and deposit wallets, or two transactions with a little POL gas for an EOA. To do it ahead of time, or for browser-signed user-owned orders, call `ensure_ready` once with `protocol_v2=True`. Plain `ensure_ready()` behaves exactly as before.
+
+```python
+from polynode.trading import MergeParams, RedeemParams, SplitParams
+
+await trader.ensure_ready("0xYourPrivateKey...", protocol_v2=True)  # optional
+version = await trader.get_market_protocol(token_id)  # "v1" (current) or "v2"
+
+# Same call for every market; the SDK picks the exchange and signing domain.
+await trader.order(OrderParams(token_id=token_id, side="BUY", price=0.5, size=10))
+
+# Position operations (user-owned execution) route through the Router on V2 markets.
+await trader.execute_split(SplitParams(condition_id=condition_id, amount=10))
+await trader.execute_merge(MergeParams(condition_id=condition_id, amount=10))
+await trader.execute_redeem(RedeemParams(condition_id=condition_id, outcome_index=0))  # 0 = YES, 1 = NO
+payout = await trader.preview_payout(position_id, 10)  # None until resolved
+
+status = await trader.check_approvals(protocol_v2=True)
+print(status.protocol_v2_ready, status.position_ops_v2_ready, status.auto_redeem_enabled)
+```
+
+The SDK learns a market's protocol from Polymarket's market data and caches it for 24 hours in a new local table (existing tables are unchanged). It never guesses from the shape of an id: if the protocol cannot be learned, the order is refused with a retryable `MarketProtocolError` instead of being signed for the wrong exchange. Pass `protocol_version="v2"` (or call `trader.hint_market_protocol(...)`) to skip the lookup; a value that contradicts what the SDK already knows is refused. Short-form streams pick `positionIds` for Protocol V2 markets and expose `market.protocol_version`, so orders on discovered markets skip the lookup.
+
+Results of Protocol V2 markets are shares of 1,000,000 (`[1000000, 0]` = YES won, `[500000, 500000]` = 50/50); `payouts` carries the same result in smallest whole numbers, like current markets. `RedemptionWatcher` handles both. Automatic redemption by Polymarket's AutoRedeemer is opt-in only (`enable_auto_redeem()` / `disable_auto_redeem()`); proceeds always return to your wallet. Converting neg-risk positions is not supported for Protocol V2 markets yet.
+
 #### Optional user-owned execution
 
 Set `execution_mode=ExecutionMode.USER_OWNED` when the signing wallet should trade with zero builder attribution and use its own gasless authorization. Builder mode remains the default and existing integrations are unchanged.
@@ -536,29 +641,82 @@ const result = await fetch("/api/orders/submit", {
 }).then((response) => response.json());
 ```
 
-On the backend, atomically take the prepared object from session state, then validate and submit it:
+On the backend, atomically take the prepared object from session state, durably record the deterministic order identity, then validate and submit it:
 
 ```python
-async def submit_order(trader, browser_result, prepared_orders):
+async def submit_order(trader, browser_result, prepared_orders, attempts):
     # `take_once` must delete atomically so two workers cannot submit the same request.
     prepared = await prepared_orders.take_once(browser_result.request_id)
     if prepared is None:
         raise ValueError("Unknown or already-used signing request")
 
-    result = await trader.submit_prepared_user_owned_order(
-        prepared,
+    order_hash = prepared.order_hash
+    # This durable, idempotent write must commit before submission starts.
+    await attempts.create_once(
+        order_hash=order_hash,
         request_id=browser_result.request_id,
-        address=browser_result.address,
-        signature=browser_result.signature,
+        wallet=prepared.signing_request.address,
+        token_id=prepared.signing_request.order["tokenId"],
+        side=prepared.signing_request.order["side"],
+        status="submitting",
     )
-    return {
-        "success": result.success,
-        "orderId": result.order_id,
-        "error": result.error,
-    }
+
+    try:
+        result = await trader.submit_prepared_user_owned_order(
+            prepared,
+            request_id=browser_result.request_id,
+            address=browser_result.address,
+            signature=browser_result.signature,
+        )
+    except BaseException:
+        # Once consumed, a local/network exception has an ambiguous outcome.
+        status = (
+            "outcome_unknown"
+            if prepared.consumed
+            else "rejected_before_submission"
+        )
+        await attempts.set_status(order_hash, status)
+        raise
+    else:
+        if result.order_id and result.order_id.lower() != order_hash.lower():
+            await attempts.set_status(order_hash, "identity_mismatch")
+            raise RuntimeError("CLOB returned an unexpected order ID")
+        await attempts.record_response(order_hash, result)
+        return {
+            "success": result.success,
+            "orderId": result.order_id or order_hash,
+            "error": result.error,
+        }
 ```
 
-`prepare_user_owned_order()` supports V2 user-owned execution only, expires after five minutes by default, forces zero builder attribution, rejects positive fee authentication, and performs no submission. GTC, FOK, and FAK orders must omit expiration (zero is accepted and canonicalized to no expiration); GTD requires a fresh Unix-seconds expiration with the 60-second safety buffer, and the signing request is clamped to that window. `submit_prepared_user_owned_order()` verifies the request ID, expiry, connected wallet, stored wallet/funder identity, exact typed data, and recovered signer before consuming the request. A consumed request cannot be replayed. If submission has an ambiguous network result, reconcile its status instead of preparing an automatic duplicate.
+`prepared.order_hash` is the lowercase `0x`-prefixed EIP-712 digest of the canonical standard exchange `Order`. For EOA and Safe orders it also matches the browser-signing digest. POLY_1271 browsers sign an outer `TypedDataSign` wrapper, whose digest is intentionally different; `order_hash` always identifies the inner order that the CLOB and fills report. The property is computed on demand, is unchanged by trusted-state export/import, and is not added to the serialized schema.
+
+`prepare_user_owned_order()` supports V2 user-owned execution only, expires after five minutes by default, forces zero builder attribution, rejects positive fee authentication, and performs no submission. GTC, FOK, and FAK orders must omit expiration (zero is accepted and canonicalized to no expiration); GTD requires a fresh Unix-seconds expiration with the 60-second safety buffer, and the signing request is clamped to that window. `submit_prepared_user_owned_order()` verifies the request ID, expiry, connected wallet, stored wallet/funder identity, exact typed data, and recovered signer before consuming the request. A consumed request cannot be replayed.
+
+Treat any exception after `prepared.consumed` becomes true—including an HTTP timeout, disconnect, cancellation, or local failure around the network call—as `outcome_unknown`. Never submit that hash again and never automatically prepare a replacement. Reconcile by exact hash against both `await trader.get_open_orders(asset_id=token_id)` (`OpenOrder.id`) and your durable authenticated V2 fill source (`fill.order_hash`):
+
+```python
+async def reconcile_unknown(trader, attempt, fills):
+    open_orders = await trader.get_open_orders(asset_id=attempt.token_id)
+    open_order = next(
+        (order for order in open_orders if order.id.lower() == attempt.order_hash.lower()),
+        None,
+    )
+    matching_fills = await fills.by_order_hash(attempt.order_hash)
+    return {"openOrder": open_order, "fills": matching_fills}
+```
+
+An open order may already be partially filled (`size_matched` is nonzero), while a fully filled or canceled order will not remain open. Group all partial fills for the exact hash. Finding neither an open order nor a fill is not proof that submission failed: keep the attempt unknown and retry reconciliation with bounded backoff. The application-owned attempt store and fill source must be durable, wallet-scoped, and idempotent by `order_hash`; do not infer identity from token, side, amounts, timestamps, balances, or request ID.
+
+If a request-scoped trader was populated from a browser bundle or decrypted vault record, clear its credentials even when validation, signing, submission, or reconciliation fails:
+
+```python
+trader = await trader_from_browser_bundle(request_json)
+try:
+    result = await submit_order(trader, browser_result, prepared_orders, attempts)
+finally:
+    trader.close()
+```
 
 For a single-process application, a backend-only in-memory dictionary is sufficient. For multiple workers, serialize only with the SDK's trusted server-state methods and use a server-side store that can atomically take/delete by `requestId`:
 

{polynode-0.14.0 → polynode-0.15.0}/README.md

@@ -2,7 +2,11 @@
 
 Python SDK for the [Polynode](https://polynode.dev) real-time prediction market data platform.
 
-**New in v0.14.0:** Web platforms can take a user from wallet authorization through an exact browser-signed user-owned order without exposing backend credentials. The SDK imports the shared versioned browser bundle into memory, produces a credential-free signing request with a complete order preview, supports one-time multi-worker state, validates canonical signatures and wallet identity, checks BUY collateral before prompting, and submits with exact zero builder attribution.
+**New in v0.15.0:** Polymarket Protocol V2 markets (October 2026). Upgrade before 2026-11-02 if you trade: `order()` looks up each market's protocol and signs Protocol V2 orders for the right exchange automatically, and split, merge and the new redeem work on them too. Nothing changes for current markets or for streaming and REST users. This is not the April 2026 "V2" (CTF Exchange V2 and pUSD) described elsewhere in this README; see [Polymarket Protocol V2 markets](#polymarket-protocol-v2-markets).
+
+**In v0.14.1:** Every prepared user-owned order exposes its canonical V2 exchange `order_hash` before submission. This is the exact CLOB/open-order ID and fill `order_hash`; deposit-wallet orders hash the standard inner `Order`, not the POLY_1271 wallet-signing wrapper. Record it before the network attempt so timeouts can be reconciled without risking a duplicate.
+
+**In v0.14.0:** Web platforms can take a user from wallet authorization through an exact browser-signed user-owned order without exposing backend credentials. The SDK imports the shared versioned browser bundle into memory, produces a credential-free signing request with a complete order preview, supports one-time multi-worker state, validates canonical signatures and wallet identity, checks BUY collateral before prompting, and submits with exact zero builder attribution.
 
 **In v0.13.0:** Trading added explicit `user_owned` execution. Existing builder mode remains the default; opted-in wallets use zero builder attribution, one wallet-ownership authorization, and strict wallet-bound gasless credentials. Builder credentials and nonzero builder codes fail closed in this mode. EOA-controlled Safe and deposit wallets are supported; legacy Magic/proxy wallets are intentionally excluded from the first release.
 
@@ -36,7 +40,6 @@ with PolyNode(api_key="pn_live_...") as pn:
     status = pn.status()
     connections = pn.connections()
     markets = pn.markets(count=10)
-    settlements = pn.recent_settlements(count=5)
     wallet_positions = pn.wallet_positions(
         address, redeemable=True, condition_id=condition_id
     )
@@ -91,7 +94,7 @@ asyncio.run(main())
 
 ### Complete V3 API
 
-V3 includes wallets, combos, rewards, credits, identities, markets, builders, profiles, perps, crypto, sports, backtesting, and other current product families. `execute()` gives you access to all 120 current V3 operations through one consistent Python interface.
+V3 includes wallets, combos, rewards, credits, identities, markets, events, builders, profiles, perps, crypto, sports, backtesting, and other current product families. `execute()` gives you access to all 129 current V3 operations through one consistent Python interface.
 
 ```python
 import asyncio
@@ -99,7 +102,7 @@ from polynode import AsyncPolyNode
 
 async def read_v3(address: str):
     async with AsyncPolyNode(api_key="pn_live_...") as pn:
-        print(len(pn.v3.operations))  # 120
+        print(len(pn.v3.operations))  # 128
 
         combo_activity = await pn.v3.execute(
             "GET /v3/combos/activity",
@@ -110,11 +113,76 @@ async def read_v3(address: str):
             path_params={"address": address},
             query={"limit": 100},
         )
-        return combo_activity, wallet_rewards
+        scopes = await pn.v3.execute(
+            "GET /v3/leaderboard/scopes",
+            query={"period": "7d", "scope": "category"},
+        )
+        markets = await pn.v3.execute(
+            "GET /v3/markets",
+            query={"status": "open", "limit": 100},
+        )
+        return combo_activity, wallet_rewards, scopes, markets
 
 asyncio.run(read_v3("0xabc..."))
 ```
 
+Use the typed Combo P&L helper for All Time realized, unrealized, and total
+P&L, or realized P&L over a fixed or custom half-open window:
+
+```python
+from polynode import PolyNodeV3
+
+with PolyNodeV3("pn_live_...") as v3:
+    all_time = v3.combo_pnl_leaderboard(
+        period="all",
+        sort_by="total_pnl",
+    )
+    custom = v3.combo_pnl_leaderboard(
+        period="custom",
+        after=1_788_134_400,
+        before=1_788_220_800,
+        sort_by="realized_pnl",
+    )
+```
+
+Wallets with incomplete arbitrary transfer basis or without a current mark are
+omitted rather than returned with zero P&L. Inspect `coverage` on every response
+before presenting the ranking.
+
+Market and event catalogs use opaque cursor pagination. Reward-market list
+rows include nullable title, slug, image, event, category, and tag fields.
+
+Named perps helpers accept the returned opaque cursor:
+
+```python
+from polynode import PolyNodeV3
+
+with PolyNodeV3(api_key="pn_live_...") as v3:
+    first = v3.perps_trades(
+        "BTC-USD",
+        after=1_787_875_200,
+        before=1_787_961_600,
+        limit=100,
+    )
+    if first.get("next_cursor"):
+        second = v3.perps_trades(
+            "BTC-USD",
+            after=1_787_875_200,
+            before=1_787_961_600,
+            limit=100,
+            cursor=first["next_cursor"],
+        )
+
+    events = v3.perps_events(address=address, limit=100)
+    liquidations = v3.perps_liquidations(min_notional=10_000)
+    flows = v3.perps_wallet_flows(address, limit=100)
+```
+
+Reuse the same route and filters on every cursor page. Wallet-flow totals and
+counts remain fixed during one traversal. Cumulative volume delta remains a
+bounded single-page series and has no cursor helper. Async clients expose the
+same methods with `await`.
+
 The SDK encodes path parameters for you. Read requests that are safe to repeat retry transient failures and honor `Retry-After`; requests that change data are never retried automatically. JSON decimals decode as `Decimal`, and `ApiError` exposes the status, request ID, retry details, and a request URL with credentials removed.
 
 Current presets include `dome`, `fills`, `combos`, `redemptions`, and `deposits`. Current filters include `since()`, `combo_condition_ids()`, `leg_position_ids()`, `event_ids()`, `module_ids()`, `action()`, and `direction()`.
@@ -265,6 +333,43 @@ For the V2 order flow, required approvals, and common failure modes, see [docs.p
 
 V2 fees are determined at match time and are not signed into an order, so V2 payloads omit `feeRateBps`, `nonce`, and `taker`. Explicit legacy V1 mode still signs `feeRateBps`; for that path the SDK fetches `/fee-rate` and fails closed if fee, tick-size, or neg-risk metadata is unavailable or malformed.
 
+#### Polymarket Protocol V2 markets
+
+> **Two different "V2"s.** Polymarket Protocol V2 (October 2026) is Polymarket's new position system: positions live in a new ledger (PositionManager), every market type trades on one new exchange (ExchangeV3, order signing domain version `"3"`), and split, merge and redeem go through a Router. It is **not** the April 2026 upgrade (CTF Exchange V2 with pUSD collateral) that `ExchangeVersion.V2` and the rest of this README call "V2". Current markets keep using the April exchanges.
+
+**When.** Polymarket's test markets for Protocol V2 trade from 2026-10-05 to 2026-10-30. New markets move to Protocol V2 from around 2026-11-02 (tentative, per Polymarket). Existing markets stay where they are.
+
+**What you need to do.**
+
+- Streaming and REST only: nothing. Same methods, same response shapes. Rows and events for Protocol V2 markets carry a few optional fields: `protocol_version: "v2"`, `module` (`"binary"` or `"neg_risk"`), `exchange_version: "v3"` on fills, and `payouts_ppm` / `derived` on oracle events. A row without them is a current market.
+- Trading: upgrade to `polynode` 0.15.0 before 2026-11-02 and place orders exactly as before. Older versions keep working on current markets, but Polymarket rejects their orders on Protocol V2 markets (no funds move).
+- Storing ids yourself: keep outcome ids as strings (up to 78 digits). Condition ids are returned in the 66-character form; the 64-character form is accepted as input.
+
+The first order on a Protocol V2 market grants the two approvals it needs (pUSD and PositionManager, both for ExchangeV3): one gasless batch for Safe and deposit wallets, or two transactions with a little POL gas for an EOA. To do it ahead of time, or for browser-signed user-owned orders, call `ensure_ready` once with `protocol_v2=True`. Plain `ensure_ready()` behaves exactly as before.
+
+```python
+from polynode.trading import MergeParams, RedeemParams, SplitParams
+
+await trader.ensure_ready("0xYourPrivateKey...", protocol_v2=True)  # optional
+version = await trader.get_market_protocol(token_id)  # "v1" (current) or "v2"
+
+# Same call for every market; the SDK picks the exchange and signing domain.
+await trader.order(OrderParams(token_id=token_id, side="BUY", price=0.5, size=10))
+
+# Position operations (user-owned execution) route through the Router on V2 markets.
+await trader.execute_split(SplitParams(condition_id=condition_id, amount=10))
+await trader.execute_merge(MergeParams(condition_id=condition_id, amount=10))
+await trader.execute_redeem(RedeemParams(condition_id=condition_id, outcome_index=0))  # 0 = YES, 1 = NO
+payout = await trader.preview_payout(position_id, 10)  # None until resolved
+
+status = await trader.check_approvals(protocol_v2=True)
+print(status.protocol_v2_ready, status.position_ops_v2_ready, status.auto_redeem_enabled)
+```
+
+The SDK learns a market's protocol from Polymarket's market data and caches it for 24 hours in a new local table (existing tables are unchanged). It never guesses from the shape of an id: if the protocol cannot be learned, the order is refused with a retryable `MarketProtocolError` instead of being signed for the wrong exchange. Pass `protocol_version="v2"` (or call `trader.hint_market_protocol(...)`) to skip the lookup; a value that contradicts what the SDK already knows is refused. Short-form streams pick `positionIds` for Protocol V2 markets and expose `market.protocol_version`, so orders on discovered markets skip the lookup.
+
+Results of Protocol V2 markets are shares of 1,000,000 (`[1000000, 0]` = YES won, `[500000, 500000]` = 50/50); `payouts` carries the same result in smallest whole numbers, like current markets. `RedemptionWatcher` handles both. Automatic redemption by Polymarket's AutoRedeemer is opt-in only (`enable_auto_redeem()` / `disable_auto_redeem()`); proceeds always return to your wallet. Converting neg-risk positions is not supported for Protocol V2 markets yet.
+
 #### Optional user-owned execution
 
 Set `execution_mode=ExecutionMode.USER_OWNED` when the signing wallet should trade with zero builder attribution and use its own gasless authorization. Builder mode remains the default and existing integrations are unchanged.
@@ -502,29 +607,82 @@ const result = await fetch("/api/orders/submit", {
 }).then((response) => response.json());
 ```
 
-On the backend, atomically take the prepared object from session state, then validate and submit it:
+On the backend, atomically take the prepared object from session state, durably record the deterministic order identity, then validate and submit it:
 
 ```python
-async def submit_order(trader, browser_result, prepared_orders):
+async def submit_order(trader, browser_result, prepared_orders, attempts):
     # `take_once` must delete atomically so two workers cannot submit the same request.
     prepared = await prepared_orders.take_once(browser_result.request_id)
     if prepared is None:
         raise ValueError("Unknown or already-used signing request")
 
-    result = await trader.submit_prepared_user_owned_order(
-        prepared,
+    order_hash = prepared.order_hash
+    # This durable, idempotent write must commit before submission starts.
+    await attempts.create_once(
+        order_hash=order_hash,
         request_id=browser_result.request_id,
-        address=browser_result.address,
-        signature=browser_result.signature,
+        wallet=prepared.signing_request.address,
+        token_id=prepared.signing_request.order["tokenId"],
+        side=prepared.signing_request.order["side"],
+        status="submitting",
     )
-    return {
-        "success": result.success,
-        "orderId": result.order_id,
-        "error": result.error,
-    }
+
+    try:
+        result = await trader.submit_prepared_user_owned_order(
+            prepared,
+            request_id=browser_result.request_id,
+            address=browser_result.address,
+            signature=browser_result.signature,
+        )
+    except BaseException:
+        # Once consumed, a local/network exception has an ambiguous outcome.
+        status = (
+            "outcome_unknown"
+            if prepared.consumed
+            else "rejected_before_submission"
+        )
+        await attempts.set_status(order_hash, status)
+        raise
+    else:
+        if result.order_id and result.order_id.lower() != order_hash.lower():
+            await attempts.set_status(order_hash, "identity_mismatch")
+            raise RuntimeError("CLOB returned an unexpected order ID")
+        await attempts.record_response(order_hash, result)
+        return {
+            "success": result.success,
+            "orderId": result.order_id or order_hash,
+            "error": result.error,
+        }
 ```
 
-`prepare_user_owned_order()` supports V2 user-owned execution only, expires after five minutes by default, forces zero builder attribution, rejects positive fee authentication, and performs no submission. GTC, FOK, and FAK orders must omit expiration (zero is accepted and canonicalized to no expiration); GTD requires a fresh Unix-seconds expiration with the 60-second safety buffer, and the signing request is clamped to that window. `submit_prepared_user_owned_order()` verifies the request ID, expiry, connected wallet, stored wallet/funder identity, exact typed data, and recovered signer before consuming the request. A consumed request cannot be replayed. If submission has an ambiguous network result, reconcile its status instead of preparing an automatic duplicate.
+`prepared.order_hash` is the lowercase `0x`-prefixed EIP-712 digest of the canonical standard exchange `Order`. For EOA and Safe orders it also matches the browser-signing digest. POLY_1271 browsers sign an outer `TypedDataSign` wrapper, whose digest is intentionally different; `order_hash` always identifies the inner order that the CLOB and fills report. The property is computed on demand, is unchanged by trusted-state export/import, and is not added to the serialized schema.
+
+`prepare_user_owned_order()` supports V2 user-owned execution only, expires after five minutes by default, forces zero builder attribution, rejects positive fee authentication, and performs no submission. GTC, FOK, and FAK orders must omit expiration (zero is accepted and canonicalized to no expiration); GTD requires a fresh Unix-seconds expiration with the 60-second safety buffer, and the signing request is clamped to that window. `submit_prepared_user_owned_order()` verifies the request ID, expiry, connected wallet, stored wallet/funder identity, exact typed data, and recovered signer before consuming the request. A consumed request cannot be replayed.
+
+Treat any exception after `prepared.consumed` becomes true—including an HTTP timeout, disconnect, cancellation, or local failure around the network call—as `outcome_unknown`. Never submit that hash again and never automatically prepare a replacement. Reconcile by exact hash against both `await trader.get_open_orders(asset_id=token_id)` (`OpenOrder.id`) and your durable authenticated V2 fill source (`fill.order_hash`):
+
+```python
+async def reconcile_unknown(trader, attempt, fills):
+    open_orders = await trader.get_open_orders(asset_id=attempt.token_id)
+    open_order = next(
+        (order for order in open_orders if order.id.lower() == attempt.order_hash.lower()),
+        None,
+    )
+    matching_fills = await fills.by_order_hash(attempt.order_hash)
+    return {"openOrder": open_order, "fills": matching_fills}
+```
+
+An open order may already be partially filled (`size_matched` is nonzero), while a fully filled or canceled order will not remain open. Group all partial fills for the exact hash. Finding neither an open order nor a fill is not proof that submission failed: keep the attempt unknown and retry reconciliation with bounded backoff. The application-owned attempt store and fill source must be durable, wallet-scoped, and idempotent by `order_hash`; do not infer identity from token, side, amounts, timestamps, balances, or request ID.
+
+If a request-scoped trader was populated from a browser bundle or decrypted vault record, clear its credentials even when validation, signing, submission, or reconciliation fails:
+
+```python
+trader = await trader_from_browser_bundle(request_json)
+try:
+    result = await submit_order(trader, browser_result, prepared_orders, attempts)
+finally:
+    trader.close()
+```
 
 For a single-process application, a backend-only in-memory dictionary is sufficient. For multiple workers, serialize only with the SDK's trusted server-state methods and use a server-side store that can atomically take/delete by `requestId`:
 

{polynode-0.14.0 → polynode-0.15.0}/core-contract-v1.json

@@ -237,7 +237,7 @@
         "never_drop_silently": true
       }
     },
-    "operation_count": 120,
+    "operation_count": 129,
     "operations": [
       {
         "method": "POST",
@@ -371,12 +371,48 @@
         "domain": "combos",
         "retry": "safe_read"
       },
+      {
+        "method": "GET",
+        "path": "/v3/combos/activity/daily",
+        "domain": "combos",
+        "retry": "safe_read"
+      },
+      {
+        "method": "GET",
+        "path": "/v3/combos/leaderboard",
+        "domain": "combos",
+        "retry": "safe_read"
+      },
       {
         "method": "GET",
         "path": "/v3/combos/redemptions",
         "domain": "combos",
         "retry": "safe_read"
       },
+      {
+        "method": "GET",
+        "path": "/v3/markets",
+        "domain": "markets",
+        "retry": "safe_read"
+      },
+      {
+        "method": "GET",
+        "path": "/v3/markets/stats",
+        "domain": "markets",
+        "retry": "safe_read"
+      },
+      {
+        "method": "GET",
+        "path": "/v3/events",
+        "domain": "events",
+        "retry": "safe_read"
+      },
+      {
+        "method": "GET",
+        "path": "/v3/events/stats",
+        "domain": "events",
+        "retry": "safe_read"
+      },
       {
         "method": "GET",
         "path": "/v3/markets/search",
@@ -485,6 +521,12 @@
         "domain": "global",
         "retry": "safe_read"
       },
+      {
+        "method": "GET",
+        "path": "/v3/leaderboard/scopes",
+        "domain": "global",
+        "retry": "safe_read"
+      },
       {
         "method": "GET",
         "path": "/v3/builders",
@@ -497,6 +539,12 @@
         "domain": "builders",
         "retry": "safe_read"
       },
+      {
+        "method": "GET",
+        "path": "/v3/builders/{code}/leaderboard",
+        "domain": "builders",
+        "retry": "safe_read"
+      },
       {
         "method": "GET",
         "path": "/v3/builders/{code}/trades",
@@ -887,6 +935,12 @@
         "domain": "perps",
         "retry": "safe_read"
       },
+      {
+        "method": "GET",
+        "path": "/v3/perps/activity/daily",
+        "domain": "perps",
+        "retry": "safe_read"
+      },
       {
         "method": "GET",
         "path": "/v3/perps/funding-pnl/{instrument}",