fix(hosted): unblock quickstart market orders + normalize v0 trade amounts (#1019)

The client-side economics validator rejected every server-built hosted
market order pre-sign (worst_price is pinned to the tick-grid extreme by
design; max_cost_usdc/shares_6dec are the binding user protections, both
already validated). Market orders now get a (0,1) domain sanity check
only; limit orders keep the slippage bound.

Also: v0 user-trade amounts arrive in 6-dec micro-shares — normalize to
decimal shares in both SDK mappers (symmetric reverse mapping); fix the
stale create_order hosted docstring; make the trading quickstart use
real model fields and drop the slippage workaround warning.

Verified live against trade.pmxt.dev with a  market buy filled and
settled end-to-end (Polygon tx 0x803b96b4...).

Author: realfishsam

changelog.md

@@ -2,6 +2,20 @@
 
 All notable changes to this project will be documented in this file.
 
+## [2.49.8] - 2026-06-10
+
+Hosted trading quickstart actually works now. The SDKs' client-side economics validator was rejecting every server-built market order before signing (`economic mismatch: worst_price expected <= ... got 0.999`), because the hosted trading API deliberately pins market-order `worst_price` to the tick-grid extreme and caps the user with `max_cost_usdc` / `shares_6dec` instead ("textbook market semantics"). Verified live against `trade.pmxt.dev` with a real $5 fill end-to-end.
+
+### Fixed
+
+- **TS `pmxt/hosted-typed-data.ts` + Python `pmxt/_hosted_typeddata.py`**: `validateWorstPrice` / `_validate_worst_price` no longer apply the limit-order slippage bound to **market** orders. For market orders the binding user protection is `max_cost_usdc` (buys) / `shares_6dec` (sells) — both already strictly validated — so the validator now only sanity-checks that `worst_price` lies inside the open `(0, 1)` price domain. Limit orders keep the existing slippage-bound check. This unblocks `create_order` / `createOrder` market orders in hosted mode, which previously failed pre-sign, every time.
+- **TS `pmxt/hosted-mappers.ts` + Python `pmxt/_hosted_mappers.py`**: `userTradeFromV0` / `user_trade_from_v0` now normalize the v0 wire `amount` (6-dec micro-shares, e.g. `58139533.0`) to decimal shares (`58.139533`), so `UserTrade.amount` means shares — consistent with `Position.size` and the rest of the SDK. The reverse mappers scale back to micros symmetrically.
+- **Python `client.py`**: `create_order` docstring claimed "Not available through the hosted API" — it is; corrected to describe the hosted build → local-sign → submit flow.
+
+### Changed
+
+- **`docs/trading-quickstart.mdx`**: Removed the "use aggressive `slippage_pct`" workaround warning (the validator bug it papered over is fixed); market-order examples no longer pass `slippage_pct` and note that market orders are budget-capped, not price-capped. Fixed the TypeScript `createOrder` example to use `type` (the actual `CreateOrderParams` field) instead of the nonexistent `orderType`. Fixed step-6 verification snippets to use real model fields (`Position.size` / `outcome_label`, `Balance.available`) instead of nonexistent `quantity` / `notional` / `free`. Documented that hosted limit orders currently return `501`.
+
 ## [2.49.7] - 2026-06-09
 
 API Reference sidebar reorder: `Trading` and `Orders & Positions` move from near the bottom of the tab to immediately under `Events & Markets`, so the customer's natural path is walkable top-to-bottom — discover (Events & Markets) → act (Trading) → inspect state (Orders & Positions) → niche features.

docs/trading-quickstart.mdx

@@ -97,8 +97,8 @@ deposit_tx = client.escrow.deposit_tx(amount=10.0)
 # Sign and send deposit_tx with your wallet library...
 
 # 3. Confirm the deposit landed
-balance = client.fetch_balance()
-print(f"Escrow USDC: {balance.free}")
+balances = client.fetch_balance()
+print(f"Escrow USDC: {balances[0].available}")
 ```
 
 ```typescript TypeScript
@@ -111,8 +111,8 @@ const depositTx = await client.escrow.depositTx(10);
 // Sign and send depositTx with your wallet library...
 
 // 3. Confirm the deposit landed
-const balance = await client.fetchBalance();
-console.log(`Escrow USDC: ${balance.free}`);
+const balances = await client.fetchBalance();
+console.log(`Escrow USDC: ${balances[0].available}`);
 ```
 </CodeGroup>
 </Accordion>
@@ -131,11 +131,9 @@ order = client.create_order(
     outcome=yes,
     side="buy",
     order_type="market",
-    amount=5.0,
-    denom="usdc",
-    slippage_pct=30.0,
+    amount=5.0,   # market buys are denominated in USDC: spend exactly $5
 )
-print(f"Order {order.id}: {order.status}")
+print(f"Order {order.id}: {order.status} filled={order.filled}")
 ```
 
 ```typescript TypeScript
@@ -146,12 +144,10 @@ const yes = market.outcomes.find((o) => o.label.toLowerCase() === "yes")!;
 const order = await client.createOrder({
   outcome: yes,
   side: "buy",
-  orderType: "market",
-  amount: 5,
-  denom: "usdc",
-  slippagePct: 30,
+  type: "market",
+  amount: 5, // market buys are denominated in USDC: spend exactly $5
 });
-console.log(`Order ${order.id}: ${order.status}`);
+console.log(`Order ${order.id}: ${order.status} filled=${order.filled}`);
 ```
 
 ```bash curl
@@ -169,26 +165,32 @@ The hosted trading API accepts either the venue-native identifier (returned by `
 **Polymarket has a 5-share minimum per order.** At ~$0.78/share, a 5 USDC buy is ~6.4 shares — fine. But $2 at the same price is only 2.5 shares and will be rejected with `OrderSizeTooSmall`. Size up or switch to a cheaper outcome.
 </Warning>
 
-<Warning>
-**Use aggressive `slippage_pct`** until the upstream economic validator tightens its `worst_price` checks. Pragmatic defaults: `slippage_pct=30` for buys, `slippage_pct=99.9` for sells. Lower values frequently trip a precision check that has nothing to do with actual slippage.
-</Warning>
+<Note>
+**Market orders are budget-capped, not price-capped.** A market buy spends exactly `amount` USDC and a market sell sells exactly `amount` shares — the on-chain authorization caps the spend, so `slippage_pct` is not needed (and is ignored) for market orders. Hosted **limit** orders are not yet available and currently return `501`; use the self-hosted server for resting limit orders.
+</Note>
 
 ## 6. Verify the fill
 
-Hosted positions appear immediately on `fetch_positions`. The position's `quantity` and `notional` reflect the escrow-side accounting.
+Hosted positions appear immediately on `fetch_positions`. The position's `size` is your share count; the remaining USDC sits in `fetch_balance`.
 
 <CodeGroup>
 ```python Python
 positions = client.fetch_positions()
 for p in positions:
-    print(f"{p.market_id}  qty={p.quantity}  notional={p.notional}")
+    print(f"{p.market_id}  {p.outcome_label}  size={p.size}")
+
+balances = client.fetch_balance()
+print(f"Escrow USDC left: {balances[0].available}")
 ```
 
 ```typescript TypeScript
 const positions = await client.fetchPositions();
 for (const p of positions) {
-  console.log(`${p.marketId}  qty=${p.quantity}  notional=${p.notional}`);
+  console.log(`${p.marketId}  ${p.outcomeLabel}  size=${p.size}`);
 }
+
+const balances = await client.fetchBalance();
+console.log(`Escrow USDC left: ${balances[0].available}`);
 ```
 </CodeGroup>
 

package-lock.json

@@ -80,11 +80,16 @@ def order_to_v0(order: Order | Mapping[str, Any]) -> dict[str, Any]:
 def user_trade_from_v0(payload: Mapping[str, Any] | Any) -> UserTrade:
     """Map a ``UserTradeV0`` JSON object to :class:`pmxt.models.UserTrade`."""
     data = _as_dict(payload)
+    raw_amount = _float_or_none(data.get("amount"))
     values = {
         "id": _str_or_none(data.get("id")),
         "timestamp": _timestamp_to_ms(data.get("timestamp")),
         "price": _float_or_none(data.get("price")),
-        "amount": _float_or_none(data.get("amount")),
+        # The v0 wire sends trade amounts in 6-dec micro-shares (verified
+        # live: 58139533.0 == 58.139533 shares, matching the same position's
+        # decimal ``shares``). Normalize so UserTrade.amount means shares,
+        # like everywhere else in the SDK.
+        "amount": raw_amount / 1_000_000 if raw_amount is not None else None,
         "side": data.get("side") or "unknown",
         "order_id": _str_or_none(data.get("order_id")),
         "market_id": _str_or_none(data.get("market_id")),
@@ -101,12 +106,14 @@ def user_trade_from_v0(payload: Mapping[str, Any] | Any) -> UserTrade:
 def user_trade_to_v0(trade: UserTrade | Mapping[str, Any]) -> dict[str, Any]:
     """Map :class:`pmxt.models.UserTrade` back to a ``UserTradeV0`` object."""
     data = _as_dict(trade)
+    decimal_amount = _float_or_none(data.get("amount"))
     out = {
         "id": _str_or_none(data.get("id")),
         "market_id": _str_or_none(data.get("market_id")),
         "outcome_id": _str_or_none(data.get("outcome_id")),
         "side": data.get("side"),
-        "amount": _float_or_none(data.get("amount")),
+        # Inverse of user_trade_from_v0: decimal shares -> 6-dec micro-shares.
+        "amount": round(decimal_amount * 1_000_000) if decimal_amount is not None else None,
         "price": _float_or_none(data.get("price")),
         "fee": _float_or_none(data.get("fee")),
         "timestamp": _ms_to_timestamp(data.get("timestamp")),

sdks/python/pmxt/_hosted_mappers.py

@@ -419,6 +419,24 @@ def _validate_worst_price(
     build_response: Any,
 ) -> None:
     worst_price = Decimal(_message_int(message, "worst_price", "worstPrice")) / _SIX_DEC_SCALE
+
+    # Hosted MARKET orders pin worst_price to the tick-grid extreme by design
+    # ("textbook market semantics"): the binding user protection is
+    # max_cost_usdc (buys) / shares_6dec (sells), validated above. A slippage
+    # bound on worst_price would reject every server-built market order, so
+    # only sanity-check the price domain here.
+    order_type = str(
+        _first_present(
+            _value(build_request, "order_type"),
+            _value(build_request, "orderType"),
+            "market",
+        )
+    ).lower()
+    if order_type == "market":
+        if not (Decimal("0") < worst_price < Decimal("1")):
+            _economic_fail(f"worst_price expected within (0, 1) got {worst_price}")
+        return
+
     slippage_pct = _decimal(
         _first_present(
             _value(build_request, "slippage_pct"),

sdks/python/pmxt/_hosted_typeddata.py

@@ -2963,7 +2963,9 @@ def create_order(
         """
         Create a new order.
 
-        Not available through the hosted API — trades execute locally.
+        In hosted mode (``pmxt_api_key`` + ``wallet_address`` + ``private_key``)
+        this wraps build -> local EIP-712 sign -> submit against the hosted
+        trading API. Venue-direct mode executes locally with raw credentials.
 
         You can specify the market either with explicit market_id/outcome_id,
         or by passing an outcome object directly (e.g., market.yes).

sdks/python/pmxt/client.py

@@ -84,7 +84,8 @@ def _user_trade_v0(timestamp="2026-06-08T10:12:13.456Z"):
         "market_id": "market-003",
         "outcome_id": "outcome-yes",
         "side": "sell",
-        "amount": 4.5,
+        # Wire amounts are 6-dec micro-shares; the SDK normalizes to decimal.
+        "amount": 4_500_000,
         "price": 0.71,
         "fee": 0.02,
         "timestamp": timestamp,

sdks/python/tests/test_hosted_mappers.py

@@ -469,15 +469,54 @@ def test_validate_economics_rejects_tampered_max_cost_usdc() -> None:
         )
 
 
-def test_validate_economics_rejects_worst_price_outside_slippage_bound() -> None:
+def test_validate_economics_rejects_worst_price_outside_slippage_bound_for_limit() -> None:
     fixture = _fixture("polymarket_buy")
+    build_request = {**_copy(fixture["build_request"]), "order_type": "limit"}
     response = _with_response_field(
         fixture["build_response"],
         "worstPrice",
         "worst_price",
         900_000,
     )
 
+    with pytest.raises(InvalidSignature):
+        validate_economics(
+            route=fixture["route"],
+            build_request=build_request,
+            build_response=response,
+        )
+
+
+def test_validate_economics_accepts_pinned_worst_price_for_market_orders() -> None:
+    """Hosted market orders pin worst_price to the tick-grid extreme by
+    design — max_cost_usdc is the binding user protection. The validator
+    must NOT apply the limit-order slippage bound (regression: every
+    documented quickstart market buy was rejected pre-sign)."""
+    fixture = _fixture("polymarket_buy")
+    response = _with_response_field(
+        fixture["build_response"],
+        "worstPrice",
+        "worst_price",
+        999_000,
+    )
+
+    validate_economics(
+        route=fixture["route"],
+        build_request=_copy(fixture["build_request"]),
+        build_response=response,
+    )
+
+
+@pytest.mark.parametrize("pinned", [0, 1_000_000, 2_000_000])
+def test_validate_economics_rejects_market_worst_price_outside_domain(pinned: int) -> None:
+    fixture = _fixture("polymarket_buy")
+    response = _with_response_field(
+        fixture["build_response"],
+        "worstPrice",
+        "worst_price",
+        pinned,
+    )
+
     with pytest.raises(InvalidSignature):
         validate_economics(
             route=fixture["route"],

sdks/python/tests/test_hosted_typeddata.py

@@ -108,7 +108,11 @@ export function userTradeFromV0(payload: Record<string, unknown>): UserTrade {
     const trade: UserTrade = {
         id: strOrEmpty(payload["id"]),
         price: floatOrZero(payload["price"]),
-        amount: floatOrZero(payload["amount"]),
+        // The v0 wire sends trade amounts in 6-dec micro-shares (verified
+        // live: 58139533.0 == 58.139533 shares, matching the same position's
+        // decimal `shares`). Normalize so UserTrade.amount means shares,
+        // like everywhere else in the SDK.
+        amount: floatOrZero(payload["amount"]) / 1_000_000,
         side,
         timestamp: timestampToMs(payload["timestamp"]),
     };
@@ -130,7 +134,8 @@ export function userTradeToV0(trade: UserTrade): Record<string, unknown> {
     const out: Record<string, unknown> = {
         id: trade.id,
         side: trade.side,
-        amount: trade.amount,
+        // Inverse of userTradeFromV0: decimal shares -> 6-dec micro-shares.
+        amount: Math.round(trade.amount * 1_000_000),
         price: trade.price,
         timestamp: msToTimestamp(trade.timestamp),
     };

sdks/typescript/pmxt/hosted-mappers.ts

@@ -442,6 +442,28 @@ function validateWorstPrice(
 ): void {
     const worstPriceMicro = messageBigInt(message, "worst_price", "worstPrice");
     const worstPrice = Number(worstPriceMicro) / SIX_DEC_DIVISOR;
+
+    // Hosted MARKET orders pin worst_price to the tick-grid extreme by
+    // design ("textbook market semantics"): the binding user protection is
+    // max_cost_usdc (buys) / shares_6dec (sells), validated above. A
+    // slippage bound on worst_price would reject every server-built market
+    // order, so only sanity-check the price domain here.
+    const orderType = String(
+        firstPresent(
+            getField(buildRequest, "order_type"),
+            getField(buildRequest, "orderType"),
+            "market",
+        ),
+    ).toLowerCase();
+    if (orderType === "market") {
+        if (!(worstPrice > 0 && worstPrice < 1)) {
+            economicFail(
+                `worst_price expected within (0, 1) got ${worstPrice}`,
+            );
+        }
+        return;
+    }
+
     const slippagePctRaw = firstPresent(
         getField(buildRequest, "slippage_pct"),
         getField(buildRequest, "slippagePct"),