release: 2.50.10 — fix 8 HIGH SDK/docs code-correctness bugs (incl. 2.50.6 regressions)

Author: realfishsam

changelog.md

@@ -2,6 +2,26 @@
 
 All notable changes to this project will be documented in this file.
 
+## [2.50.10] - 2026-06-18
+
+### Fixed
+
+A code-correctness audit against the SDK source found 8 HIGH-severity bugs in published docs — code blocks that would TypeError, AttributeError, or silently no-op. Two of them I introduced myself in 2.50.6 by rewriting against the wrong SDK truth. All fixed in parallel with three agents, each verifying against the SDK source line they cite.
+
+- **`docs/authentication.mdx:107` + `docs/guides/self-hosted.mdx:93`**: Python `create_order(type="limit", ...)` would raise `TypeError: unexpected keyword argument 'type'`. The parameter is `order_type=`, not `type=` (`sdks/python/pmxt/client.py:2892`). Fixed both call sites.
+- **`docs/guides/escrow-lifecycle.mdx:118,124`**: Self-introduced regression from 2.50.6. After fixing `fetch_balance` to return a list, I documented `usdc.free / .used / .total` — those fields don't exist. The Balance dataclass exposes `available` / `locked` / `total` (`sdks/python/pmxt/models.py:596-603`; `sdks/typescript/pmxt/models.ts:387-393`). `.free` and `.used` would AttributeError on first access. Updated both Python and TypeScript examples to use the real field names.
+- **`docs/router/prices.mdx:206`**: `poly.fetch_order_book(market_id=clusters[0].markets[0].market_id)` — `fetch_order_book` takes `outcome_id`, not `market_id` (`sdks/python/pmxt/client.py:1441`). The `_compat_id` resolver at line 1446 would catch the missing required arg and raise `TypeError: Missing required argument: 'outcome_id'`. Updated to pull an outcome ID from `clusters[0].markets[0].outcomes[0].outcome_id`.
+- **`docs/concepts/catalog-uuid-vs-venue-id.mdx:48-56`**: The "reverse-resolve a venue ID to a catalog UUID" example showed `router.fetch_matched_market_clusters(venue="polymarket", venue_market_id="0x...")` then read `clusters[0].market_id`. None of those exist: the method signature (`sdks/python/pmxt/router.py:328-350`) accepts only `market_id`, `slug`, `url`, `query`, `venues`/`exclude_venues`, and `MatchedMarketCluster` (`models.py:939-964`) has `cluster_id` + `markets[]` with no top-level `market_id`. There is no clean SDK reverse-resolution API for the venue→catalog mapping. Replaced the broken example with a `POST /v0/sql` query against `prediction_markets.markets` filtered by `venue` + `venue_market_id` — which is what the next paragraph of the page already pointed at.
+- **`docs/guides/signing.mdx` — `## Advanced: bring your own signer`**: The 2.50.6 rewrite of this section shipped a Python pattern that doesn't work and a TypeScript pattern that throws on the first call. Two distinct bugs:
+  - **Python:** the pattern was `built = client.build_order(...); built.signed_order = my_signer.sign_typed_data(...); client.submit_order(built)`. In hosted mode, `submit_order` ignores `built.signed_order` and re-signs internally with `self.signer` (`client.py:875-895` in `_call_hosted_signer`; `client.py:911` reads `signer or self.signer`; `client.py:3203` `_hosted_submit_body(..., signer=None)` falls back). The custom signature was silently discarded and the user's `private_key` was used instead. Anyone following the doc would think their custom signer worked when in fact only the `private_key` path was active.
+  - **TypeScript:** worse — `submitOrder` is explicitly disabled in hosted mode and throws `PmxtError("submitOrder is not available in hosted mode. Use createOrder instead.")` (`client.ts:1134-1137`). The TS recipe could never run.
+  - **Correct pattern:** constructor injection. Python `pmxt.Polymarket(..., signer=my_signer)` (`client.py:336` — constructor accepts `signer: Optional[Any] = None`). TS `new Polymarket({ ..., signer: mySigner })` (`client.ts:288,335`).
+  - **Signer protocol:** the Python signer must implement `sign_typed_data(typed_data: dict) -> hex` — taking the WHOLE typed-data dict (`client.py:875-895` iterates `("sign_typed_data", "sign")` and passes the full dict). The 2.50.6 docs incorrectly showed a split `domain=/types=/message=` signature; that was wrong. The TS Signer protocol (`signers.ts:33-35`) is `{ address: string; signTypedData(typedData: TypedData): Promise<string> }`. Rewrote both examples to constructor-inject and call `create_order` / `createOrder`. Removed the build/sign/submit dance entirely — it's not a hosted-mode pattern.
+- **`docs/guides/signing.mdx` — TS field names**: TS `buildOrder`/`createOrder` examples used `orderType:` and `slippagePct:`. The `CreateOrderParams` interface (`models.ts:533-545`) uses `type:` (not `orderType`). Slippage is even more unusual — TS forwards it through the params extension dict as the snake_case key `slippage_pct:` (`client.ts:2429-2430`). The TS field name really is snake_case here; that's not a typo. Updated all TS examples.
+- **`docs/guides/hosted-errors.mdx` — TS `NoLiquidity` recovery (`line 214`)**: same `orderType:` → `type:` fix.
+- **`docs/guides/hosted-errors.mdx` — `BuiltOrderExpired` retry pattern (`lines 150-187`)**: same build/sign/submit pattern problem as `signing.mdx`. The retry example showed `built.signed_order = ...; submit_order(built)`. Same issue: Python hosted ignores the assignment and re-signs; TS hosted throws. Rewrote both examples to call `create_order` / `createOrder` directly inside the try/except — the SDK's convenience wrapper handles build → sign → submit atomically, so a `BuiltOrderExpired` retry is just calling `create_order` again.
+- **`docs/api-reference/fetch-ohlcv.mdx:7`**: Broken internal link `/dashboard` (an in-docs path that doesn't exist) replaced with the external `https://pmxt.dev/dashboard`. The only broken internal link in the docs tree per the link-integrity sweep.
+
 ## [2.50.9] - 2026-06-18
 
 ### Docs

docs/api-reference/fetch-ohlcv.mdx

@@ -4,7 +4,7 @@ openapi: GET /api/{exchange}/fetchOHLCV
 ---
 
 <Info>
-**More data with an API key** — Without an API key, OHLCV is limited to Polymarket's native API: short history windows, no volume, and venue-specific rate limits. With a PMXT API key you get volume, 1+ years of history, and normalized candles across venues. Kalshi, Limitless, and more are coming soon. [Get your API key](/dashboard).
+**More data with an API key** — Without an API key, OHLCV is limited to Polymarket's native API: short history windows, no volume, and venue-specific rate limits. With a PMXT API key you get volume, 1+ years of history, and normalized candles across venues. Kalshi, Limitless, and more are coming soon. [Get your API key](https://pmxt.dev/dashboard).
 </Info>
 
 ## Use cases

docs/authentication.mdx

@@ -104,7 +104,7 @@ directly:
 order = poly.create_order(
     outcome=market.yes,
     side="buy",
-    type="limit",
+    order_type="limit",
     price=0.42,
     amount=100,
 )

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

@@ -45,15 +45,16 @@ In [self-hosted mode](/guides/self-hosted) — `POST /api/{exchange}/createOrder
 
 If you already have a venue-native id (e.g. a saved database of Polymarket `conditionId`s) and want the catalog UUID for cross-venue work:
 
-```python
-clusters = router.fetch_matched_market_clusters(
-    venue="polymarket",
-    venue_market_id="0xc704f74e2f9dfae70f770cb253ffadde10768eeab41233098bf5ac67995a94b5",
-)
-catalog_uuid = clusters[0].market_id
+The SDK does not expose a single-shot `venue_market_id` -> catalog UUID kwarg today. For batch or one-off reverse lookups, query the catalog directly via `POST /v0/sql`:
+
+```sql
+SELECT market_id
+FROM prediction_markets.markets
+WHERE venue = 'polymarket'
+  AND venue_market_id = '0xc704f74e2f9dfae70f770cb253ffadde10768eeab41233098bf5ac67995a94b5';
 ```
 
-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`).
+`prediction_markets.markets` and `prediction_markets.outcomes` carry the canonical UUID alongside the venue-native fields (`venue_market_id`, `venue_outcome_id` / `token_id`), so the same query shape covers outcomes too.
 
 ## Examples (the two ids for one market)
 

docs/guides/escrow-lifecycle.mdx

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

docs/guides/hosted-errors.mdx

@@ -151,12 +151,12 @@ Hardware-wallet signing is the most common cause — Ledger confirmations can ta
 ```python Python
 from pmxt._hosted_errors import BuiltOrderExpired
 
-def submit_with_retry(client, *, market_id, outcome_id, **kwargs):
+def submit_with_retry(client, **kwargs):
+    # In hosted mode, create_order handles build -> sign -> submit atomically.
+    # On BuiltOrderExpired the internal submit raced the 30s TTL; just call again.
     for attempt in range(2):
-        built = client.build_order(market_id=market_id, outcome_id=outcome_id, **kwargs)
-        built.signed_order = signer.sign_typed_data(built.raw["typed_data"])
         try:
-            return client.submit_order(built)
+            return client.create_order(**kwargs)
         except BuiltOrderExpired:
             if attempt == 1:
                 raise
@@ -165,23 +165,20 @@ def submit_with_retry(client, *, market_id, outcome_id, **kwargs):
 
 ```typescript TypeScript
 import { BuiltOrderExpired } from "pmxtjs";
+import type { CreateOrderParams, Order } from "pmxtjs";
 
-async function submitWithRetry(client, params) {
+async function submitWithRetry(client, params: CreateOrderParams): Promise<Order> {
+  // In hosted mode, createOrder handles build -> sign -> submit atomically.
+  // On BuiltOrderExpired the internal submit raced the 30s TTL; just call again.
   for (let attempt = 0; attempt < 2; attempt++) {
-    const built = await client.buildOrder(params);
-    const typedData = built.raw.typed_data;
-    built.signedOrder = await signer.signTypedData(
-      typedData.domain,
-      typedData.types,
-      typedData.message,
-    );
     try {
-      return await client.submitOrder(built);
+      return await client.createOrder(params);
     } catch (e) {
       if (e instanceof BuiltOrderExpired && attempt === 0) continue;
       throw e;
     }
   }
+  throw new Error("unreachable");
 }
 ```
 </CodeGroup>
@@ -211,7 +208,7 @@ except NoLiquidity:
 import { NoLiquidity } from "pmxtjs";
 
 try {
-  await client.createOrder({ orderType: "market", ... });
+  await client.createOrder({ type: "market", ... });
 } catch (e) {
   if (e instanceof NoLiquidity) {
     // Wait, retry against a different outcome, or post limits via self-hosted.

docs/guides/self-hosted.mdx

@@ -90,7 +90,7 @@ poly = pmxt.Polymarket(private_key="0xYourPrivateKey...")
 order = poly.create_order(
     outcome=market.yes,
     side="buy",
-    type="limit",
+    order_type="limit",
     price=0.42,
     amount=100,
 )

docs/guides/signing.mdx

@@ -43,10 +43,10 @@ const order = await client.createOrder({
   marketId: "2eeb03dc-404b-41d5-bc57-6aeb37927ae6",
   outcomeId: "a114f052-1fd1-4bcd-b9cf-de019db81b67",
   side: "buy",
-  orderType: "market",
+  type: "market",
   amount: 5,
   denom: "usdc",
-  slippagePct: 30,
+  slippage_pct: 30,
 });
 ```
 </CodeGroup>
@@ -72,17 +72,19 @@ Because reads don't require a signature, anyone with the `pmxt_api_key` can read
 
 ## Advanced: bring your own signer
 
-If your key lives in a hardware wallet, HSM, MPC service, or anything that isn't a raw hex private key, skip `private_key` and use the lower-level `build_order` / `submit_order` flow. Any object that implements `sign_typed_data(domain, types, message) -> hex` works.
+If your key lives in a hardware wallet, HSM, MPC service, or anything that isn't a raw hex private key, skip `private_key` and inject a custom signer at construction. The SDK uses it transparently for every hosted write — you keep calling `create_order` as usual.
+
+The signer protocol is one method: `sign_typed_data(typed_data: dict) -> hex` (Python) or `signTypedData(typedData): Promise<string>` plus a readonly `address` (TypeScript).
 
 <CodeGroup>
 ```python Python
 client = pmxt.Polymarket(
     pmxt_api_key="pmxt_live_...",
     wallet_address="0xYourWallet...",
-    # no private_key
+    signer=my_custom_signer,  # exposes sign_typed_data(typed_data) -> hex
 )
 
-built = client.build_order(
+order = client.create_order(
     market_id="2eeb03dc-...",
     outcome_id="a114f052-...",
     side="buy",
@@ -91,43 +93,25 @@ built = client.build_order(
     denom="usdc",
     slippage_pct=30.0,
 )
-
-typed_data = built.raw["typed_data"]
-signature = my_custom_signer.sign_typed_data(
-    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
 const client = new Polymarket({
   pmxtApiKey: "pmxt_live_...",
   walletAddress: "0xYourWallet...",
-  // no privateKey
+  signer: myCustomSigner,  // { address, signTypedData(typedData) -> Promise<hex> }
 });
 
-const built = await client.buildOrder({
+const order = await client.createOrder({
   marketId: "2eeb03dc-...",
   outcomeId: "a114f052-...",
   side: "buy",
-  orderType: "market",
+  type: "market",
   amount: 5,
   denom: "usdc",
-  slippagePct: 30,
+  slippage_pct: 30,
 });
-
-const typedData = built.raw.typed_data;
-const signature = await myCustomSigner.signTypedData(
-  typedData.domain,
-  typedData.types,
-  typedData.message,
-);
-built.signedOrder = signature;
-const order = await client.submitOrder(built);
 ```
 </CodeGroup>
 
-For Opinion, `built` carries two payloads (`typed_data` and `pull_typed_data`); sign both and pass `signature` + `pull_signature` to `submit_order`. The SDK's `EthAccountSigner` / `EthersSigner` are reference implementations of the signer protocol — ethers v6 supports Ledger out of the box; for MPC see Fireblocks / Privy / Turnkey docs.
+For Opinion's dual-signature flow, the same injected signer is invoked twice (once per payload) — no extra wiring. The SDK's `EthAccountSigner` (Python) / `EthersSigner` (TypeScript) are reference implementations; ethers v6 supports Ledger out of the box, and for MPC see Fireblocks / Privy / Turnkey docs.

docs/router/prices.mdx

@@ -203,7 +203,7 @@ poly   = pmxt.Polymarket(private_key="0x...")
 clusters = router.fetch_matched_market_clusters(relation="identity", limit=20)
 
 # 2. Inspect the order book on a specific venue
-book = poly.fetch_order_book(market_id=clusters[0].markets[0].market_id)
+book = poly.fetch_order_book(outcome_id=clusters[0].markets[0].outcomes[0].outcome_id)
 
 # 3. Place an order locally (never proxied through PMXT)
 # poly.create_order(...)