pmxtjs 2.51.1 → 2.51.3

package/pmxt/client.ts

@@ -17,7 +17,7 @@ import {
 import {
     Balance,
     BuiltOrder,
-    CreateOrderParams,
+    CreateOrderInput,
     EventFetchParams,
     EventFilterCriteria,
     EventFilterFunction,
@@ -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";
 
@@ -82,6 +82,7 @@ import {
     validateEconomics,
     verifySignature,
 } from "./hosted-typed-data.js";
+import type { HostedRoute } from "./hosted-typed-data.js";
 import type { Signer, TypedData } from "./signers.js";
 import { signerFromPrivateKey, EthersSigner } from "./signers.js";
 import { Escrow } from "./escrow.js";
@@ -351,6 +352,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 +372,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 +424,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 +520,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 +1234,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 +1337,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 +1366,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 +1400,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 +1436,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 {
@@ -1990,7 +2012,13 @@ export abstract class Exchange {
         throw this.wsTransportUnavailableError("watchAllOrderBooks");
     }
 
-    /** @deprecated Use {@link watchAllOrderBooks} instead. */
+    /**
+     * Stream all orderbook updates across venues.
+     *
+     * @deprecated Use {@link watchAllOrderBooks} instead.
+     * @param venues - Optional venue filter
+     * @returns Next event with source, symbol, and orderbook
+     */
     async firehose(venues?: string[]): Promise<FirehoseEvent> {
         return this.watchAllOrderBooks(venues);
     }
@@ -2127,15 +2155,18 @@ export abstract class Exchange {
      * const order = await exchange.submitOrder(built);
      *
      * // Using outcome shorthand:
+     * const yes = market.yes;
+     * if (!yes) throw new Error("Market has no YES outcome");
+     *
      * const built2 = await exchange.buildOrder({
-     *   outcome: market.yes,
+     *   outcome: yes,
      *   side: "buy",
      *   type: "market",
      *   amount: 10
      * });
      * ```
      */
-    async buildOrder(params: CreateOrderParams & { outcome?: MarketOutcome }): Promise<BuiltOrder> {
+    async buildOrder(params: CreateOrderInput): Promise<BuiltOrder> {
         if (this.isHostedTradingMode()) {
             return this._hostedBuildOrder(params);
         }
@@ -2289,7 +2320,7 @@ export abstract class Exchange {
      * at submit time.
      */
     private async _hostedBuildOrder(
-        params: CreateOrderParams & { outcome?: MarketOutcome },
+        params: CreateOrderInput,
     ): Promise<BuiltOrder> {
         const body = this._hostedBuildOrderBody(params);
         const route = HOSTED_METHOD_ROUTES.get("buildOrder")!;
@@ -2307,7 +2338,7 @@ export abstract class Exchange {
     /**
      * Hosted-mode createOrder: build → sign → submit single-call wrapper.
      */
-    private async _hostedCreateOrder(params: any): Promise<Order> {
+    private async _hostedCreateOrder(params: CreateOrderInput): Promise<Order> {
         const built = await this._hostedBuildOrder(params);
         return this._hostedSubmitOrder(built);
     }
@@ -2371,7 +2402,7 @@ export abstract class Exchange {
      * `validateTypedData` / `validateEconomics`. Returns the cross-chain
      * pull-leg route name for Opinion sells and Limitless cross-chain orders.
      */
-    private _hostedTypedDataRoute(side: string, isPull: boolean): string {
+    private _hostedTypedDataRoute(side: string, isPull: boolean): HostedRoute {
         const venue = this.exchangeName;
         const sideLower = side.toLowerCase();
         if (venue === "polymarket") {
@@ -2436,10 +2467,12 @@ export abstract class Exchange {
         return orderFromV0(data as Record<string, unknown>);
     }
 
-    private _hostedCancelTypedDataRoute(isPull: boolean): string {
+    private _hostedCancelTypedDataRoute(isPull: boolean): HostedRoute {
         const venue = this.exchangeName;
         if (venue === "polymarket") return "cancel_polymarket";
-        if (venue === "limitless") return isPull ? "cancel_limitless_base_pull" : "cancel_limitless_polygon";
+        if (venue === "limitless") {
+            return isPull ? "cancel_limitless_base_pull" : "cancel_limitless_polygon";
+        }
         return isPull ? "cancel_opinion_bsc_pull" : "cancel_opinion_polygon";
     }
 
@@ -2449,7 +2482,7 @@ export abstract class Exchange {
      * precision rejected via {@link to6dec}).
      */
     private _hostedBuildOrderBody(
-        params: CreateOrderParams & { outcome?: MarketOutcome },
+        params: CreateOrderInput,
     ): Record<string, unknown> {
         let marketId: string | undefined = params.marketId;
         let outcomeId: string | undefined = params.outcomeId;
@@ -2571,7 +2604,7 @@ export abstract class Exchange {
      * });
      * ```
      */
-    async createOrder(params: CreateOrderParams & { outcome?: MarketOutcome }): Promise<Order> {
+    async createOrder(params: CreateOrderInput): Promise<Order> {
         // SOR escape path (preserved): legacy hosted SOR flow uses a venue-side
         // SDK to execute the legs, only when a privateKey is present.
         if (this.isHosted && this.exchangeName === 'sor' && this.privateKey) {
@@ -3048,6 +3081,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 {
@@ -3122,6 +3165,75 @@ export class Limitless extends Exchange {
     constructor(options: ExchangeOptions = {}) {
         super("limitless", options);
     }
+
+    /**
+     * Watch real-time AMM price updates via WebSocket.
+     *
+     * @param marketAddress - Limitless market contract address
+     * @param callback - Optional callback invoked with the returned update
+     * @returns Next price update
+     */
+    async watchPrices(
+        marketAddress: string,
+        callback?: (data: Record<string, any>) => void,
+    ): Promise<Record<string, any>> {
+        await this.initPromise;
+        try {
+            const json = await this.sidecarPostRequest("watchPrices", [marketAddress]);
+            const data = this.handleResponse(json);
+            callback?.(data);
+            return data;
+        } catch (error) {
+            if (error instanceof PmxtError) throw error;
+            throw new PmxtError(`Failed to watch prices: ${error}`);
+        }
+    }
+
+    /**
+     * Watch real-time Limitless user position updates.
+     *
+     * Requires API key authentication.
+     *
+     * @param callback - Optional callback invoked with the returned positions
+     * @returns Next position update payload
+     */
+    async watchUserPositions(
+        callback?: (data: Position[]) => void,
+    ): Promise<Position[]> {
+        await this.initPromise;
+        try {
+            const json = await this.sidecarPostRequest("watchUserPositions", []);
+            const data = this.handleResponse(json).map(convertPosition);
+            callback?.(data);
+            return data;
+        } catch (error) {
+            if (error instanceof PmxtError) throw error;
+            throw new PmxtError(`Failed to watch user positions: ${error}`);
+        }
+    }
+
+    /**
+     * Watch real-time Limitless user transaction updates.
+     *
+     * Requires API key authentication.
+     *
+     * @param callback - Optional callback invoked with the returned update
+     * @returns Next transaction update
+     */
+    async watchUserTransactions(
+        callback?: (data: Record<string, any>) => void,
+    ): Promise<Record<string, any>> {
+        await this.initPromise;
+        try {
+            const json = await this.sidecarPostRequest("watchUserTransactions", []);
+            const data = this.handleResponse(json);
+            callback?.(data);
+            return data;
+        } catch (error) {
+            if (error instanceof PmxtError) throw error;
+            throw new PmxtError(`Failed to watch user transactions: ${error}`);
+        }
+    }
 }
 
 /**
@@ -3402,6 +3514,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/hosted-typed-data.ts

@@ -141,7 +141,9 @@ export type HostedRoute =
     | "opinion_sell_bsc_pull"
     | "cancel_polymarket"
     | "cancel_opinion_polygon"
-    | "cancel_opinion_bsc_pull";
+    | "cancel_opinion_bsc_pull"
+    | "cancel_limitless_polygon"
+    | "cancel_limitless_base_pull";
 
 const SCHEMAS: Readonly<Record<HostedRoute, TypedDataSchema>> = {
     polymarket_buy: {
@@ -221,6 +223,20 @@ const SCHEMAS: Readonly<Record<HostedRoute, TypedDataSchema>> = {
         messageKeys: messageKeysFromFields(CANCEL_PULL_FIELDS),
         walletField: "user",
     },
+    cancel_limitless_polygon: {
+        primaryType: "CancelOrder",
+        domain: PREFUNDED_DOMAIN,
+        fields: CANCEL_ORDER_FIELDS,
+        messageKeys: messageKeysFromFields(CANCEL_ORDER_FIELDS),
+        walletField: "user",
+    },
+    cancel_limitless_base_pull: {
+        primaryType: "CancelPull",
+        domain: LIMITLESS_VENUE_DOMAIN,
+        fields: CANCEL_PULL_FIELDS,
+        messageKeys: messageKeysFromFields(CANCEL_PULL_FIELDS),
+        walletField: "user",
+    },
 };
 
 // secp256k1 group order / 2, for canonical low-s check.

package/pmxt/models.ts

@@ -549,6 +549,12 @@ export interface CreateOrderParams {
     /** Limit price (required for limit orders, 0.0-1.0) */
     price?: number;
 
+    /** Hosted mode: unit that amount is denominated in. Market buys use usdc; market sells and limit orders use shares. */
+    denom?: "usdc" | "shares";
+
+    /** Hosted mode: maximum slippage percentage for market orders. */
+    slippage_pct?: number;
+
     /** Optional fee rate (e.g., 1000 for 0.1%) */
     fee?: number;
 
@@ -562,6 +568,20 @@ export interface CreateOrderParams {
     onBehalfOf?: number;
 }
 
+/**
+ * Public order input accepted by createOrder/buildOrder.
+ *
+ * Callers can either pass explicit marketId/outcomeId fields, or pass an
+ * outcome object returned by fetchMarkets and let the SDK infer those ids.
+ */
+export type CreateOrderInput =
+    | (CreateOrderParams & { outcome?: never })
+    | (Omit<CreateOrderParams, 'marketId' | 'outcomeId'> & {
+        outcome: MarketOutcome;
+        marketId?: never;
+        outcomeId?: never;
+    });
+
 /** Alias matching the core MarketFetchParams name. */
 export type MarketFetchParams = MarketFilterParams;
 

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) {