pmxtjs 2.19.6 → 2.20.0

package/pmxt/client.ts

@@ -6,37 +6,43 @@
  */
 
 import {
-    DefaultApi,
     Configuration,
-    FetchOHLCVRequest,
-    FetchTradesRequest,
     CreateOrderRequest,
+    DefaultApi,
     ExchangeCredentials,
+    FetchOHLCVRequest,
+    FetchTradesRequest,
+    BuildOrderRequest,
+    SubmitOrderRequest,
 } from "../generated/src/index.js";
 
 import {
-    UnifiedMarket,
-    MarketOutcome,
+    Balance,
+    BuiltOrder,
+    CreateOrderParams,
+    EventFilterCriteria,
+    EventFilterFunction,
+    ExecutionPriceResult,
+    MarketFilterCriteria,
+    MarketFilterFunction,
     MarketList,
-    PriceCandle,
+    MarketOutcome,
+    Order,
     OrderBook,
     OrderLevel,
-    Trade,
-    UserTrade,
-    Order,
+    PaginatedMarketsResult,
     Position,
-    Balance,
-    SearchIn,
+    PriceCandle,
+    SubscribedAddressSnapshot,
+    SubscriptionOption,
+    Trade,
     UnifiedEvent,
-    ExecutionPriceResult,
-    PaginatedMarketsResult,
-    MarketFilterCriteria,
-    MarketFilterFunction,
-    EventFilterCriteria,
-    EventFilterFunction,
+    UnifiedMarket,
+    UserTrade,
 } from "./models.js";
 
 import { ServerManager } from "./server-manager.js";
+import { buildArgsWithOptionalOptions } from "./args.js";
 
 // Converter functions
 function convertMarket(raw: any): UnifiedMarket {
@@ -190,6 +196,22 @@ function convertEvent(raw: any): UnifiedEvent {
     return event;
 }
 
+
+function convertSubscriptionSnapshot(raw: any): SubscribedAddressSnapshot {
+    const trades = (raw.trades?? []).map(convertTrade);
+    const balances = (raw.balances?? []).map(convertBalance);
+    const positions = (raw.positions?? []).map(convertPosition);
+
+    const snapShot: SubscribedAddressSnapshot = {
+      address: raw.address,
+      trades,
+      balances,
+      positions,
+      timestamp: raw.timestamp,
+    };
+    return snapShot;
+}
+
 /**
  * Base exchange client options.
  */
@@ -384,8 +406,7 @@ export abstract class Exchange {
     async fetchMarkets(params?: any): Promise<UnifiedMarket[]> {
         await this.initPromise;
         try {
-            const args: any[] = [];
-            if (params !== undefined) args.push(params);
+            const args = buildArgsWithOptionalOptions(params);
             const response = await fetch(`${this.config.basePath}/api/${this.exchangeName}/fetchMarkets`, {
                 method: 'POST',
                 headers: { 'Content-Type': 'application/json', ...this.getAuthHeaders() },
@@ -406,8 +427,7 @@ export abstract class Exchange {
     async fetchMarketsPaginated(params?: any): Promise<PaginatedMarketsResult> {
         await this.initPromise;
         try {
-            const args: any[] = [];
-            if (params !== undefined) args.push(params);
+            const args = buildArgsWithOptionalOptions(params);
             const response = await fetch(`${this.config.basePath}/api/${this.exchangeName}/fetchMarketsPaginated`, {
                 method: 'POST',
                 headers: { 'Content-Type': 'application/json', ...this.getAuthHeaders() },
@@ -432,8 +452,7 @@ export abstract class Exchange {
     async fetchEvents(params?: any): Promise<UnifiedEvent[]> {
         await this.initPromise;
         try {
-            const args: any[] = [];
-            if (params !== undefined) args.push(params);
+            const args = buildArgsWithOptionalOptions(params);
             const response = await fetch(`${this.config.basePath}/api/${this.exchangeName}/fetchEvents`, {
                 method: 'POST',
                 headers: { 'Content-Type': 'application/json', ...this.getAuthHeaders() },
@@ -454,8 +473,7 @@ export abstract class Exchange {
     async fetchMarket(params?: any): Promise<UnifiedMarket> {
         await this.initPromise;
         try {
-            const args: any[] = [];
-            if (params !== undefined) args.push(params);
+            const args = buildArgsWithOptionalOptions(params);
             const response = await fetch(`${this.config.basePath}/api/${this.exchangeName}/fetchMarket`, {
                 method: 'POST',
                 headers: { 'Content-Type': 'application/json', ...this.getAuthHeaders() },
@@ -476,8 +494,7 @@ export abstract class Exchange {
     async fetchEvent(params?: any): Promise<UnifiedEvent> {
         await this.initPromise;
         try {
-            const args: any[] = [];
-            if (params !== undefined) args.push(params);
+            const args = buildArgsWithOptionalOptions(params);
             const response = await fetch(`${this.config.basePath}/api/${this.exchangeName}/fetchEvent`, {
                 method: 'POST',
                 headers: { 'Content-Type': 'application/json', ...this.getAuthHeaders() },
@@ -517,27 +534,6 @@ export abstract class Exchange {
         }
     }
 
-    async submitOrder(built: any): Promise<Order> {
-        await this.initPromise;
-        try {
-            const args: any[] = [];
-            args.push(built);
-            const response = await fetch(`${this.config.basePath}/api/${this.exchangeName}/submitOrder`, {
-                method: 'POST',
-                headers: { 'Content-Type': 'application/json', ...this.getAuthHeaders() },
-                body: JSON.stringify({ args, credentials: this.getCredentials() }),
-            });
-            if (!response.ok) {
-                const error = await response.json().catch(() => ({}));
-                throw new Error(error.error?.message || response.statusText);
-            }
-            const json = await response.json();
-            const data = this.handleResponse(json);
-            return convertOrder(data);
-        } catch (error) {
-            throw new Error(`Failed to submitOrder: ${error}`);
-        }
-    }
 
     async cancelOrder(orderId: string): Promise<Order> {
         await this.initPromise;
@@ -586,8 +582,7 @@ export abstract class Exchange {
     async fetchOpenOrders(marketId?: string): Promise<Order[]> {
         await this.initPromise;
         try {
-            const args: any[] = [];
-            if (marketId !== undefined) args.push(marketId);
+            const args = buildArgsWithOptionalOptions(marketId);
             const response = await fetch(`${this.config.basePath}/api/${this.exchangeName}/fetchOpenOrders`, {
                 method: 'POST',
                 headers: { 'Content-Type': 'application/json', ...this.getAuthHeaders() },
@@ -608,8 +603,7 @@ export abstract class Exchange {
     async fetchMyTrades(params?: any): Promise<UserTrade[]> {
         await this.initPromise;
         try {
-            const args: any[] = [];
-            if (params !== undefined) args.push(params);
+            const args = buildArgsWithOptionalOptions(params);
             const response = await fetch(`${this.config.basePath}/api/${this.exchangeName}/fetchMyTrades`, {
                 method: 'POST',
                 headers: { 'Content-Type': 'application/json', ...this.getAuthHeaders() },
@@ -630,8 +624,7 @@ export abstract class Exchange {
     async fetchClosedOrders(params?: any): Promise<Order[]> {
         await this.initPromise;
         try {
-            const args: any[] = [];
-            if (params !== undefined) args.push(params);
+            const args = buildArgsWithOptionalOptions(params);
             const response = await fetch(`${this.config.basePath}/api/${this.exchangeName}/fetchClosedOrders`, {
                 method: 'POST',
                 headers: { 'Content-Type': 'application/json', ...this.getAuthHeaders() },
@@ -652,8 +645,7 @@ export abstract class Exchange {
     async fetchAllOrders(params?: any): Promise<Order[]> {
         await this.initPromise;
         try {
-            const args: any[] = [];
-            if (params !== undefined) args.push(params);
+            const args = buildArgsWithOptionalOptions(params);
             const response = await fetch(`${this.config.basePath}/api/${this.exchangeName}/fetchAllOrders`, {
                 method: 'POST',
                 headers: { 'Content-Type': 'application/json', ...this.getAuthHeaders() },
@@ -671,10 +663,10 @@ export abstract class Exchange {
         }
     }
 
-    async fetchPositions(): Promise<Position[]> {
+    async fetchPositions(address?: string): Promise<Position[]> {
         await this.initPromise;
         try {
-            const args: any[] = [];
+            const args: any[] = address? [address] : [];
             const response = await fetch(`${this.config.basePath}/api/${this.exchangeName}/fetchPositions`, {
                 method: 'POST',
                 headers: { 'Content-Type': 'application/json', ...this.getAuthHeaders() },
@@ -692,10 +684,10 @@ export abstract class Exchange {
         }
     }
 
-    async fetchBalance(): Promise<Balance[]> {
+    async fetchBalance(address?: string): Promise<Balance[]> {
         await this.initPromise;
         try {
-            const args: any[] = [];
+            const args: any[] = address? [address] : [];
             const response = await fetch(`${this.config.basePath}/api/${this.exchangeName}/fetchBalance`, {
                 method: 'POST',
                 headers: { 'Content-Type': 'application/json', ...this.getAuthHeaders() },
@@ -877,6 +869,7 @@ export abstract class Exchange {
      * Call repeatedly in a loop to stream updates (CCXT Pro pattern).
      * 
      * @param outcomeId - Outcome ID to watch
+     * @param address - Public wallet to be watched
      * @param since - Optional timestamp to filter trades from
      * @param limit - Optional limit for number of trades
      * @returns Next trade update(s)
@@ -894,12 +887,16 @@ export abstract class Exchange {
      */
     async watchTrades(
         outcomeId: string,
+        address?: string,
         since?: number,
         limit?: number
     ): Promise<Trade[]> {
         await this.initPromise;
         try {
             const args: any[] = [outcomeId];
+            if (address !== undefined) {
+                args.push(address);
+            }
             if (since !== undefined) {
                 args.push(since);
             }
@@ -924,8 +921,213 @@ export abstract class Exchange {
         }
     }
 
+    /**
+     * Watch real-time updates of a public wallet via WebSocket.
+     *
+     * Returns a promise that resolves with the next update(s).
+     * Call repeatedly in a loop to stream updates (CCXT Pro pattern).
+     *
+     * @param address - Public wallet to be watched
+     * @param types - Subscription options including 'trades', 'positions', and 'balances'
+     * @returns Next update(s)
+     *
+     * @example
+     * ```typescript
+     * // Stream updates of a public wallet address
+     * while (true) {
+     *   const snapshots = await exchange.watchAddress(address, types);
+     *   for (const snapshot of snapshots) {
+     *     console.log(`Trade: ${snapshot.trades}`);
+     *   }
+     * }
+     * ```
+     */
+    async watchAddress(
+        address: string,
+        types?: SubscriptionOption[],
+    ): Promise<SubscribedAddressSnapshot> {
+        await this.initPromise;
+        try {
+            const args: any[] = [address];
+            if (types !== undefined) {
+                args.push(types);
+            }
+            const requestBody: any = {
+                args,
+                credentials: this.getCredentials()
+            };
+
+            const response = await this.api.watchAddress({
+                exchange: this.exchangeName as any,
+                watchAddressRequest: requestBody,
+            });
+
+            const data = this.handleResponse(response);
+            return convertSubscriptionSnapshot(data);
+        } catch (error) {
+            throw new Error(`Failed to watch address: ${error}`);
+        }
+    }
+
+    /**
+     * Stop watching a previously registered wallet address and release its resource updates.
+     *
+     * @param address - Public wallet to be watched
+     * @returns
+     */
+    async unwatchAddress(
+        address: string,
+    ): Promise<Trade[]> {
+        await this.initPromise;
+        try {
+            const args: any[] = [address];
+
+            const requestBody: any = {
+                args,
+                credentials: this.getCredentials()
+            };
+
+            const response = await this.api.unwatchAddress({
+                exchange: this.exchangeName as any,
+                unwatchAddressRequest: requestBody,
+            });
+
+            return this.handleResponse(response);
+        } catch (error) {
+            throw new Error(`Failed to unwatch address: ${error}`);
+        }
+    }
+
     // Trading Methods (require authentication)
 
+    /**
+     * Build an order payload without submitting it to the exchange.
+     * Returns the exchange-native signed order or transaction payload for
+     * inspection, forwarding through a middleware layer, or deferred
+     * submission via {@link submitOrder}.
+     *
+     * You can specify the market either with explicit marketId/outcomeId,
+     * or by passing an outcome object directly (e.g., market.yes).
+     *
+     * @param params - Order parameters (same as createOrder)
+     * @returns A BuiltOrder containing the exchange-native payload
+     *
+     * @example
+     * ```typescript
+     * // Build, inspect, then submit:
+     * const built = await exchange.buildOrder({
+     *   marketId: "663583",
+     *   outcomeId: "10991849...",
+     *   side: "buy",
+     *   type: "limit",
+     *   amount: 10,
+     *   price: 0.55
+     * });
+     *
+     * console.log(built.signedOrder); // inspect before submitting
+     * const order = await exchange.submitOrder(built);
+     *
+     * // Using outcome shorthand:
+     * const built2 = await exchange.buildOrder({
+     *   outcome: market.yes,
+     *   side: "buy",
+     *   type: "market",
+     *   amount: 10
+     * });
+     * ```
+     */
+    async buildOrder(params: CreateOrderParams & { outcome?: MarketOutcome }): Promise<BuiltOrder> {
+        await this.initPromise;
+        try {
+            let marketId = params.marketId;
+            let outcomeId = params.outcomeId;
+
+            if (params.outcome) {
+                if (marketId !== undefined || outcomeId !== undefined) {
+                    throw new Error(
+                        "Cannot specify both 'outcome' and 'marketId'/'outcomeId'. Use one or the other."
+                    );
+                }
+                const outcome: MarketOutcome = params.outcome;
+                if (!outcome.marketId) {
+                    throw new Error(
+                        "outcome.marketId is not set. Ensure the outcome comes from a fetched market."
+                    );
+                }
+                marketId = outcome.marketId;
+                outcomeId = outcome.outcomeId;
+            }
+
+            const paramsDict: any = {
+                marketId,
+                outcomeId,
+                side: params.side,
+                type: params.type,
+                amount: params.amount,
+            };
+            if (params.price !== undefined) {
+                paramsDict.price = params.price;
+            }
+            if (params.fee !== undefined) {
+                paramsDict.fee = params.fee;
+            }
+
+            const requestBody: BuildOrderRequest = {
+                args: [paramsDict],
+                credentials: this.getCredentials()
+            };
+
+            const response = await this.api.buildOrder({
+                exchange: this.exchangeName as any,
+                buildOrderRequest: requestBody,
+            });
+
+            const data = this.handleResponse(response);
+            return data as BuiltOrder;
+        } catch (error) {
+            throw new Error(`Failed to build order: ${error}`);
+        }
+    }
+
+    /**
+     * Submit a pre-built order returned by {@link buildOrder}.
+     *
+     * @param built - The BuiltOrder payload from buildOrder()
+     * @returns The submitted order
+     *
+     * @example
+     * ```typescript
+     * const built = await exchange.buildOrder({
+     *   outcome: market.yes,
+     *   side: "buy",
+     *   type: "limit",
+     *   amount: 10,
+     *   price: 0.55
+     * });
+     * const order = await exchange.submitOrder(built);
+     * console.log(order.id, order.status);
+     * ```
+     */
+    async submitOrder(built: BuiltOrder): Promise<Order> {
+        await this.initPromise;
+        try {
+            const requestBody: SubmitOrderRequest = {
+                args: [built as any],
+                credentials: this.getCredentials()
+            };
+
+            const response = await this.api.submitOrder({
+                exchange: this.exchangeName as any,
+                submitOrderRequest: requestBody,
+            });
+
+            const data = this.handleResponse(response);
+            return convertOrder(data);
+        } catch (error) {
+            throw new Error(`Failed to submit order: ${error}`);
+        }
+    }
+
     /**
      * Create a new order.
      * 

package/pmxt/models.ts

@@ -1,6 +1,6 @@
 /**
  * Data models for PMXT TypeScript SDK.
- * 
+ *
  * These are clean TypeScript interfaces that provide a user-friendly API.
  */
 
@@ -368,6 +368,29 @@ export interface CreateOrderParams {
     /** Optional fee rate (e.g., 1000 for 0.1%) */
     fee?: number;
 }
+
+/**
+ * An order payload built but not yet submitted to the exchange.
+ */
+export interface BuiltOrder {
+    /** The exchange name this order was built for. */
+    exchange: string;
+    /** The original params used to build this order. */
+    params: CreateOrderParams;
+    /** For CLOB exchanges (Polymarket): the EIP-712 signed order. */
+    signedOrder?: Record<string, unknown>;
+    /** For on-chain AMM exchanges: the EVM transaction payload. */
+    tx?: {
+        to: string;
+        data: string;
+        value: string;
+        chainId: number;
+    };
+    /** The raw, exchange-native payload. Always present. */
+    raw: unknown;
+}
+
+
 /**
  * A list of UnifiedMarket objects with a convenience match() method.
  * Extends Array so all standard array operations work unchanged.
@@ -545,3 +568,34 @@ export interface EventFilterCriteria {
  * Function type for custom event filtering logic.
  */
 export type EventFilterFunction = (event: UnifiedEvent) => boolean;
+
+/**
+ * Subscription options.
+ */
+export type SubscriptionOption = 'trades' | 'positions' | 'balances';
+
+/**
+ * Subscription snapshot of a watched public wallet address.
+ */
+export interface SubscribedAddressSnapshot {
+    /** The wallet address being watched */
+    address: string;
+
+    /** Recent trades for this address
+     * (if the above SubscriptionOption 'trades' option was requested)
+     */
+    trades?: Trade[];
+
+    /** Current open positions for this address
+     * (if the above SubscriptionOption 'positions' option was requested)
+     */
+    positions?: Position[];
+
+    /** Current balances for this address
+     * (if the above SubscriptionOption 'balances' option was requested)
+     */
+    balances?: Balance[];
+
+    /** Unix timestamp (ms) of this snapshot */
+    timestamp: number;
+}