release: 2.50.6 — delete /sql page + contradiction sweep (HIGH-severity SDK/docs mismatches)

Author: realfishsam

changelog.md

@@ -2,6 +2,26 @@
 
 All notable changes to this project will be documented in this file.
 
+## [2.50.6] - 2026-06-18
+
+### Docs
+
+- **Deleted `docs/sql.mdx`.** Removed from Get Started in `docs/docs.json` and from the API Reference Enterprise group. The `POST /v0/sql` endpoint reference page stays. One inbound link in `docs/concepts/catalog-uuid-vs-venue-id.mdx:56` retargeted from `[SQL endpoint](/sql)` to a plain `POST /v0/sql` reference.
+- **Contradiction sweep — round 1.** Three audit agents (SDK-truth-vs-docs, inter-page contradictions, stale-feature-status) found 60+ candidate findings; fixed every HIGH-severity item that didn't require a product call. Skipped items flagged separately at the end of this note.
+- **`docs/introduction.mdx`**: "11 venue integrations" → "15+ venue integrations" — `core/src/server/exchange-factory.ts` registers 16 (excluding test/demo/mock the customer count is ~14, "15+" is the honest marketing number).
+- **`docs/concepts/prediction-markets-101.mdx`**: USDC entry was misleading — said "Polymarket-native USDC". Actual settlement asset is **USDC.e** (bridged) at `0x2791Bca1f2de4661ED88A30C99A7a9449Aa84174`, which is what Polymarket's CTF exchange uses. The migrate-to-hosted-trading guide already had this right; the 101 was contradicting it. Same edit confirms native Polygon USDC and bridged USDC on other chains are not interchangeable with USDC.e.
+- **`docs/concepts/hosted-trading.mdx`**: `client.escrow.deposit()` / `.withdraw()` — neither method exists. The Escrow class exposes `approve_tx` / `deposit_tx` / `withdraw_tx` / `withdrawals` (`sdks/python/pmxt/escrow.py:114-184`). Replaced with the actual call shape including the `withdraw_tx("request" | "claim" | "cancel", ...)` argument signature.
+- **`docs/guides/escrow-lifecycle.mdx`**: `fetch_balance` returns `List[Balance]`, not a single `Balance` (`sdks/python/pmxt/client.py:1643`). The "Confirm the deposit" example unpacked `balance.free / .used / .total` directly, which would `AttributeError` on a list. Fixed to `balances = client.fetch_balance(); usdc = balances[0]; ...`. The `trading-quickstart` already used the list form correctly; this brought escrow-lifecycle in line.
+- **`docs/guides/signing.mdx`**: The "Advanced: bring your own signer" example used three attributes that don't exist on the SDK's `BuiltOrder` dataclass — `built.typed_data`, `built.built_order_id`, and a kwargs-style `submit_order(built_order_id=, signature=)`. The actual Python signature is `submit_order(built: BuiltOrder)` (`sdks/python/pmxt/client.py:3183`); typed-data lives at `built.raw["typed_data"]`; the signature attaches as `built.signed_order` before submit. Rewrote both Python and TypeScript examples to match. The TS `submitOrder({ builtOrderId, signature })` shape was also wrong — TS `submitOrder` accepts the `BuiltOrder` object too.
+- **`docs/guides/hosted-errors.mdx`** (two fixes in one page):
+  - The "BuiltOrderExpired retry" example had the same wrong `built.typed_data` / `built.built_order_id` / kwargs `submit_order` shape as the signing guide. Rewrote both Python and TS to use the real attribute paths and the object-shape `submit_order(built)` / `submitOrder(built)` call.
+  - The stale "`fetch_markets` returns venue-native IDs, but `create_order` needs catalog UUIDs" warning was the same lie that 2.50.3 and 2.50.5 fixed in `hosted-trading.mdx` and `prediction-markets-101.mdx`. Hosted-errors.mdx was the third place it lived. Rewrote the `OutcomeNotFound` Quick check to describe the real failure modes — outcome resolved against a different `exchange_name`, or removed from the catalog — and dropped the venue-native-ID accusation entirely.
+  - The `NoLiquidity` recovery example told callers to fall back to a hosted limit order. Hosted limit orders return 501 (`docs/trading-quickstart.mdx:165`) — the advice was internally inconsistent and would crash any caller who followed it. Rewrote the recovery to "wait, switch outcome, or run self-hosted for resting limits."
+- **Skipped — needs your call before I touch them:**
+  - **Limitless hosted writes.** The SDK's hosted routing tables (`sdks/typescript/pmxt/hosted-routing.ts:24-28`, `sdks/python/pmxt/_hosted_routing.py:19`) include `limitless` in `HOSTED_TRADING_VENUES`, and `client.py:829-838` routes the schemas. But the SDK's own `NotSupported` error string at `hosted-routing.ts:75` still says "only supported for Polymarket and Opinion" — and every doc page asserts the same. Either Limitless hosted writes are prod-ready (six doc pages need updating and the error string is wrong) or they're partially wired (no doc change, error string is right). I don't have enough signal to decide.
+  - **Operator multisig.** `docs/concepts/hosted-trading.mdx:89` says "A multisig replacement is planned but not yet deployed" while line 93 says the operator address is `immutable`. Both can be true (replacement = new contract deployment + migration), but the wording reads like an in-place rotation. Wanted your call on the phrasing.
+  - **`trade.pmxt.dev` vs `api.pmxt.dev` terminology drift.** Introduction splits hosted into two hostnames (reads on `api.pmxt.dev`, writes on `trade.pmxt.dev`); `authentication.mdx` and `rate-limits.mdx` only mention `api.pmxt.dev`. A builder reading auth in isolation won't know `trade.pmxt.dev` is a thing. Not a wrong claim, just incomplete coverage on auth/rate-limits.
+
 ## [2.50.5] - 2026-06-18
 
 ### Docs

docs/concepts/catalog-uuid-vs-venue-id.mdx

@@ -53,7 +53,7 @@ clusters = router.fetch_matched_market_clusters(
 catalog_uuid = clusters[0].market_id
 ```
 
-For batch workflows, the [SQL endpoint](/sql) gives you direct access to `prediction_markets.markets` and `prediction_markets.outcomes` with the canonical UUID alongside the venue-native fields (`venue_market_id`, `venue_outcome_id` / `token_id`).
+For batch workflows, `POST /v0/sql` gives you direct access to `prediction_markets.markets` and `prediction_markets.outcomes` with the canonical UUID alongside the venue-native fields (`venue_market_id`, `venue_outcome_id` / `token_id`).
 
 ## Examples (the two ids for one market)
 

docs/concepts/hosted-trading.mdx

@@ -69,7 +69,7 @@ The SDK accepts either form. Outcomes returned by `pmxt.Polymarket(...).fetch_ma
 - **Polymarket** is on Polygon. Escrow-held USDC is spent directly via Polymarket's CTF exchange — same-chain settlement.
 - **Opinion** is on BSC (chainId 56). Escrow-held USDC funds a cross-chain settlement leg into a BSC-side `VenueEscrow` that holds Opinion [outcome](/concepts/prediction-markets-101#event-market-outcome) tokens. The user never deposits to or signs on BSC — PMXT operates the cross-chain hop, still gated by the user's signature on the Polygon side.
 
-All EIP-712 order signatures use the Polygon `PreFundedEscrow` domain regardless of venue. The user's wallet retains beneficial ownership at all times. Funds enter via `client.escrow.deposit()`, exit via `client.escrow.withdraw()`. Both are unsigned-tx builders — your wallet signs and submits them. See [Escrow Lifecycle](/guides/escrow-lifecycle).
+All EIP-712 order signatures use the Polygon `PreFundedEscrow` domain regardless of venue. The user's wallet retains beneficial ownership at all times. Funds enter via `client.escrow.deposit_tx(amount)`, exit via `client.escrow.withdraw_tx("request" | "claim" | "cancel", ...)`. Both build unsigned txs — your wallet signs and submits them. See [Escrow Lifecycle](/guides/escrow-lifecycle).
 
 ### Deployed contracts
 

docs/concepts/prediction-markets-101.mdx

@@ -39,7 +39,7 @@ A specific EVM-compatible chain (chainId 137). PMXT's `PreFundedEscrow` contract
 
 ### USDC
 
-A US-dollar-pegged stablecoin (1 USDC ≈ $1) issued on many chains. PMXT uses the **Polygon-native** USDC for hosted trading. Bridged versions on other chains are not interchangeable.
+A US-dollar-pegged stablecoin (1 USDC ≈ $1) issued on many chains. PMXT hosted trading settles in **USDC.e on Polygon** (`0x2791Bca1f2de4661ED88A30C99A7a9449Aa84174`) — the bridged token Polymarket's CTF exchange uses. Native Polygon USDC and bridged USDC on other chains are not interchangeable.
 
 ### EIP-712
 

docs/docs.json

@@ -60,8 +60,7 @@
               "authentication",
               "mcp",
               "security",
-              "rate-limits",
-              "sql"
+              "rate-limits"
             ]
           },
           {
@@ -225,7 +224,6 @@
             "group": "Enterprise",
             "openapi": "api-reference/openapi-hosted.json",
             "pages": [
-              "sql",
               "POST /v0/sql"
             ]
           }

docs/guides/escrow-lifecycle.mdx

@@ -113,13 +113,15 @@ After the deposit transaction confirms on-chain, the balance shows up in escrow.
 
 <CodeGroup>
 ```python Python
-balance = client.fetch_balance()
-print(f"Free: {balance.free}, Used: {balance.used}, Total: {balance.total}")
+balances = client.fetch_balance()
+usdc = balances[0]
+print(f"Free: {usdc.free}, Used: {usdc.used}, Total: {usdc.total}")
 ```
 
 ```typescript TypeScript
-const balance = await client.fetchBalance();
-console.log(`Free: ${balance.free}, Used: ${balance.used}, Total: ${balance.total}`);
+const balances = await client.fetchBalance();
+const usdc = balances[0];
+console.log(`Free: ${usdc.free}, Used: ${usdc.used}, Total: ${usdc.total}`);
 ```
 </CodeGroup>
 

docs/guides/hosted-errors.mdx

@@ -154,12 +154,9 @@ from pmxt._hosted_errors import BuiltOrderExpired
 def submit_with_retry(client, *, market_id, outcome_id, **kwargs):
     for attempt in range(2):
         built = client.build_order(market_id=market_id, outcome_id=outcome_id, **kwargs)
-        sig = signer.sign_typed_data(built.typed_data)
+        built.signed_order = signer.sign_typed_data(built.raw["typed_data"])
         try:
-            return client.submit_order(
-                built_order_id=built.built_order_id,
-                signature=sig,
-            )
+            return client.submit_order(built)
         except BuiltOrderExpired:
             if attempt == 1:
                 raise
@@ -172,16 +169,14 @@ import { BuiltOrderExpired } from "pmxtjs";
 async function submitWithRetry(client, params) {
   for (let attempt = 0; attempt < 2; attempt++) {
     const built = await client.buildOrder(params);
-    const sig = await signer.signTypedData(
-      built.typedData.domain,
-      built.typedData.types,
-      built.typedData.message,
+    const typedData = built.raw.typed_data;
+    built.signedOrder = await signer.signTypedData(
+      typedData.domain,
+      typedData.types,
+      typedData.message,
     );
     try {
-      return await client.submitOrder({
-        builtOrderId: built.builtOrderId,
-        signature: sig,
-      });
+      return await client.submitOrder(built);
     } catch (e) {
       if (e instanceof BuiltOrderExpired && attempt === 0) continue;
       throw e;
@@ -199,7 +194,7 @@ async function submitWithRetry(client, params) {
 
 **Parent classes:** `InvalidOrder`, `HostedTradingError`.
 
-**Recovery:** wait for liquidity, post a limit order instead of a market order, or pick a different outcome.
+**Recovery:** wait for liquidity, pick a different outcome, or run [self-hosted](/guides/self-hosted) for resting limit orders (hosted limit orders are not yet available).
 
 <CodeGroup>
 ```python Python
@@ -208,8 +203,8 @@ from pmxt._hosted_errors import NoLiquidity
 try:
     client.create_order(order_type="market", ...)
 except NoLiquidity:
-    # Fall back to a limit order at a price you'd accept
-    client.create_order(order_type="limit", price=0.50, ...)
+    # Wait, retry against a different outcome, or post limits via self-hosted.
+    pass
 ```
 
 ```typescript TypeScript
@@ -219,7 +214,7 @@ try {
   await client.createOrder({ orderType: "market", ... });
 } catch (e) {
   if (e instanceof NoLiquidity) {
-    await client.createOrder({ orderType: "limit", price: 0.5, ... });
+    // Wait, retry against a different outcome, or post limits via self-hosted.
   } else {
     throw e;
   }
@@ -234,7 +229,7 @@ try {
 </Warning>
 
 <Warning>
-**`fetch_markets` returns venue-native IDs**, but `create_order` needs catalog UUIDs. If you see `OutcomeNotFound` despite having a valid-looking ID, you are almost certainly passing a venue-native ID to a hosted endpoint. See [Catalog UUID vs venue ID](/concepts/catalog-uuid-vs-venue-id).
+If you see `OutcomeNotFound` despite having a valid-looking ID, the SDK could not resolve it on either the catalog UUID or `(venue, venue_outcome_id)` path. Most commonly: the outcome was resolved against a different venue than the client's `exchange_name`, or the outcome has since been removed from the catalog. See [Catalog UUID vs venue ID](/concepts/catalog-uuid-vs-venue-id).
 </Warning>
 
 ## Catching everything hosted

docs/guides/signing.mdx

@@ -92,16 +92,14 @@ built = client.build_order(
     slippage_pct=30.0,
 )
 
+typed_data = built.raw["typed_data"]
 signature = my_custom_signer.sign_typed_data(
-    domain=built.typed_data["domain"],
-    types=built.typed_data["types"],
-    message=built.typed_data["message"],
-)
-
-order = client.submit_order(
-    built_order_id=built.built_order_id,
-    signature=signature,
+    domain=typed_data["domain"],
+    types=typed_data["types"],
+    message=typed_data["message"],
 )
+built.signed_order = signature  # attach signature for submit
+order = client.submit_order(built)
 ```
 
 ```typescript TypeScript
@@ -121,16 +119,14 @@ const built = await client.buildOrder({
   slippagePct: 30,
 });
 
+const typedData = built.raw.typed_data;
 const signature = await myCustomSigner.signTypedData(
-  built.typedData.domain,
-  built.typedData.types,
-  built.typedData.message,
+  typedData.domain,
+  typedData.types,
+  typedData.message,
 );
-
-const order = await client.submitOrder({
-  builtOrderId: built.builtOrderId,
-  signature,
-});
+built.signedOrder = signature;
+const order = await client.submitOrder(built);
 ```
 </CodeGroup>
 

docs/introduction.mdx

@@ -111,7 +111,7 @@ Polymarket or Kalshi.
 
 Without PMXT, getting cross-venue prediction market data means:
 
-- **11 venue integrations** — each with its own auth, pagination, field
+- **15+ venue integrations** — each with its own auth, pagination, field
   names, and rate limits. Polymarket uses CLOB token IDs. Kalshi uses
   tickers. Smarkets uses contract IDs. You normalize all of it.
 - **A data pipeline** — to ingest, deduplicate, and keep fresh as markets