feat(docs): per-method hosted/self-hosted toggle on Group A reference pages (v2.49.2)

changelog.md

@@ -2,6 +2,26 @@
 
 All notable changes to this project will be documented in this file.
 
+## [2.49.2] - 2026-06-09
+
+Per-method docs follow-up to 2.49.1 — every Group A method (`createOrder`, `buildOrder`, `submitOrder`, `cancelOrder`, `fetchBalance`, `fetchPositions`, `fetchOpenOrders`, `fetchMyTrades`, `fetchOrder`, `fetchClosedOrders`, `fetchAllOrders`) now has a synchronized `Hosted (recommended)` / `Self-hosted` tab toggle on its reference page, so customers see the hosted endpoint and the v2.49 SDK constructor shape by default and can flip to the local-sidecar variant in place. Mintlify synchronizes tab selection across pages via shared label keys, so the choice persists as the user navigates the API Reference.
+
+### Added
+
+- **Docs (`docs/api-reference/`)**: 11 new shadow MDX files — one per Group A method — wrapping the existing OpenAPI auto-render in a `<Tabs>` toggle. `Hosted (recommended)` tab listed first on every page so it's the default; `Self-hosted` second. Tab labels are byte-identical across all 11 files for cross-page sync.
+- **Core (`openapi-hosted.json`)**: 9 new operations documenting the `trade.pmxt.dev/v0/*` trading surface — `buildOrderHosted` (POST `/v0/trade/build-order`), `submitOrderHosted` (POST `/v0/trade/submit-order`), `createOrderHosted` (SDK-convenience POST `/v0/trade/create-order` documentation entry), `cancelOrderHosted` (POST `/v0/orders/cancel/build`), `fetchBalanceHosted` (GET `/v0/user/{address}/balances`), `fetchPositionsHosted` (GET `/v0/user/{address}/positions`), `fetchOpenOrdersHosted` (GET `/v0/orders/open`), `fetchMyTradesHosted` (GET `/v0/user/{address}/trades`), `fetchOrderHosted` (GET `/v0/orders/{order_id}`). Each carries Python + TypeScript `x-codeSamples` using the v2.49 hosted constructor (`pmxtApiKey`, `walletAddress`, `privateKey`), error responses covering 401/403/404/410/422/503, and bearer auth via the existing `bearerAuth` security scheme. Plus 10 new component schemas for the v0 request/response shapes, all referencing existing components (`Order`, `Balance`, etc.) from 2.49.1.
+- **Docs (`docs.json`)**: Trading and "Orders & Positions" sidebar groups now reference the 11 shadow MDX slugs directly, so Mintlify renders the toggle pages instead of auto-generating from `openapi.json`.
+
+### Fixed
+
+- **Core (`createOrder` / `buildOrder` code samples)**: Pre-existing JSDoc rot — the auto-generated reference pages showed `type="market"` combined with `price=0.55`, an incoherent combination since price is only meaningful for limit orders. Replaced with coherent limit-order samples across all 16 venues (32 createOrder + 32 buildOrder samples, 64 line changes total). The fix lives in `core/scripts/generate-openapi.js`'s `PARAM_OVERRIDES` map so future regeneration emits the correct shape.
+
+### Not addressed (out of scope, flagged for follow-up)
+
+- **`fetchClosedOrdersHosted` / `fetchAllOrdersHosted`**: no underlying hosted endpoint exists — both methods raise `NotSupported` in hosted mode (closed orders are modeled as trades; use `fetchMyTrades` for historical fills). The shadow MDX files surface this via a `<Warning>` on the Hosted tab linking to `fetchMyTrades`.
+- **Escrow methods**: `client.escrow.{approve, deposit, withdraw, withdrawals}` aren't in Group A and so don't have toggle pages yet. They're hosted-only (no self-hosted variant exists), so a follow-up could add single-tab reference pages.
+- **Generator capability map gap**: `buildCapabilityMap()` in `core/scripts/generate-openapi.js` only instantiates 13 of the 16 exported exchange classes, omitting `Hyperliquid`, `GeminiTitan`, and `Mock`. Re-running the generator drops their `x-codeSamples`. The merged main spec retains the missing samples from a prior generator run; the surgical fix here didn't disturb them. Worth a real fix in a follow-up.
+
 ## [2.49.1] - 2026-06-08
 
 Positioning-shift patch on top of 2.49.0 — the hosted trading mode shipped in 2.49.0 but the docs, READMEs, and OpenAPI schemas still defaulted to the self-hosted sidecar path. This release flips the default everywhere the SDK + docs surface a customer hits: hosted PMXT is the primary experience; self-hosting becomes the advanced escape hatch. No SDK runtime behavior changes — pure documentation, schema, and copy work. Marketing-site changes ship separately in a sibling pmxt-website PR.

core/scripts/generate-openapi.js

@@ -461,6 +461,28 @@ const PARAM_OVERRIDES = {
     fetchRelatedMarkets: [{ name: 'marketId', value: '12345' }],
     fetchMatchedMarkets: [{ name: 'minDifference', value: 0.05 }],
     fetchMatchedPrices: [{ name: 'minDifference', value: 0.05 }],
+    // Self-hosted createOrder / buildOrder samples: limit order shape only.
+    // The auto-extracted shape mixed `type: "market"` with `price: 0.55`,
+    // which is incoherent (price is only meaningful for limit orders) and
+    // tacked on internal-only fields (fee, tickSize, negRisk, onBehalfOf)
+    // that the average reader shouldn't see. A clean limit-order example
+    // is the simplest correct shape.
+    createOrder: [
+        { name: 'marketId', value: '12345' },
+        { name: 'outcomeId', value: '67890' },
+        { name: 'side', value: 'buy' },
+        { name: 'type', value: 'limit' },
+        { name: 'amount', value: 10 },
+        { name: 'price', value: 0.55 },
+    ],
+    buildOrder: [
+        { name: 'marketId', value: '12345' },
+        { name: 'outcomeId', value: '67890' },
+        { name: 'side', value: 'buy' },
+        { name: 'type', value: 'limit' },
+        { name: 'amount', value: 10 },
+        { name: 'price', value: 0.55 },
+    ],
 };
 
 const FULL_OVERRIDES = {

docs/api-reference/buildOrder.mdx

@@ -0,0 +1,138 @@
+---
+title: buildOrder
+description: Build an order payload without submitting it. Hosted returns EIP-712 typed data to sign locally.
+---
+
+<Tabs>
+  <Tab title="Hosted (recommended)">
+    <Note>
+      The hosted path routes to `POST trade.pmxt.dev/v0/trade/build-order` and is
+      the default when `pmxt_api_key` is set. Returns a `built_order_id` plus EIP-712
+      typed data the wallet must sign before calling
+      [`submitOrder`](/api-reference/submitOrder). Pass catalog UUIDs
+      (`market_id`, `outcome_id`), not venue-native ids. See
+      [hosted trading](/concepts/hosted-trading) for the end-to-end flow.
+      Get a key at [pmxt.dev/dashboard](https://pmxt.dev/dashboard).
+    </Note>
+
+    <CodeGroup>
+    ```python Python
+    import pmxt
+
+    client = pmxt.Polymarket(
+        pmxt_api_key="YOUR_PMXT_API_KEY",
+        wallet_address="0xYourWallet",
+        private_key="0x...",
+    )
+    built = client.build_order(
+        market_id="12345678-1234-1234-1234-123456789abc",
+        outcome_id="abcdef01-2345-6789-abcd-ef0123456789",
+        side="buy",
+        type="limit",
+        amount=10,
+        price=0.55,
+    )
+    print(built.expiry, built.raw)
+    # Sign + submit later with client.submit_order(built).
+    ```
+
+    ```javascript TypeScript
+    import { Polymarket } from "pmxtjs";
+
+    const client = new Polymarket({
+      pmxtApiKey: "YOUR_PMXT_API_KEY",
+      walletAddress: "0xYourWallet",
+      privateKey: "0x...",
+    });
+
+    const built = await client.buildOrder({
+      marketId: "12345678-1234-1234-1234-123456789abc",
+      outcomeId: "abcdef01-2345-6789-abcd-ef0123456789",
+      side: "buy",
+      type: "limit",
+      amount: 10,
+      price: 0.55,
+    });
+    console.log(built.expiry, built.raw);
+    // Sign + submit later with client.submitOrder(built).
+    ```
+
+    ```bash curl
+    curl -X POST "https://trade.pmxt.dev/v0/trade/build-order" \
+      -H "Authorization: Bearer $PMXT_API_KEY" \
+      -H "Content-Type: application/json" \
+      -d '{
+        "market_id": "12345678-1234-1234-1234-123456789abc",
+        "outcome_id": "abcdef01-2345-6789-abcd-ef0123456789",
+        "side": "buy",
+        "order_type": "limit",
+        "amount": 10,
+        "denom": "shares",
+        "price": 0.55,
+        "user_address": "0xYourWallet"
+      }'
+    ```
+    </CodeGroup>
+  </Tab>
+
+  <Tab title="Self-hosted">
+    <Note>
+      The self-hosted path uses the local sidecar at
+      `POST localhost:3847/api/{exchange}/buildOrder`. Returns the venue-native
+      signed order or request body for inspection or deferred submission via
+      [`submitOrder`](/api-reference/submitOrder). See
+      [Self-hosted](/guides/self-hosted) for setup.
+    </Note>
+
+    <CodeGroup>
+    ```python Python
+    import pmxt
+
+    client = pmxt.Polymarket(
+        api_key="YOUR_VENUE_API_KEY",
+        api_secret="YOUR_VENUE_API_SECRET",
+        passphrase="YOUR_PASSPHRASE",
+        private_key="YOUR_PRIVATE_KEY",
+        proxy_address="YOUR_PROXY_ADDRESS",
+    )
+    built = client.build_order(
+        market_id="12345",
+        outcome_id="67890",
+        side="buy",
+        type="limit",
+        amount=10,
+        price=0.55,
+    )
+    print(built.exchange, built.raw)
+    ```
+
+    ```javascript TypeScript
+    import { Polymarket } from "pmxtjs";
+
+    const client = new Polymarket({
+      apiKey: "YOUR_VENUE_API_KEY",
+      apiSecret: "YOUR_VENUE_API_SECRET",
+      passphrase: "YOUR_PASSPHRASE",
+      privateKey: "YOUR_PRIVATE_KEY",
+      proxyAddress: "YOUR_PROXY_ADDRESS",
+    });
+
+    const built = await client.buildOrder({
+      marketId: "12345",
+      outcomeId: "67890",
+      side: "buy",
+      type: "limit",
+      amount: 10,
+      price: 0.55,
+    });
+    console.log(built.exchange, built.raw);
+    ```
+
+    ```bash curl
+    curl -X POST "http://localhost:3847/api/polymarket/buildOrder" \
+      -H "Content-Type: application/json" \
+      -d '{"args":[{"marketId":"12345","outcomeId":"67890","side":"buy","type":"limit","amount":10,"price":0.55}]}'
+    ```
+    </CodeGroup>
+  </Tab>
+</Tabs>

docs/api-reference/cancelOrder.mdx

@@ -0,0 +1,99 @@
+---
+title: cancelOrder
+description: Cancel an open order. Hosted uses a two-call build -> sign -> cancel chain.
+---
+
+<Tabs>
+  <Tab title="Hosted (recommended)">
+    <Note>
+      The hosted path is a two-call chain: `POST trade.pmxt.dev/v0/orders/cancel/build`
+      returns EIP-712 typed data for the wallet to sign, then
+      `POST trade.pmxt.dev/v0/orders/cancel` submits the signature. The SDK's
+      `cancel_order()` chains both calls. Get a key at
+      [pmxt.dev/dashboard](https://pmxt.dev/dashboard).
+    </Note>
+
+    <CodeGroup>
+    ```python Python
+    import pmxt
+
+    client = pmxt.Polymarket(
+        pmxt_api_key="YOUR_PMXT_API_KEY",
+        wallet_address="0xYourWallet",
+        private_key="0x...",
+    )
+    cancelled = client.cancel_order("order_abc123")
+    print(cancelled.id, cancelled.status)
+    ```
+
+    ```javascript TypeScript
+    import { Polymarket } from "pmxtjs";
+
+    const client = new Polymarket({
+      pmxtApiKey: "YOUR_PMXT_API_KEY",
+      walletAddress: "0xYourWallet",
+      privateKey: "0x...",
+    });
+
+    const cancelled = await client.cancelOrder("order_abc123");
+    console.log(cancelled.id, cancelled.status);
+    ```
+
+    ```bash curl
+    # Step 1: build
+    curl -X POST "https://trade.pmxt.dev/v0/orders/cancel/build" \
+      -H "Authorization: Bearer $PMXT_API_KEY" \
+      -H "Content-Type: application/json" \
+      -d '{"order_id":"order_abc123","user_address":"0xYourWallet"}'
+
+    # Step 2: sign the typed_data locally, then submit
+    curl -X POST "https://trade.pmxt.dev/v0/orders/cancel" \
+      -H "Authorization: Bearer $PMXT_API_KEY" \
+      -H "Content-Type: application/json" \
+      -d '{"cancel_id":"cnl_abc...","signature":"0x..."}'
+    ```
+    </CodeGroup>
+  </Tab>
+
+  <Tab title="Self-hosted">
+    <Note>
+      The self-hosted path uses the local sidecar at
+      `POST localhost:3847/api/{exchange}/cancelOrder` with the venue-native order id.
+      The sidecar signs and submits the cancel directly to the venue. See
+      [Self-hosted](/guides/self-hosted) for setup.
+    </Note>
+
+    <CodeGroup>
+    ```python Python
+    import pmxt
+
+    client = pmxt.Polymarket(
+        api_key="YOUR_VENUE_API_KEY",
+        private_key="YOUR_PRIVATE_KEY",
+        proxy_address="YOUR_PROXY_ADDRESS",
+    )
+    cancelled = client.cancel_order("0xVenueOrderId")
+    print(cancelled.id, cancelled.status)
+    ```
+
+    ```javascript TypeScript
+    import { Polymarket } from "pmxtjs";
+
+    const client = new Polymarket({
+      apiKey: "YOUR_VENUE_API_KEY",
+      privateKey: "YOUR_PRIVATE_KEY",
+      proxyAddress: "YOUR_PROXY_ADDRESS",
+    });
+
+    const cancelled = await client.cancelOrder("0xVenueOrderId");
+    console.log(cancelled.id, cancelled.status);
+    ```
+
+    ```bash curl
+    curl -X POST "http://localhost:3847/api/polymarket/cancelOrder" \
+      -H "Content-Type: application/json" \
+      -d '{"args":["0xVenueOrderId"]}'
+    ```
+    </CodeGroup>
+  </Tab>
+</Tabs>