release: 2.50.11 — SDK hosted-mode routing for fetch_balance/positions/order + $1 min docs

Author: realfishsam

changelog.md

@@ -2,6 +2,39 @@
 
 All notable changes to this project will be documented in this file.
 
+## [2.50.11] - 2026-06-18
+
+End-to-end live verification of the 2.50.10 doc claims surfaced two real SDK routing bugs and one hosted-API response-shape bug. All three fixed in parallel and verified live against `trade.pmxt.dev` with the test wallet `0xcb856a79c3E6490e0cFD7934eB59326E593C0cD1`.
+
+### Fixed (Python SDK — `sdks/python/pmxt/client.py`)
+
+- **`fetch_balance` (line 1643), `fetch_positions` (line 1622), `fetch_order` (line 1512) now route through the hosted v0 endpoints in hosted mode.** Previously all three punted to the legacy sidecar (`POST /api/polymarket/fetchBalance` and equivalents), which calls Polymarket CLOB's `getBalanceAllowance` and an on-chain `balanceOf` on pUSD at `0xC011a7E12a19f7B1f670d46F03B03f3342E82DFB` — the WRONG token (pUSD instead of USDC.e) at the WRONG contract (CLOB collateral, not PreFundedEscrow). Any wallet that funded a hosted account via the dashboard's Deposit flow saw `available=0`, `total=0`, `chain=None`, `venue=None` from `fetch_balance` while their USDC.e was sitting safely in `PreFundedEscrow.balances(wallet)`. Same root cause for `fetch_positions` (returned `[]` for wallets with real positions) and for `fetch_order` (forwarded the PMXT-internal task_id straight to Polymarket's CLOB, which surfaced the misleading error `Invalid orderID [Polymarket]`).
+- All three now dispatch via `_hosted_request("fetch_balance" | "fetch_positions" | "fetch_order", ...)` in hosted mode, using existing mappers `balance_from_v0` / `position_from_v0` / `order_from_v0` from `_hosted_mappers.py`. Self-hosted branches preserved unchanged — they continue to use the sidecar, which is correct in self-hosted mode.
+
+### Fixed (TypeScript SDK — `sdks/typescript/pmxt/client.ts`)
+
+- **`fetchOrder` (line 1189), `fetchPositions` (line 1319), `fetchBalance` (line 1345)**: same bug, same fix. Hosted-mode branches added that dispatch via `_tradingRequest` with `HOSTED_METHOD_ROUTES.get("fetchOrder" | "fetchPositions" | "fetchBalance")` and the `orderFromV0` / `positionFromV0` / `balanceFromV0` mappers from `hosted-mappers.ts`.
+
+### Live verification
+
+Same three calls, before and after, against the same wallet on `trade.pmxt.dev`:
+
+| Method | Before | After | On-chain truth |
+| - | - | - | - |
+| `fetch_balance()` | `total=0, available=0, chain=None, venue=None` | `total=52.094842, available=52.094842` | `PreFundedEscrow.balances(0xcb856…) = 52.094842 USDC.e` (verified via direct contract call to `0x3ad326f78b1390b9a5dc5f00e7f62f8632de23e2`) |
+| `fetch_positions()` | `[]` | 25 real positions | Wallet has historical positions; SDK now sees them |
+| `fetch_order("364")` | `BadRequest: Invalid orderID [Polymarket]` (CLOB rejected an internal task_id it never assigned) | `HostedTradingError: invalid amount for a marketable BUY order ($0.77), min size: 1` (the real venue error surfaced through the hosted route) | `GET /v0/orders/364` returns `status="failed"` with the literal CLOB error string |
+
+### Docs
+
+- **`docs/trading-quickstart.mdx`** — The "What PMXT abstracts" Note in Step 5 was incomplete. Polymarket has TWO minimums that fire independently: the 5-share minimum (already documented) AND a $1 minimum on marketable BUY orders (previously undocumented). At $0.138/share, the 5-share rule says `0.69` is enough — but the $1 marketable-BUY rule rejects with `invalid amount for a marketable BUY order ($0.77), min size: 1`. The Note now describes both rules and works the example. Surfaced because the live test placed exactly this rejection.
+- **`docs/trading-quickstart.mdx` Step 6 ("Verify the fill")** — added a Note clarifying that the `id` returned by hosted `create_order` is a PMXT internal task_id (not a Polymarket order id), must be looked up via `client.fetch_order(id)` (which now actually works after the SDK fix above), and that fresh orders return `status="queued"` because venue submission is async. The "queued" wording aligns with the server-side change applied on the trading-api server (branch `fix/submit-order-queued-not-accepted` on `/root/pmxt-trading`, commit `1576a03` — not yet pushed to production).
+- **`docs/guides/hosted-errors.mdx`** — the `OrderSizeTooSmall` section was rewritten to split the 5-share rule from the $1 marketable-BUY rule, quote the literal CLOB error string `invalid amount for a marketable BUY order ($X), min size: 1`, and explicitly note this is the venue's check, not PMXT's.
+
+### Investigated but NOT bugs
+
+- **Initial misattribution to a degraded Polygon RPC.** A first-pass investigation pointed at `lb.drpc.live` and 172 "USDC balance call failed in multicall" warnings on the server, claiming a silent-zero on RPC failure. Martin pushed back, correctly: drpc is healthy. Independent verification (direct `eth_call` to `lb.drpc.live`) returns `52.094842 USDC.e` for the test wallet immediately. The 172 warnings are noise: `batch_user_escrow_balances` in `trading_api/core/multicall3.py` is reused across the Polygon HomeEscrow (which implements `balances(address)`) and the BSC + Base VenueEscrow contracts (which do NOT — every `balances()` call to them reverts with `execution reverted: 0x` by design). The caller intentionally discards those sub-call results (`escrow.py:73-74`) but the wrapper logs WARN on every call. Cosmetic log-level bug, separately tracked, not the cause of the SDK reading 0. The SDK bug was that it never asked the hosted v0 endpoint in the first place — it routed to the sidecar which queried the wrong contract.
+
 ## [2.50.10] - 2026-06-18
 
 ### Fixed

docs/guides/hosted-errors.mdx

@@ -59,9 +59,14 @@ try {
 
 ## OrderSizeTooSmall
 
-**When it fires:** the resolved share count is below the venue's minimum. Polymarket's minimum is **5 shares per order**. A $2 buy at $0.78/share is only 2.5 shares — rejected.
+**When it fires:** the resolved order is below one of Polymarket's two independent venue-side minimums on marketable BUY orders. Both rules are enforced by the venue itself (not PMXT), and the **higher of the two binds**:
 
-**Detail string:** `Order size 2.564 below the minimum 5 shares for venue polymarket`.
+- **5-share minimum.** A $2 buy at $0.78/share is only 2.5 shares — rejected.
+- **$1 notional minimum (marketable BUY).** A 5-share buy at $0.138/share is $0.69 — passes the 5-share rule but is rejected by the venue with the literal error `invalid amount for a marketable BUY order ($0.69), min size: 1`. The effective minimum at that price is ~8 shares (~$1.10).
+
+**Detail string (5-share rule):** `Order size 2.564 below the minimum 5 shares for venue polymarket`.
+
+**Detail string ($1 rule, passed through from venue):** `invalid amount for a marketable BUY order ($X), min size: 1`.
 
 **Parent classes:** `InvalidOrder`, `HostedTradingError`.
 

docs/trading-quickstart.mdx

@@ -162,13 +162,18 @@ The hosted trading API accepts either the venue-native identifier (returned by `
 </Note>
 
 <Note>
-**What PMXT abstracts vs what leaks through from the venue.** PMXT unifies the order shape across venues, but a few Polymarket rules pass through as-is: orders have a **5-share minimum** (a $2 buy at $0.78 is 2.5 shares and is rejected with `OrderSizeTooSmall`), and market orders are **budget-capped** (a buy spends exactly `amount` USDC, a sell sells exactly `amount` shares — `slippage_pct` is ignored). Hosted **limit** orders are not yet available and return `501`; use [self-hosted](/guides/self-hosted) for resting limits.
+**What PMXT abstracts vs what leaks through from the venue.** PMXT unifies the order shape across venues, but a few Polymarket rules pass through as-is. Polymarket enforces **two independent minimums on marketable BUY orders** — a **5-share minimum** AND a **$1 notional minimum** — and the higher of the two binds. At $0.138/share the 5-share rule alone would only require $0.69, but the $1 rule raises the effective minimum to ~8 shares (~$1.10); a 5-share buy at that price is rejected by the venue with `invalid amount for a marketable BUY order ($0.69), min size: 1` and PMXT surfaces it as `OrderSizeTooSmall`. Market orders are **budget-capped** (a buy spends exactly `amount` USDC, a sell sells exactly `amount` shares — `slippage_pct` is ignored). Hosted **limit** orders are not yet available and return `501`; use [self-hosted](/guides/self-hosted) for resting limits.
 </Note>
 
 ## 6. Verify the fill
 
 Hosted positions appear immediately on `fetch_positions`. The position's `size` is your share count; the remaining USDC sits in `fetch_balance`.
 
+<Note>
+The `id` returned by hosted `create_order` is a **PMXT internal task id**, not a Polymarket (or other venue) order id. Calling Polymarket's own order-lookup with it will return nothing. Use `client.fetch_order(id)` — the hosted SDK knows how to resolve the task and reports the live status (`queued`, `fulfilling`, `fulfilled`, `failed`, `no_fill`). A fresh `create_order` returns `status="queued"` because the venue submit happens asynchronously; poll `fetch_order` (or pass `wait=true`) to get the venue-confirmed outcome.
+</Note>
+
+
 <CodeGroup>
 ```python Python
 positions = client.fetch_positions()

sdks/python/pmxt/client.py

@@ -1510,6 +1510,12 @@ def cancel_order(self, order_id: str) -> Order:
             raise self._parse_api_exception(e) from None
 
     def fetch_order(self, order_id: str) -> Order:
+        if self.is_hosted:
+            response = self._hosted_request(
+                "fetch_order",
+                path_params={"order_id": order_id},
+            )
+            return self._hosted_single(response, "order", order_from_v0)
         try:
             args = []
             args.append(order_id)
@@ -1620,6 +1626,13 @@ def fetch_all_orders(self, params: Optional[dict] = None, **kwargs) -> List[Orde
             raise self._parse_api_exception(e) from None
 
     def fetch_positions(self, address: Optional[str] = None) -> List[Position]:
+        if self.is_hosted:
+            resolved_address = resolve_wallet_address(self, address)
+            response = self._hosted_request(
+                "fetch_positions",
+                path_params={"address": resolved_address},
+            )
+            return self._hosted_collection(response, "positions", position_from_v0)
         try:
             args = []
             if address is not None:
@@ -1641,6 +1654,13 @@ def fetch_positions(self, address: Optional[str] = None) -> List[Position]:
             raise self._parse_api_exception(e) from None
 
     def fetch_balance(self, address: Optional[str] = None) -> List[Balance]:
+        if self.is_hosted:
+            resolved_address = resolve_wallet_address(self, address)
+            response = self._hosted_request(
+                "fetch_balance",
+                path_params={"address": resolved_address},
+            )
+            return self._hosted_collection(response, "balances", balance_from_v0)
         try:
             args = []
             if address is not None:

sdks/typescript/pmxt/client.ts

@@ -1188,6 +1188,12 @@ export abstract class Exchange {
 
     async fetchOrder(orderId: string): Promise<Order> {
         await this.initPromise;
+        if (this.isHosted) {
+            const route = HOSTED_METHOD_ROUTES.get("fetchOrder")!;
+            const path = formatRoutePath(route, { order_id: orderId });
+            const data = await _tradingRequest(this, { method: route.method, path });
+            return orderFromV0(data as Record<string, unknown>);
+        }
         try {
             const args: any[] = [];
             args.push(orderId);
@@ -1318,6 +1324,14 @@ export abstract class Exchange {
 
     async fetchPositions(address?: string): Promise<Position[]> {
         await this.initPromise;
+        if (this.isHosted) {
+            const resolvedAddress = resolveWalletAddress(this, address);
+            const route = HOSTED_METHOD_ROUTES.get("fetchPositions")!;
+            const path = formatRoutePath(route, { address: resolvedAddress });
+            const data = await _tradingRequest(this, { method: route.method, path });
+            const list = Array.isArray(data) ? data : [];
+            return list.map((p) => positionFromV0(p as Record<string, unknown>));
+        }
         try {
             const args: any[] = [];
             if (address !== undefined) args.push(address);
@@ -1344,6 +1358,14 @@ export abstract class Exchange {
 
     async fetchBalance(address?: string): Promise<Balance[]> {
         await this.initPromise;
+        if (this.isHosted) {
+            const resolvedAddress = resolveWalletAddress(this, address);
+            const route = HOSTED_METHOD_ROUTES.get("fetchBalance")!;
+            const path = formatRoutePath(route, { address: resolvedAddress });
+            const data = await _tradingRequest(this, { method: route.method, path });
+            const list = Array.isArray(data) ? data : [];
+            return list.map((b) => balanceFromV0(b as Record<string, unknown>));
+        }
         try {
             const args: any[] = [];
             if (address !== undefined) args.push(address);