pmxtjs 2.51.1 → 2.51.2

package/dist/esm/index.d.ts

@@ -17,13 +17,13 @@
  * console.log(markets[0].title);
  * ```
  */
-import { Exchange, Polymarket, Kalshi, KalshiDemo, Limitless, Myriad, Probable, Baozi, Opinion, Metaculus, Smarkets, PolymarketUS, GeminiTitan, Hyperliquid, SuiBets, Rain, Mock } from "./pmxt/client.js";
+import { Exchange, Polymarket, Kalshi, KalshiDemo, Limitless, Myriad, Probable, Baozi, Opinion, Metaculus, Smarkets, PolymarketUS, GeminiTitan, Hyperliquid, SuiBets, Rain, Hunch, Mock } from "./pmxt/client.js";
 import { Router } from "./pmxt/router.js";
 import { ServerManager } from "./pmxt/server-manager.js";
 import { FeedClient } from "./pmxt/feed-client.js";
 import * as models from "./pmxt/models.js";
 import * as errors from "./pmxt/errors.js";
-export { Exchange, Polymarket, Kalshi, KalshiDemo, Limitless, Myriad, Probable, Baozi, Opinion, Metaculus, Smarkets, PolymarketUS, GeminiTitan, Hyperliquid, SuiBets, Suibets, Rain, Mock, PolymarketOptions } from "./pmxt/client.js";
+export { Exchange, Polymarket, Kalshi, KalshiDemo, Limitless, Myriad, Probable, Baozi, Opinion, Metaculus, Smarkets, PolymarketUS, GeminiTitan, Hyperliquid, SuiBets, Suibets, Rain, Hunch, Mock, PolymarketOptions } from "./pmxt/client.js";
 export { FeedClient } from "./pmxt/feed-client.js";
 export type { Ticker, Tickers, OHLCV, Market as FeedMarket, OracleRound, FeedClientOptions } from "./pmxt/feed-client.js";
 export { Router } from "./pmxt/router.js";
@@ -97,6 +97,7 @@ declare const pmxt: {
     SuiBets: typeof SuiBets;
     Suibets: typeof SuiBets;
     Rain: typeof Rain;
+    Hunch: typeof Hunch;
     Mock: typeof Mock;
     Router: typeof Router;
     ServerManager: typeof ServerManager;

package/dist/esm/index.js

@@ -17,13 +17,13 @@
  * console.log(markets[0].title);
  * ```
  */
-import { Exchange, Polymarket, Kalshi, KalshiDemo, Limitless, Myriad, Probable, Baozi, Opinion, Metaculus, Smarkets, PolymarketUS, GeminiTitan, Hyperliquid, SuiBets, Suibets, Rain, Mock } from "./pmxt/client.js";
+import { Exchange, Polymarket, Kalshi, KalshiDemo, Limitless, Myriad, Probable, Baozi, Opinion, Metaculus, Smarkets, PolymarketUS, GeminiTitan, Hyperliquid, SuiBets, Suibets, Rain, Hunch, Mock } from "./pmxt/client.js";
 import { Router } from "./pmxt/router.js";
 import { ServerManager } from "./pmxt/server-manager.js";
 import { FeedClient } from "./pmxt/feed-client.js";
 import * as models from "./pmxt/models.js";
 import * as errors from "./pmxt/errors.js";
-export { Exchange, Polymarket, Kalshi, KalshiDemo, Limitless, Myriad, Probable, Baozi, Opinion, Metaculus, Smarkets, PolymarketUS, GeminiTitan, Hyperliquid, SuiBets, Suibets, Rain, Mock } from "./pmxt/client.js";
+export { Exchange, Polymarket, Kalshi, KalshiDemo, Limitless, Myriad, Probable, Baozi, Opinion, Metaculus, Smarkets, PolymarketUS, GeminiTitan, Hyperliquid, SuiBets, Suibets, Rain, Hunch, Mock } from "./pmxt/client.js";
 export { FeedClient } from "./pmxt/feed-client.js";
 export { Router } from "./pmxt/router.js";
 export { ServerManager } from "./pmxt/server-manager.js";
@@ -78,6 +78,7 @@ const pmxt = {
     SuiBets,
     Suibets,
     Rain,
+    Hunch,
     Mock,
     Router,
     ServerManager,

package/dist/esm/pmxt/client.d.ts

@@ -105,6 +105,7 @@ export declare abstract class Exchange {
     private _wsClient;
     /** Sticky flag: true if the sidecar /ws endpoint is unavailable. */
     private _wsUnsupported;
+    private readonly _useSidecarLockBaseUrl;
     constructor(exchangeName: string, options?: ExchangeOptions);
     private initializeServer;
     protected handleResponse(response: any): any;
@@ -125,9 +126,9 @@ export declare abstract class Exchange {
     /**
      * Resolve the current sidecar base URL.
      *
-     * For hosted mode the configured basePath is returned as-is.
-     * For local mode the port is re-read from the lock file on every
-     * call so we pick up sidecar restarts that land on a different port.
+     * Hosted mode and explicit baseUrl clients keep the configured basePath.
+     * Default local clients re-read the lock-file port on every call so they
+     * pick up sidecar restarts that land on a different port.
      */
     private resolveBaseUrl;
     /**
@@ -576,6 +577,14 @@ export interface PolymarketOptions {
     proxyAddress?: string;
     /** Optional signature type */
     signatureType?: 'eoa' | 'poly-proxy' | 'gnosis-safe' | number;
+    /**
+     * EVM wallet address used for hosted reads/writes.
+     */
+    walletAddress?: string;
+    /**
+     * External signer used for hosted writes.
+     */
+    signer?: Signer;
 }
 export declare class Polymarket extends Exchange {
     constructor(options?: PolymarketOptions);
@@ -856,6 +865,15 @@ export declare const Suibets: typeof SuiBets;
 export declare class Rain extends Exchange {
     constructor(options?: ExchangeOptions);
 }
+/**
+ * Hunch exchange client.
+ *
+ * Hunch is a crypto-native prediction market. Reads are unauthenticated;
+ * trading requires an EVM private key.
+ */
+export declare class Hunch extends Exchange {
+    constructor(options?: ExchangeOptions);
+}
 /**
  * Mock exchange client.
  *

package/dist/esm/pmxt/client.js

@@ -7,8 +7,8 @@
 import { Configuration, DefaultApi, } from "../generated/src/index.js";
 import { MarketList, } from "./models.js";
 import { ServerManager } from "./server-manager.js";
-import { PmxtError, fromServerError, InvalidOrder } from "./errors.js";
-import { resolvePmxtBaseUrl } from "./constants.js";
+import { PmxtError, fromServerError, InvalidOrder, NotSupported } from "./errors.js";
+import { ENV, resolvePmxtBaseUrl } from "./constants.js";
 import { SidecarWsClient } from "./ws-client.js";
 import { logger } from "./logger.js";
 // Hosted-mode trading dispatch.
@@ -190,6 +190,7 @@ export class Exchange {
     _wsClient = null;
     /** Sticky flag: true if the sidecar /ws endpoint is unavailable. */
     _wsUnsupported = false;
+    _useSidecarLockBaseUrl;
     constructor(exchangeName, options = {}) {
         this.exchangeName = exchangeName.toLowerCase();
         this.apiKey = options.apiKey;
@@ -207,6 +208,9 @@ export class Exchange {
         const baseUrl = resolved.baseUrl;
         this.pmxtApiKey = resolved.pmxtApiKey;
         this.isHosted = resolved.isHosted;
+        const hasBaseUrlOverride = Boolean(options.baseUrl ||
+            (typeof process !== "undefined" && process.env[ENV.BASE_URL]));
+        this._useSidecarLockBaseUrl = !this.isHosted && !hasBaseUrlOverride;
         // Hosted trading bridge: if the caller passed a privateKey but no
         // explicit signer, lazily wrap it in an EthersSigner so that
         // `pmxt.Polymarket(pmxtApiKey, privateKey)` just works without the
@@ -247,15 +251,17 @@ export class Exchange {
         if (autoStartServer) {
             try {
                 await this.serverManager.ensureServerRunning();
-                // Get the actual port the server is running on
-                // (may differ from default if default port was busy)
-                const actualPort = this.serverManager.getRunningPort();
-                const newBaseUrl = `http://localhost:${actualPort}`;
-                // Update API client with actual base URL
-                this.config = new Configuration({
-                    basePath: newBaseUrl,
-                });
-                this.api = new DefaultApi(this.config);
+                if (this._useSidecarLockBaseUrl) {
+                    // Get the actual port the server is running on
+                    // (may differ from default if default port was busy)
+                    const actualPort = this.serverManager.getRunningPort();
+                    const newBaseUrl = `http://localhost:${actualPort}`;
+                    // Update API client with actual base URL
+                    this.config = new Configuration({
+                        basePath: newBaseUrl,
+                    });
+                    this.api = new DefaultApi(this.config);
+                }
             }
             catch (error) {
                 const msg = `Failed to start PMXT server: ${error instanceof Error ? error.message : error}\n\n` +
@@ -329,12 +335,12 @@ export class Exchange {
     /**
      * Resolve the current sidecar base URL.
      *
-     * For hosted mode the configured basePath is returned as-is.
-     * For local mode the port is re-read from the lock file on every
-     * call so we pick up sidecar restarts that land on a different port.
+     * Hosted mode and explicit baseUrl clients keep the configured basePath.
+     * Default local clients re-read the lock-file port on every call so they
+     * pick up sidecar restarts that land on a different port.
      */
     resolveBaseUrl() {
-        if (this.isHosted)
+        if (this.isHosted || !this._useSidecarLockBaseUrl)
             return this.config.basePath;
         const port = this.serverManager.getRunningPort();
         return `http://localhost:${port}`;
@@ -1018,7 +1024,10 @@ export class Exchange {
             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);
+            const payload = data && typeof data === "object" && "order" in data
+                ? data.order
+                : data;
+            return orderFromV0(payload);
         }
         try {
             const args = [];
@@ -1124,6 +1133,9 @@ export class Exchange {
     }
     async fetchClosedOrders(params) {
         await this.initPromise;
+        if (this.isHosted) {
+            throw new NotSupported("fetchClosedOrders is not available in hosted trading mode.");
+        }
         try {
             const args = [];
             if (params !== undefined)
@@ -1152,6 +1164,9 @@ export class Exchange {
     }
     async fetchAllOrders(params) {
         await this.initPromise;
+        if (this.isHosted) {
+            throw new NotSupported("fetchAllOrders is not available in hosted trading mode.");
+        }
         try {
             const args = [];
             if (params !== undefined)
@@ -1185,7 +1200,9 @@ export class Exchange {
             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 : [];
+            const list = Array.isArray(data)
+                ? data
+                : (data && Array.isArray(data.positions) ? data.positions : []);
             return list.map((p) => positionFromV0(p));
         }
         try {
@@ -1221,7 +1238,9 @@ export class Exchange {
             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 : [];
+            const list = Array.isArray(data)
+                ? data
+                : (data && Array.isArray(data.balances) ? data.balances : []);
             return list.map((b) => balanceFromV0(b));
         }
         try {
@@ -3034,6 +3053,17 @@ export class Rain extends Exchange {
         super("rain", options);
     }
 }
+/**
+ * Hunch exchange client.
+ *
+ * Hunch is a crypto-native prediction market. Reads are unauthenticated;
+ * trading requires an EVM private key.
+ */
+export class Hunch extends Exchange {
+    constructor(options = {}) {
+        super("hunch", options);
+    }
+}
 /**
  * Mock exchange client.
  *

package/dist/esm/pmxt/escrow.js

@@ -9,6 +9,80 @@
  * Mirrors `sdks/python/pmxt/escrow.py`.
  */
 import { _tradingRequest, formatRoutePath, HOSTED_METHOD_ROUTES, resolveWalletAddress, } from "./hosted-routing.js";
+import { ValidationError } from "./errors.js";
+const APPROVAL_TOKENS = new Set(["usdc", "ctf"]);
+const WITHDRAW_ACTIONS = new Set(["request", "claim", "cancel"]);
+const USDC_SCALE = 1000000n;
+function isDecimalTokenId(token) {
+    return /^[0-9]+$/.test(token);
+}
+function normalizeApprovalToken(token) {
+    if (typeof token !== "string") {
+        throw new ValidationError("token must be 'usdc', 'ctf', or a decimal CTF token_id string", "token");
+    }
+    const candidate = token.trim();
+    const normalized = candidate.toLowerCase();
+    if (APPROVAL_TOKENS.has(normalized)) {
+        return normalized;
+    }
+    if (isDecimalTokenId(candidate)) {
+        return candidate;
+    }
+    throw new ValidationError("token must be 'usdc', 'ctf', or a decimal CTF token_id string", "token");
+}
+function normalizeAmountWei(amountWei) {
+    if (amountWei === undefined) {
+        return undefined;
+    }
+    if (typeof amountWei !== "bigint") {
+        throw new ValidationError("amount_wei must be a non-negative integer", "amount_wei");
+    }
+    if (amountWei < 0n) {
+        throw new ValidationError("amount_wei must be non-negative", "amount_wei");
+    }
+    return amountWei.toString();
+}
+function validateUsdcDecimal(value, field) {
+    const match = /^([0-9]+)(?:\.([0-9]+))?$/.exec(value);
+    if (!match) {
+        throw new ValidationError(`${field} must be a finite positive number`, field);
+    }
+    const fractional = match[2] ?? "";
+    if (fractional.length > 6) {
+        throw new ValidationError(`${field} precision exceeds 6 decimals; max precision for USDC is 0.000001`, field);
+    }
+    const scaled = BigInt(match[1]) * USDC_SCALE + BigInt(fractional.padEnd(6, "0"));
+    if (scaled <= 0n) {
+        throw new ValidationError(`${field} must be positive`, field);
+    }
+}
+function normalizeUsdcAmount(value, field = "amount") {
+    if (typeof value === "bigint") {
+        if (value <= 0n) {
+            throw new ValidationError(`${field} must be positive`, field);
+        }
+        return value.toString();
+    }
+    if (typeof value === "number") {
+        if (!Number.isFinite(value)) {
+            throw new ValidationError(`${field} must be a finite positive number`, field);
+        }
+        validateUsdcDecimal(String(value), field);
+        return value;
+    }
+    if (typeof value === "string") {
+        const trimmed = value.trim();
+        validateUsdcDecimal(trimmed, field);
+        return trimmed;
+    }
+    throw new ValidationError(`${field} must be a finite positive number`, field);
+}
+function normalizeWithdrawAction(action) {
+    if (typeof action === "string" && WITHDRAW_ACTIONS.has(action)) {
+        return action;
+    }
+    throw new ValidationError("action must be 'request', 'claim', or 'cancel'", "action");
+}
 export class Escrow {
     client;
     constructor(client) {
@@ -19,13 +93,16 @@ export class Escrow {
      * `amountWei` is omitted, the server returns an unlimited approval.
      */
     async approveTx(token, amountWei) {
+        const address = resolveWalletAddress(this.client);
+        const approvalAmount = normalizeAmountWei(amountWei);
         const route = HOSTED_METHOD_ROUTES.get("escrowApproveTx");
         return _tradingRequest(this.client, {
             method: route.method,
             path: route.path,
             body: {
-                token,
-                amount_wei: amountWei === undefined ? null : amountWei.toString(),
+                token: normalizeApprovalToken(token),
+                user_address: address,
+                ...(approvalAmount === undefined ? {} : { amount_wei: approvalAmount }),
             },
         });
     }
@@ -34,12 +111,15 @@ export class Escrow {
      * grid). Accepts number, decimal string, or BigInt in micro-units.
      */
     async depositTx(amount) {
+        const address = resolveWalletAddress(this.client);
         const route = HOSTED_METHOD_ROUTES.get("escrowDepositTx");
         return _tradingRequest(this.client, {
             method: route.method,
             path: route.path,
             body: {
-                amount: typeof amount === "bigint" ? amount.toString() : amount,
+                token: "usdc",
+                amount: normalizeUsdcAmount(amount),
+                user_address: address,
             },
         });
     }
@@ -49,16 +129,31 @@ export class Escrow {
      * the timelock, `cancel` aborts a pending request.
      */
     async withdrawTx(action, amount) {
+        const normalizedAction = normalizeWithdrawAction(action);
+        const address = resolveWalletAddress(this.client);
         const route = HOSTED_METHOD_ROUTES.get("escrowWithdrawTx");
-        const normalizedAmount = amount === undefined
-            ? null
-            : typeof amount === "bigint"
-                ? amount.toString()
-                : amount;
+        if (normalizedAction === "request") {
+            if (amount === undefined) {
+                throw new ValidationError("amount is required when action='request'", "amount");
+            }
+            return _tradingRequest(this.client, {
+                method: route.method,
+                path: route.path,
+                body: {
+                    action: normalizedAction,
+                    token: "usdc",
+                    amount: normalizeUsdcAmount(amount),
+                    user_address: address,
+                },
+            });
+        }
+        if (amount !== undefined) {
+            throw new ValidationError(`amount must be omitted when action='${normalizedAction}'`, "amount");
+        }
         return _tradingRequest(this.client, {
             method: route.method,
             path: route.path,
-            body: { action, amount: normalizedAmount },
+            body: { action: normalizedAction, token: "usdc", user_address: address },
         });
     }
     /**
@@ -67,12 +162,16 @@ export class Escrow {
      */
     async withdrawals(opts = {}) {
         const address = resolveWalletAddress(this.client, opts.address);
+        const include = (opts.include ?? "pending,events").trim();
+        if (!include) {
+            throw new ValidationError("include must not be empty", "include");
+        }
         const route = HOSTED_METHOD_ROUTES.get("escrowWithdrawals");
         const path = formatRoutePath(route, { address });
         return _tradingRequest(this.client, {
             method: route.method,
             path,
-            params: { include: opts.include ?? "pending,events" },
+            params: { include },
         });
     }
 }

package/dist/esm/pmxt/server-manager.js

@@ -81,12 +81,14 @@ export class ServerManager {
      * Check if the server is running.
      */
     async isServerRunning() {
-        // Read lock file to get current port
-        const port = this.getRunningPort();
+        const info = this.getServerInfo();
+        if (!info?.port) {
+            return false;
+        }
         try {
             // Use native fetch to check health on the actual running port
             // This avoids issues where this.api is configured with the wrong port
-            const response = await fetch(`http://localhost:${port}/health`, {
+            const response = await fetch(`http://localhost:${info.port}/health`, {
                 signal: AbortSignal.timeout(5_000),
             });
             if (response.ok) {

package/dist/index.d.ts

@@ -17,13 +17,13 @@
  * console.log(markets[0].title);
  * ```
  */
-import { Exchange, Polymarket, Kalshi, KalshiDemo, Limitless, Myriad, Probable, Baozi, Opinion, Metaculus, Smarkets, PolymarketUS, GeminiTitan, Hyperliquid, SuiBets, Rain, Mock } from "./pmxt/client.js";
+import { Exchange, Polymarket, Kalshi, KalshiDemo, Limitless, Myriad, Probable, Baozi, Opinion, Metaculus, Smarkets, PolymarketUS, GeminiTitan, Hyperliquid, SuiBets, Rain, Hunch, Mock } from "./pmxt/client.js";
 import { Router } from "./pmxt/router.js";
 import { ServerManager } from "./pmxt/server-manager.js";
 import { FeedClient } from "./pmxt/feed-client.js";
 import * as models from "./pmxt/models.js";
 import * as errors from "./pmxt/errors.js";
-export { Exchange, Polymarket, Kalshi, KalshiDemo, Limitless, Myriad, Probable, Baozi, Opinion, Metaculus, Smarkets, PolymarketUS, GeminiTitan, Hyperliquid, SuiBets, Suibets, Rain, Mock, PolymarketOptions } from "./pmxt/client.js";
+export { Exchange, Polymarket, Kalshi, KalshiDemo, Limitless, Myriad, Probable, Baozi, Opinion, Metaculus, Smarkets, PolymarketUS, GeminiTitan, Hyperliquid, SuiBets, Suibets, Rain, Hunch, Mock, PolymarketOptions } from "./pmxt/client.js";
 export { FeedClient } from "./pmxt/feed-client.js";
 export type { Ticker, Tickers, OHLCV, Market as FeedMarket, OracleRound, FeedClientOptions } from "./pmxt/feed-client.js";
 export { Router } from "./pmxt/router.js";
@@ -97,6 +97,7 @@ declare const pmxt: {
     SuiBets: typeof SuiBets;
     Suibets: typeof SuiBets;
     Rain: typeof Rain;
+    Hunch: typeof Hunch;
     Mock: typeof Mock;
     Router: typeof Router;
     ServerManager: typeof ServerManager;

package/dist/index.js

@@ -55,7 +55,7 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.server = exports.MarketList = exports.LIMITLESS_VENUE_ESCROW_ADDRESSES = exports.VENUE_ESCROW_ADDRESSES = exports.PREFUNDED_ESCROW_ADDRESSES = exports.resolvePmxtBaseUrl = exports.ENV = exports.LOCAL_URL = exports.HOSTED_URL = exports.ServerManager = exports.Router = exports.FeedClient = exports.Mock = exports.Rain = exports.Suibets = exports.SuiBets = exports.Hyperliquid = exports.GeminiTitan = exports.PolymarketUS = exports.Smarkets = exports.Metaculus = exports.Opinion = exports.Baozi = exports.Probable = exports.Myriad = exports.Limitless = exports.KalshiDemo = exports.Kalshi = exports.Polymarket = exports.Exchange = void 0;
+exports.server = exports.MarketList = exports.LIMITLESS_VENUE_ESCROW_ADDRESSES = exports.VENUE_ESCROW_ADDRESSES = exports.PREFUNDED_ESCROW_ADDRESSES = exports.resolvePmxtBaseUrl = exports.ENV = exports.LOCAL_URL = exports.HOSTED_URL = exports.ServerManager = exports.Router = exports.FeedClient = exports.Mock = exports.Hunch = exports.Rain = exports.Suibets = exports.SuiBets = exports.Hyperliquid = exports.GeminiTitan = exports.PolymarketUS = exports.Smarkets = exports.Metaculus = exports.Opinion = exports.Baozi = exports.Probable = exports.Myriad = exports.Limitless = exports.KalshiDemo = exports.Kalshi = exports.Polymarket = exports.Exchange = void 0;
 const client_js_1 = require("./pmxt/client.js");
 const router_js_1 = require("./pmxt/router.js");
 const server_manager_js_1 = require("./pmxt/server-manager.js");
@@ -80,6 +80,7 @@ Object.defineProperty(exports, "Hyperliquid", { enumerable: true, get: function
 Object.defineProperty(exports, "SuiBets", { enumerable: true, get: function () { return client_js_2.SuiBets; } });
 Object.defineProperty(exports, "Suibets", { enumerable: true, get: function () { return client_js_2.Suibets; } });
 Object.defineProperty(exports, "Rain", { enumerable: true, get: function () { return client_js_2.Rain; } });
+Object.defineProperty(exports, "Hunch", { enumerable: true, get: function () { return client_js_2.Hunch; } });
 Object.defineProperty(exports, "Mock", { enumerable: true, get: function () { return client_js_2.Mock; } });
 var feed_client_js_2 = require("./pmxt/feed-client.js");
 Object.defineProperty(exports, "FeedClient", { enumerable: true, get: function () { return feed_client_js_2.FeedClient; } });
@@ -146,6 +147,7 @@ const pmxt = {
     SuiBets: client_js_1.SuiBets,
     Suibets: client_js_1.Suibets,
     Rain: client_js_1.Rain,
+    Hunch: client_js_1.Hunch,
     Mock: client_js_1.Mock,
     Router: router_js_1.Router,
     ServerManager: server_manager_js_1.ServerManager,

package/dist/pmxt/client.d.ts

@@ -105,6 +105,7 @@ export declare abstract class Exchange {
     private _wsClient;
     /** Sticky flag: true if the sidecar /ws endpoint is unavailable. */
     private _wsUnsupported;
+    private readonly _useSidecarLockBaseUrl;
     constructor(exchangeName: string, options?: ExchangeOptions);
     private initializeServer;
     protected handleResponse(response: any): any;
@@ -125,9 +126,9 @@ export declare abstract class Exchange {
     /**
      * Resolve the current sidecar base URL.
      *
-     * For hosted mode the configured basePath is returned as-is.
-     * For local mode the port is re-read from the lock file on every
-     * call so we pick up sidecar restarts that land on a different port.
+     * Hosted mode and explicit baseUrl clients keep the configured basePath.
+     * Default local clients re-read the lock-file port on every call so they
+     * pick up sidecar restarts that land on a different port.
      */
     private resolveBaseUrl;
     /**
@@ -576,6 +577,14 @@ export interface PolymarketOptions {
     proxyAddress?: string;
     /** Optional signature type */
     signatureType?: 'eoa' | 'poly-proxy' | 'gnosis-safe' | number;
+    /**
+     * EVM wallet address used for hosted reads/writes.
+     */
+    walletAddress?: string;
+    /**
+     * External signer used for hosted writes.
+     */
+    signer?: Signer;
 }
 export declare class Polymarket extends Exchange {
     constructor(options?: PolymarketOptions);
@@ -856,6 +865,15 @@ export declare const Suibets: typeof SuiBets;
 export declare class Rain extends Exchange {
     constructor(options?: ExchangeOptions);
 }
+/**
+ * Hunch exchange client.
+ *
+ * Hunch is a crypto-native prediction market. Reads are unauthenticated;
+ * trading requires an EVM private key.
+ */
+export declare class Hunch extends Exchange {
+    constructor(options?: ExchangeOptions);
+}
 /**
  * Mock exchange client.
  *

package/dist/pmxt/client.js

@@ -6,7 +6,7 @@
  * OpenAPI client, matching the Python API exactly.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.Mock = exports.Rain = exports.Suibets = exports.SuiBets = exports.Hyperliquid = exports.GeminiTitan = exports.PolymarketUS = exports.Smarkets = exports.Metaculus = exports.Opinion = exports.Baozi = exports.Probable = exports.Myriad = exports.KalshiDemo = exports.Limitless = exports.Kalshi = exports.Polymarket = exports.Exchange = void 0;
+exports.Mock = exports.Hunch = exports.Rain = exports.Suibets = exports.SuiBets = exports.Hyperliquid = exports.GeminiTitan = exports.PolymarketUS = exports.Smarkets = exports.Metaculus = exports.Opinion = exports.Baozi = exports.Probable = exports.Myriad = exports.KalshiDemo = exports.Limitless = exports.Kalshi = exports.Polymarket = exports.Exchange = void 0;
 const index_js_1 = require("../generated/src/index.js");
 const models_js_1 = require("./models.js");
 const server_manager_js_1 = require("./server-manager.js");
@@ -193,6 +193,7 @@ class Exchange {
     _wsClient = null;
     /** Sticky flag: true if the sidecar /ws endpoint is unavailable. */
     _wsUnsupported = false;
+    _useSidecarLockBaseUrl;
     constructor(exchangeName, options = {}) {
         this.exchangeName = exchangeName.toLowerCase();
         this.apiKey = options.apiKey;
@@ -210,6 +211,9 @@ class Exchange {
         const baseUrl = resolved.baseUrl;
         this.pmxtApiKey = resolved.pmxtApiKey;
         this.isHosted = resolved.isHosted;
+        const hasBaseUrlOverride = Boolean(options.baseUrl ||
+            (typeof process !== "undefined" && process.env[constants_js_1.ENV.BASE_URL]));
+        this._useSidecarLockBaseUrl = !this.isHosted && !hasBaseUrlOverride;
         // Hosted trading bridge: if the caller passed a privateKey but no
         // explicit signer, lazily wrap it in an EthersSigner so that
         // `pmxt.Polymarket(pmxtApiKey, privateKey)` just works without the
@@ -250,15 +254,17 @@ class Exchange {
         if (autoStartServer) {
             try {
                 await this.serverManager.ensureServerRunning();
-                // Get the actual port the server is running on
-                // (may differ from default if default port was busy)
-                const actualPort = this.serverManager.getRunningPort();
-                const newBaseUrl = `http://localhost:${actualPort}`;
-                // Update API client with actual base URL
-                this.config = new index_js_1.Configuration({
-                    basePath: newBaseUrl,
-                });
-                this.api = new index_js_1.DefaultApi(this.config);
+                if (this._useSidecarLockBaseUrl) {
+                    // Get the actual port the server is running on
+                    // (may differ from default if default port was busy)
+                    const actualPort = this.serverManager.getRunningPort();
+                    const newBaseUrl = `http://localhost:${actualPort}`;
+                    // Update API client with actual base URL
+                    this.config = new index_js_1.Configuration({
+                        basePath: newBaseUrl,
+                    });
+                    this.api = new index_js_1.DefaultApi(this.config);
+                }
             }
             catch (error) {
                 const msg = `Failed to start PMXT server: ${error instanceof Error ? error.message : error}\n\n` +
@@ -332,12 +338,12 @@ class Exchange {
     /**
      * Resolve the current sidecar base URL.
      *
-     * For hosted mode the configured basePath is returned as-is.
-     * For local mode the port is re-read from the lock file on every
-     * call so we pick up sidecar restarts that land on a different port.
+     * Hosted mode and explicit baseUrl clients keep the configured basePath.
+     * Default local clients re-read the lock-file port on every call so they
+     * pick up sidecar restarts that land on a different port.
      */
     resolveBaseUrl() {
-        if (this.isHosted)
+        if (this.isHosted || !this._useSidecarLockBaseUrl)
             return this.config.basePath;
         const port = this.serverManager.getRunningPort();
         return `http://localhost:${port}`;
@@ -1021,7 +1027,10 @@ class Exchange {
             const route = hosted_routing_js_1.HOSTED_METHOD_ROUTES.get("fetchOrder");
             const path = (0, hosted_routing_js_1.formatRoutePath)(route, { order_id: orderId });
             const data = await (0, hosted_routing_js_1._tradingRequest)(this, { method: route.method, path });
-            return (0, hosted_mappers_js_1.orderFromV0)(data);
+            const payload = data && typeof data === "object" && "order" in data
+                ? data.order
+                : data;
+            return (0, hosted_mappers_js_1.orderFromV0)(payload);
         }
         try {
             const args = [];
@@ -1127,6 +1136,9 @@ class Exchange {
     }
     async fetchClosedOrders(params) {
         await this.initPromise;
+        if (this.isHosted) {
+            throw new errors_js_1.NotSupported("fetchClosedOrders is not available in hosted trading mode.");
+        }
         try {
             const args = [];
             if (params !== undefined)
@@ -1155,6 +1167,9 @@ class Exchange {
     }
     async fetchAllOrders(params) {
         await this.initPromise;
+        if (this.isHosted) {
+            throw new errors_js_1.NotSupported("fetchAllOrders is not available in hosted trading mode.");
+        }
         try {
             const args = [];
             if (params !== undefined)
@@ -1188,7 +1203,9 @@ class Exchange {
             const route = hosted_routing_js_1.HOSTED_METHOD_ROUTES.get("fetchPositions");
             const path = (0, hosted_routing_js_1.formatRoutePath)(route, { address: resolvedAddress });
             const data = await (0, hosted_routing_js_1._tradingRequest)(this, { method: route.method, path });
-            const list = Array.isArray(data) ? data : [];
+            const list = Array.isArray(data)
+                ? data
+                : (data && Array.isArray(data.positions) ? data.positions : []);
             return list.map((p) => (0, hosted_mappers_js_1.positionFromV0)(p));
         }
         try {
@@ -1224,7 +1241,9 @@ class Exchange {
             const route = hosted_routing_js_1.HOSTED_METHOD_ROUTES.get("fetchBalance");
             const path = (0, hosted_routing_js_1.formatRoutePath)(route, { address: resolvedAddress });
             const data = await (0, hosted_routing_js_1._tradingRequest)(this, { method: route.method, path });
-            const list = Array.isArray(data) ? data : [];
+            const list = Array.isArray(data)
+                ? data
+                : (data && Array.isArray(data.balances) ? data.balances : []);
             return list.map((b) => (0, hosted_mappers_js_1.balanceFromV0)(b));
         }
         try {
@@ -3053,6 +3072,18 @@ class Rain extends Exchange {
     }
 }
 exports.Rain = Rain;
+/**
+ * Hunch exchange client.
+ *
+ * Hunch is a crypto-native prediction market. Reads are unauthenticated;
+ * trading requires an EVM private key.
+ */
+class Hunch extends Exchange {
+    constructor(options = {}) {
+        super("hunch", options);
+    }
+}
+exports.Hunch = Hunch;
 /**
  * Mock exchange client.
  *

package/dist/pmxt/escrow.js

@@ -12,6 +12,80 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.Escrow = void 0;
 const hosted_routing_1 = require("./hosted-routing");
+const errors_1 = require("./errors");
+const APPROVAL_TOKENS = new Set(["usdc", "ctf"]);
+const WITHDRAW_ACTIONS = new Set(["request", "claim", "cancel"]);
+const USDC_SCALE = 1000000n;
+function isDecimalTokenId(token) {
+    return /^[0-9]+$/.test(token);
+}
+function normalizeApprovalToken(token) {
+    if (typeof token !== "string") {
+        throw new errors_1.ValidationError("token must be 'usdc', 'ctf', or a decimal CTF token_id string", "token");
+    }
+    const candidate = token.trim();
+    const normalized = candidate.toLowerCase();
+    if (APPROVAL_TOKENS.has(normalized)) {
+        return normalized;
+    }
+    if (isDecimalTokenId(candidate)) {
+        return candidate;
+    }
+    throw new errors_1.ValidationError("token must be 'usdc', 'ctf', or a decimal CTF token_id string", "token");
+}
+function normalizeAmountWei(amountWei) {
+    if (amountWei === undefined) {
+        return undefined;
+    }
+    if (typeof amountWei !== "bigint") {
+        throw new errors_1.ValidationError("amount_wei must be a non-negative integer", "amount_wei");
+    }
+    if (amountWei < 0n) {
+        throw new errors_1.ValidationError("amount_wei must be non-negative", "amount_wei");
+    }
+    return amountWei.toString();
+}
+function validateUsdcDecimal(value, field) {
+    const match = /^([0-9]+)(?:\.([0-9]+))?$/.exec(value);
+    if (!match) {
+        throw new errors_1.ValidationError(`${field} must be a finite positive number`, field);
+    }
+    const fractional = match[2] ?? "";
+    if (fractional.length > 6) {
+        throw new errors_1.ValidationError(`${field} precision exceeds 6 decimals; max precision for USDC is 0.000001`, field);
+    }
+    const scaled = BigInt(match[1]) * USDC_SCALE + BigInt(fractional.padEnd(6, "0"));
+    if (scaled <= 0n) {
+        throw new errors_1.ValidationError(`${field} must be positive`, field);
+    }
+}
+function normalizeUsdcAmount(value, field = "amount") {
+    if (typeof value === "bigint") {
+        if (value <= 0n) {
+            throw new errors_1.ValidationError(`${field} must be positive`, field);
+        }
+        return value.toString();
+    }
+    if (typeof value === "number") {
+        if (!Number.isFinite(value)) {
+            throw new errors_1.ValidationError(`${field} must be a finite positive number`, field);
+        }
+        validateUsdcDecimal(String(value), field);
+        return value;
+    }
+    if (typeof value === "string") {
+        const trimmed = value.trim();
+        validateUsdcDecimal(trimmed, field);
+        return trimmed;
+    }
+    throw new errors_1.ValidationError(`${field} must be a finite positive number`, field);
+}
+function normalizeWithdrawAction(action) {
+    if (typeof action === "string" && WITHDRAW_ACTIONS.has(action)) {
+        return action;
+    }
+    throw new errors_1.ValidationError("action must be 'request', 'claim', or 'cancel'", "action");
+}
 class Escrow {
     client;
     constructor(client) {
@@ -22,13 +96,16 @@ class Escrow {
      * `amountWei` is omitted, the server returns an unlimited approval.
      */
     async approveTx(token, amountWei) {
+        const address = (0, hosted_routing_1.resolveWalletAddress)(this.client);
+        const approvalAmount = normalizeAmountWei(amountWei);
         const route = hosted_routing_1.HOSTED_METHOD_ROUTES.get("escrowApproveTx");
         return (0, hosted_routing_1._tradingRequest)(this.client, {
             method: route.method,
             path: route.path,
             body: {
-                token,
-                amount_wei: amountWei === undefined ? null : amountWei.toString(),
+                token: normalizeApprovalToken(token),
+                user_address: address,
+                ...(approvalAmount === undefined ? {} : { amount_wei: approvalAmount }),
             },
         });
     }
@@ -37,12 +114,15 @@ class Escrow {
      * grid). Accepts number, decimal string, or BigInt in micro-units.
      */
     async depositTx(amount) {
+        const address = (0, hosted_routing_1.resolveWalletAddress)(this.client);
         const route = hosted_routing_1.HOSTED_METHOD_ROUTES.get("escrowDepositTx");
         return (0, hosted_routing_1._tradingRequest)(this.client, {
             method: route.method,
             path: route.path,
             body: {
-                amount: typeof amount === "bigint" ? amount.toString() : amount,
+                token: "usdc",
+                amount: normalizeUsdcAmount(amount),
+                user_address: address,
             },
         });
     }
@@ -52,16 +132,31 @@ class Escrow {
      * the timelock, `cancel` aborts a pending request.
      */
     async withdrawTx(action, amount) {
+        const normalizedAction = normalizeWithdrawAction(action);
+        const address = (0, hosted_routing_1.resolveWalletAddress)(this.client);
         const route = hosted_routing_1.HOSTED_METHOD_ROUTES.get("escrowWithdrawTx");
-        const normalizedAmount = amount === undefined
-            ? null
-            : typeof amount === "bigint"
-                ? amount.toString()
-                : amount;
+        if (normalizedAction === "request") {
+            if (amount === undefined) {
+                throw new errors_1.ValidationError("amount is required when action='request'", "amount");
+            }
+            return (0, hosted_routing_1._tradingRequest)(this.client, {
+                method: route.method,
+                path: route.path,
+                body: {
+                    action: normalizedAction,
+                    token: "usdc",
+                    amount: normalizeUsdcAmount(amount),
+                    user_address: address,
+                },
+            });
+        }
+        if (amount !== undefined) {
+            throw new errors_1.ValidationError(`amount must be omitted when action='${normalizedAction}'`, "amount");
+        }
         return (0, hosted_routing_1._tradingRequest)(this.client, {
             method: route.method,
             path: route.path,
-            body: { action, amount: normalizedAmount },
+            body: { action: normalizedAction, token: "usdc", user_address: address },
         });
     }
     /**
@@ -70,12 +165,16 @@ class Escrow {
      */
     async withdrawals(opts = {}) {
         const address = (0, hosted_routing_1.resolveWalletAddress)(this.client, opts.address);
+        const include = (opts.include ?? "pending,events").trim();
+        if (!include) {
+            throw new errors_1.ValidationError("include must not be empty", "include");
+        }
         const route = hosted_routing_1.HOSTED_METHOD_ROUTES.get("escrowWithdrawals");
         const path = (0, hosted_routing_1.formatRoutePath)(route, { address });
         return (0, hosted_routing_1._tradingRequest)(this.client, {
             method: route.method,
             path,
-            params: { include: opts.include ?? "pending,events" },
+            params: { include },
         });
     }
 }

package/dist/pmxt/server-manager.js

@@ -117,12 +117,14 @@ class ServerManager {
      * Check if the server is running.
      */
     async isServerRunning() {
-        // Read lock file to get current port
-        const port = this.getRunningPort();
+        const info = this.getServerInfo();
+        if (!info?.port) {
+            return false;
+        }
         try {
             // Use native fetch to check health on the actual running port
             // This avoids issues where this.api is configured with the wrong port
-            const response = await fetch(`http://localhost:${port}/health`, {
+            const response = await fetch(`http://localhost:${info.port}/health`, {
                 signal: AbortSignal.timeout(5_000),
             });
             if (response.ok) {

package/generated/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pmxtjs",
-  "version": "2.51.1",
+  "version": "2.51.2",
   "description": "OpenAPI client for pmxtjs",
   "author": "OpenAPI-Generator",
   "repository": {

package/index.ts

@@ -19,14 +19,14 @@
  */
 
 
-import { Exchange, Polymarket, Kalshi, KalshiDemo, Limitless, Myriad, Probable, Baozi, Opinion, Metaculus, Smarkets, PolymarketUS, GeminiTitan, Hyperliquid, SuiBets, Suibets, Rain, Mock } from "./pmxt/client.js";
+import { Exchange, Polymarket, Kalshi, KalshiDemo, Limitless, Myriad, Probable, Baozi, Opinion, Metaculus, Smarkets, PolymarketUS, GeminiTitan, Hyperliquid, SuiBets, Suibets, Rain, Hunch, Mock } from "./pmxt/client.js";
 import { Router } from "./pmxt/router.js";
 import { ServerManager } from "./pmxt/server-manager.js";
 import { FeedClient } from "./pmxt/feed-client.js";
 import * as models from "./pmxt/models.js";
 import * as errors from "./pmxt/errors.js";
 
-export { Exchange, Polymarket, Kalshi, KalshiDemo, Limitless, Myriad, Probable, Baozi, Opinion, Metaculus, Smarkets, PolymarketUS, GeminiTitan, Hyperliquid, SuiBets, Suibets, Rain, Mock, PolymarketOptions } from "./pmxt/client.js";
+export { Exchange, Polymarket, Kalshi, KalshiDemo, Limitless, Myriad, Probable, Baozi, Opinion, Metaculus, Smarkets, PolymarketUS, GeminiTitan, Hyperliquid, SuiBets, Suibets, Rain, Hunch, Mock, PolymarketOptions } from "./pmxt/client.js";
 export { FeedClient } from "./pmxt/feed-client.js";
 export type { Ticker, Tickers, OHLCV, Market as FeedMarket, OracleRound, FeedClientOptions } from "./pmxt/feed-client.js";
 export { Router } from "./pmxt/router.js";
@@ -98,6 +98,7 @@ const pmxt = {
     SuiBets,
     Suibets,
     Rain,
+    Hunch,
     Mock,
     Router,
     ServerManager,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pmxtjs",
-  "version": "2.51.1",
+  "version": "2.51.2",
   "description": "Unified prediction market data API - The ccxt for prediction markets",
   "author": "PMXT Contributors",
   "repository": {
@@ -43,7 +43,7 @@
     "unified"
   ],
   "dependencies": {
-    "pmxt-core": "2.51.1",
+    "pmxt-core": "2.51.2",
     "ws": "^8.18.0"
   },
   "peerDependencies": {

package/pmxt/client.ts

@@ -52,7 +52,7 @@ import {
 import { ServerManager } from "./server-manager.js";
 import { buildArgsWithOptionalOptions } from "./args.js";
 import { PmxtError, fromServerError, InvalidOrder, NotSupported } from "./errors.js";
-import { LOCAL_URL, resolvePmxtBaseUrl } from "./constants.js";
+import { ENV, LOCAL_URL, resolvePmxtBaseUrl } from "./constants.js";
 import { SidecarWsClient } from "./ws-client.js";
 import { logger } from "./logger.js";
 
@@ -351,6 +351,7 @@ export abstract class Exchange {
     private _wsClient: SidecarWsClient | null = null;
     /** Sticky flag: true if the sidecar /ws endpoint is unavailable. */
     private _wsUnsupported: boolean = false;
+    private readonly _useSidecarLockBaseUrl: boolean;
 
     constructor(exchangeName: string, options: ExchangeOptions = {}) {
         this.exchangeName = exchangeName.toLowerCase();
@@ -370,6 +371,11 @@ export abstract class Exchange {
         const baseUrl = resolved.baseUrl;
         this.pmxtApiKey = resolved.pmxtApiKey;
         this.isHosted = resolved.isHosted;
+        const hasBaseUrlOverride = Boolean(
+            options.baseUrl ||
+            (typeof process !== "undefined" && process.env[ENV.BASE_URL]),
+        );
+        this._useSidecarLockBaseUrl = !this.isHosted && !hasBaseUrlOverride;
 
         // Hosted trading bridge: if the caller passed a privateKey but no
         // explicit signer, lazily wrap it in an EthersSigner so that
@@ -417,16 +423,18 @@ export abstract class Exchange {
             try {
                 await this.serverManager.ensureServerRunning();
 
-                // Get the actual port the server is running on
-                // (may differ from default if default port was busy)
-                const actualPort = this.serverManager.getRunningPort();
-                const newBaseUrl = `http://localhost:${actualPort}`;
+                if (this._useSidecarLockBaseUrl) {
+                    // Get the actual port the server is running on
+                    // (may differ from default if default port was busy)
+                    const actualPort = this.serverManager.getRunningPort();
+                    const newBaseUrl = `http://localhost:${actualPort}`;
 
-                // Update API client with actual base URL
-                this.config = new Configuration({
-                    basePath: newBaseUrl,
-                });
-                this.api = new DefaultApi(this.config);
+                    // Update API client with actual base URL
+                    this.config = new Configuration({
+                        basePath: newBaseUrl,
+                    });
+                    this.api = new DefaultApi(this.config);
+                }
             } catch (error) {
                 const msg =
                     `Failed to start PMXT server: ${error instanceof Error ? error.message : error}\n\n` +
@@ -511,12 +519,12 @@ export abstract class Exchange {
     /**
      * Resolve the current sidecar base URL.
      *
-     * For hosted mode the configured basePath is returned as-is.
-     * For local mode the port is re-read from the lock file on every
-     * call so we pick up sidecar restarts that land on a different port.
+     * Hosted mode and explicit baseUrl clients keep the configured basePath.
+     * Default local clients re-read the lock-file port on every call so they
+     * pick up sidecar restarts that land on a different port.
      */
     private resolveBaseUrl(): string {
-        if (this.isHosted) return this.config.basePath;
+        if (this.isHosted || !this._useSidecarLockBaseUrl) return this.config.basePath;
         const port = this.serverManager.getRunningPort();
         return `http://localhost:${port}`;
     }
@@ -1225,7 +1233,10 @@ export abstract class Exchange {
             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>);
+            const payload = data && typeof data === "object" && "order" in data
+                ? (data as { order: unknown }).order
+                : data;
+            return orderFromV0(payload as Record<string, unknown>);
         }
         try {
             const args: any[] = [];
@@ -1325,6 +1336,9 @@ export abstract class Exchange {
 
     async fetchClosedOrders(params?: OrderHistoryParams): Promise<Order[]> {
         await this.initPromise;
+        if (this.isHosted) {
+            throw new NotSupported("fetchClosedOrders is not available in hosted trading mode.");
+        }
         try {
             const args: any[] = [];
             if (params !== undefined) args.push(params);
@@ -1351,6 +1365,9 @@ export abstract class Exchange {
 
     async fetchAllOrders(params?: OrderHistoryParams): Promise<Order[]> {
         await this.initPromise;
+        if (this.isHosted) {
+            throw new NotSupported("fetchAllOrders is not available in hosted trading mode.");
+        }
         try {
             const args: any[] = [];
             if (params !== undefined) args.push(params);
@@ -1382,7 +1399,9 @@ export abstract class Exchange {
             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 : [];
+            const list: unknown[] = Array.isArray(data)
+                ? data
+                : (data && Array.isArray((data as any).positions) ? (data as any).positions : []);
             return list.map((p) => positionFromV0(p as Record<string, unknown>));
         }
         try {
@@ -1416,7 +1435,9 @@ export abstract class Exchange {
             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 : [];
+            const list: unknown[] = Array.isArray(data)
+                ? data
+                : (data && Array.isArray((data as any).balances) ? (data as any).balances : []);
             return list.map((b) => balanceFromV0(b as Record<string, unknown>));
         }
         try {
@@ -3048,6 +3069,16 @@ export interface PolymarketOptions {
 
     /** Optional signature type */
     signatureType?: 'eoa' | 'poly-proxy' | 'gnosis-safe' | number;
+
+    /**
+     * EVM wallet address used for hosted reads/writes.
+     */
+    walletAddress?: string;
+
+    /**
+     * External signer used for hosted writes.
+     */
+    signer?: Signer;
 }
 
 export class Polymarket extends Exchange {
@@ -3402,6 +3433,19 @@ export class Rain extends Exchange {
     }
 }
 
+
+/**
+ * Hunch exchange client.
+ *
+ * Hunch is a crypto-native prediction market. Reads are unauthenticated;
+ * trading requires an EVM private key.
+ */
+export class Hunch extends Exchange {
+    constructor(options: ExchangeOptions = {}) {
+        super("hunch", options);
+    }
+}
+
 /**
  * Mock exchange client.
  *

package/pmxt/escrow.ts

@@ -16,6 +16,99 @@ import {
     HostedClientLike,
     resolveWalletAddress,
 } from "./hosted-routing";
+import { ValidationError } from "./errors";
+
+const APPROVAL_TOKENS = new Set(["usdc", "ctf"]);
+const WITHDRAW_ACTIONS = new Set(["request", "claim", "cancel"]);
+const USDC_SCALE = 1_000_000n;
+
+function isDecimalTokenId(token: string): boolean {
+    return /^[0-9]+$/.test(token);
+}
+
+function normalizeApprovalToken(token: string): string {
+    if (typeof token !== "string") {
+        throw new ValidationError(
+            "token must be 'usdc', 'ctf', or a decimal CTF token_id string",
+            "token",
+        );
+    }
+
+    const candidate = token.trim();
+    const normalized = candidate.toLowerCase();
+    if (APPROVAL_TOKENS.has(normalized)) {
+        return normalized;
+    }
+    if (isDecimalTokenId(candidate)) {
+        return candidate;
+    }
+    throw new ValidationError(
+        "token must be 'usdc', 'ctf', or a decimal CTF token_id string",
+        "token",
+    );
+}
+
+function normalizeAmountWei(amountWei: bigint | undefined): string | undefined {
+    if (amountWei === undefined) {
+        return undefined;
+    }
+    if (typeof amountWei !== "bigint") {
+        throw new ValidationError("amount_wei must be a non-negative integer", "amount_wei");
+    }
+    if (amountWei < 0n) {
+        throw new ValidationError("amount_wei must be non-negative", "amount_wei");
+    }
+    return amountWei.toString();
+}
+
+function validateUsdcDecimal(value: string, field: string): void {
+    const match = /^([0-9]+)(?:\.([0-9]+))?$/.exec(value);
+    if (!match) {
+        throw new ValidationError(`${field} must be a finite positive number`, field);
+    }
+
+    const fractional = match[2] ?? "";
+    if (fractional.length > 6) {
+        throw new ValidationError(
+            `${field} precision exceeds 6 decimals; max precision for USDC is 0.000001`,
+            field,
+        );
+    }
+
+    const scaled = BigInt(match[1]) * USDC_SCALE + BigInt(fractional.padEnd(6, "0"));
+    if (scaled <= 0n) {
+        throw new ValidationError(`${field} must be positive`, field);
+    }
+}
+
+function normalizeUsdcAmount(value: number | string | bigint, field: string = "amount"): number | string {
+    if (typeof value === "bigint") {
+        if (value <= 0n) {
+            throw new ValidationError(`${field} must be positive`, field);
+        }
+        return value.toString();
+    }
+    if (typeof value === "number") {
+        if (!Number.isFinite(value)) {
+            throw new ValidationError(`${field} must be a finite positive number`, field);
+        }
+        validateUsdcDecimal(String(value), field);
+        return value;
+    }
+    if (typeof value === "string") {
+        const trimmed = value.trim();
+        validateUsdcDecimal(trimmed, field);
+        return trimmed;
+    }
+    throw new ValidationError(`${field} must be a finite positive number`, field);
+}
+
+function normalizeWithdrawAction(action: string): "request" | "claim" | "cancel" {
+    if (typeof action === "string" && WITHDRAW_ACTIONS.has(action)) {
+        return action as "request" | "claim" | "cancel";
+    }
+    throw new ValidationError("action must be 'request', 'claim', or 'cancel'", "action");
+}
 
 export class Escrow {
     constructor(private readonly client: HostedClientLike) {}
@@ -25,13 +118,16 @@ export class Escrow {
      * `amountWei` is omitted, the server returns an unlimited approval.
      */
     async approveTx(token: string, amountWei?: bigint): Promise<unknown> {
+        const address = resolveWalletAddress(this.client);
+        const approvalAmount = normalizeAmountWei(amountWei);
         const route = HOSTED_METHOD_ROUTES.get("escrowApproveTx")!;
         return _tradingRequest(this.client, {
             method: route.method,
             path: route.path,
             body: {
-                token,
-                amount_wei: amountWei === undefined ? null : amountWei.toString(),
+                token: normalizeApprovalToken(token),
+                user_address: address,
+                ...(approvalAmount === undefined ? {} : { amount_wei: approvalAmount }),
             },
         });
     }
@@ -41,12 +137,15 @@ export class Escrow {
      * grid). Accepts number, decimal string, or BigInt in micro-units.
      */
     async depositTx(amount: number | string | bigint): Promise<unknown> {
+        const address = resolveWalletAddress(this.client);
         const route = HOSTED_METHOD_ROUTES.get("escrowDepositTx")!;
         return _tradingRequest(this.client, {
             method: route.method,
             path: route.path,
             body: {
-                amount: typeof amount === "bigint" ? amount.toString() : amount,
+                token: "usdc",
+                amount: normalizeUsdcAmount(amount),
+                user_address: address,
             },
         });
     }
@@ -60,17 +159,34 @@ export class Escrow {
         action: "request" | "claim" | "cancel",
         amount?: number | string | bigint,
     ): Promise<unknown> {
+        const normalizedAction = normalizeWithdrawAction(action);
+        const address = resolveWalletAddress(this.client);
         const route = HOSTED_METHOD_ROUTES.get("escrowWithdrawTx")!;
-        const normalizedAmount =
-            amount === undefined
-                ? null
-                : typeof amount === "bigint"
-                  ? amount.toString()
-                  : amount;
+        if (normalizedAction === "request") {
+            if (amount === undefined) {
+                throw new ValidationError("amount is required when action='request'", "amount");
+            }
+            return _tradingRequest(this.client, {
+                method: route.method,
+                path: route.path,
+                body: {
+                    action: normalizedAction,
+                    token: "usdc",
+                    amount: normalizeUsdcAmount(amount),
+                    user_address: address,
+                },
+            });
+        }
+        if (amount !== undefined) {
+            throw new ValidationError(
+                `amount must be omitted when action='${normalizedAction}'`,
+                "amount",
+            );
+        }
         return _tradingRequest(this.client, {
             method: route.method,
             path: route.path,
-            body: { action, amount: normalizedAmount },
+            body: { action: normalizedAction, token: "usdc", user_address: address },
         });
     }
 
@@ -82,12 +198,16 @@ export class Escrow {
         opts: { include?: string; address?: string } = {},
     ): Promise<unknown> {
         const address = resolveWalletAddress(this.client, opts.address);
+        const include = (opts.include ?? "pending,events").trim();
+        if (!include) {
+            throw new ValidationError("include must not be empty", "include");
+        }
         const route = HOSTED_METHOD_ROUTES.get("escrowWithdrawals")!;
         const path = formatRoutePath(route, { address });
         return _tradingRequest(this.client, {
             method: route.method,
             path,
-            params: { include: opts.include ?? "pending,events" },
+            params: { include },
         });
     }
 }

package/pmxt/server-manager.ts

@@ -103,13 +103,15 @@ export class ServerManager {
      * Check if the server is running.
      */
     async isServerRunning(): Promise<boolean> {
-        // Read lock file to get current port
-        const port = this.getRunningPort();
+        const info = this.getServerInfo();
+        if (!info?.port) {
+            return false;
+        }
 
         try {
             // Use native fetch to check health on the actual running port
             // This avoids issues where this.api is configured with the wrong port
-            const response = await fetch(`http://localhost:${port}/health`, {
+            const response = await fetch(`http://localhost:${info.port}/health`, {
                 signal: AbortSignal.timeout(5_000),
             });
             if (response.ok) {