pmxtjs 2.48.6 → 2.49.0

package/dist/esm/pmxt/hosted-mappers.js

@@ -0,0 +1,291 @@
+/**
+ * Hosted trading v0 response mappers.
+ *
+ * The hosted trading API exposes explicit `/v0/*` JSON shapes. These helpers
+ * translate those wire dictionaries to the SDK TypeScript interfaces.
+ *
+ * Mirrors `sdks/python/pmxt/_hosted_mappers.py`.
+ */
+import { InvalidOrder } from "./errors.js";
+// ---------------------------------------------------------------------------
+// Precision helper
+// ---------------------------------------------------------------------------
+const SIX_DEC_SCALE = 1000000n;
+/**
+ * Convert a decimal amount to integer micro-units (6-decimal grid).
+ *
+ * Rejects amounts whose fractional part has more than 6 digits. Pure integer
+ * math via BigInt — no float rounding involved.
+ */
+export function to6dec(amount) {
+    const str = typeof amount === "bigint" ? `${amount}` : String(amount);
+    const negative = str.startsWith("-");
+    const cleaned = negative ? str.slice(1) : str;
+    const [intPart, fracPart = ""] = cleaned.split(".");
+    if (fracPart.length > 6) {
+        throw new InvalidOrder(`amount precision exceeds 6 decimals: ${amount}`);
+    }
+    if (!/^\d*$/.test(intPart) || !/^\d*$/.test(fracPart)) {
+        throw new InvalidOrder(`invalid amount: ${amount}`);
+    }
+    const padded = (fracPart + "000000").slice(0, 6);
+    const intMag = BigInt(intPart || "0");
+    const scaled = intMag * SIX_DEC_SCALE + BigInt(padded);
+    return negative ? -scaled : scaled;
+}
+// ---------------------------------------------------------------------------
+// Order mappers
+// ---------------------------------------------------------------------------
+/** Map an `OrderV0` JSON object to {@link Order}. */
+export function orderFromV0(payload) {
+    const id = strOrEmpty(payload["id"]);
+    const marketId = strOrEmpty(payload["market_id"] ?? payload["marketId"]);
+    const outcomeId = strOrEmpty(payload["outcome_id"] ?? payload["outcomeId"]);
+    const status = strOrEmpty(payload["status"]);
+    const sideRaw = payload["side"];
+    const side = sideRaw === "sell" ? "sell" : "buy";
+    const typeRaw = payload["type"];
+    const type = typeRaw === "limit" ? "limit" : "market";
+    const order = {
+        id,
+        marketId,
+        outcomeId,
+        side,
+        type,
+        amount: floatOrZero(payload["amount"]),
+        status,
+        filled: floatOrZero(payload["filled"]),
+        remaining: floatOrZero(payload["remaining"]),
+        timestamp: timestampToMs(payload["timestamp"]),
+    };
+    const price = floatOrUndefined(payload["price"]);
+    if (price !== undefined)
+        order.price = price;
+    const fee = floatOrUndefined(payload["fee"]);
+    if (fee !== undefined)
+        order.fee = fee;
+    return order;
+}
+/** Map an {@link Order} back to an `OrderV0` JSON object. */
+export function orderToV0(order) {
+    const out = {
+        id: order.id,
+        market_id: order.marketId,
+        outcome_id: order.outcomeId,
+        side: order.side,
+        type: order.type,
+        amount: order.amount,
+        status: order.status,
+        filled: order.filled,
+        remaining: order.remaining,
+        timestamp: msToTimestamp(order.timestamp),
+    };
+    if (order.price !== undefined)
+        out["price"] = order.price;
+    if (order.fee !== undefined)
+        out["fee"] = order.fee;
+    return out;
+}
+// ---------------------------------------------------------------------------
+// UserTrade mappers
+// ---------------------------------------------------------------------------
+/** Map a `UserTradeV0` JSON object to {@link UserTrade}. */
+export function userTradeFromV0(payload) {
+    const sideRaw = payload["side"];
+    const side = sideRaw === "buy" || sideRaw === "sell" ? sideRaw : "unknown";
+    const trade = {
+        id: strOrEmpty(payload["id"]),
+        price: floatOrZero(payload["price"]),
+        amount: floatOrZero(payload["amount"]),
+        side,
+        timestamp: timestampToMs(payload["timestamp"]),
+    };
+    const orderId = strOrUndefined(payload["order_id"] ?? payload["orderId"]);
+    if (orderId !== undefined)
+        trade.orderId = orderId;
+    const outcomeId = strOrUndefined(payload["outcome_id"] ?? payload["outcomeId"]);
+    if (outcomeId !== undefined)
+        trade.outcomeId = outcomeId;
+    const marketId = strOrUndefined(payload["market_id"] ?? payload["marketId"]);
+    if (marketId !== undefined)
+        trade.marketId = marketId;
+    return trade;
+}
+/** Map a {@link UserTrade} back to a `UserTradeV0` JSON object. */
+export function userTradeToV0(trade) {
+    const out = {
+        id: trade.id,
+        side: trade.side,
+        amount: trade.amount,
+        price: trade.price,
+        timestamp: msToTimestamp(trade.timestamp),
+    };
+    if (trade.orderId !== undefined)
+        out["order_id"] = trade.orderId;
+    if (trade.outcomeId !== undefined)
+        out["outcome_id"] = trade.outcomeId;
+    if (trade.marketId !== undefined)
+        out["market_id"] = trade.marketId;
+    return out;
+}
+// ---------------------------------------------------------------------------
+// Position mappers
+// ---------------------------------------------------------------------------
+/**
+ * Map a `PositionV0` JSON object to {@link Position}.
+ *
+ * Optional fields (`outcomeLabel`, `entryPrice`, `currentPrice`,
+ * `unrealizedPnL`, `realizedPnL`) surface as `undefined` when missing —
+ * **never** a fake `0` or `""`. This keeps the SDK honest about which data
+ * the server actually provided.
+ */
+export function positionFromV0(payload) {
+    const size = floatOrZero(payload["shares"] ?? payload["size"]);
+    const entryPrice = floatOrUndefined(payload["entry_price"] ?? payload["entryPrice"]);
+    const currentPrice = floatOrUndefined(payload["current_price"] ?? payload["currentPrice"]);
+    let unrealizedPnL = floatOrUndefined(payload["unrealized_pnl"] ?? payload["unrealizedPnl"] ?? payload["unrealizedPnL"]);
+    if (unrealizedPnL === undefined &&
+        entryPrice !== undefined &&
+        currentPrice !== undefined) {
+        unrealizedPnL = (currentPrice - entryPrice) * size;
+    }
+    // Position requires marketId/outcomeId/outcomeLabel/entryPrice/currentPrice/unrealizedPnL
+    // in the current interface. We construct with safe defaults and only override
+    // when present. Per plan v5: the SDK should NOT fabricate financial data —
+    // when the server didn't supply entryPrice/currentPrice/outcomeLabel, we mark
+    // them via undefined (cast through a partial since the existing Position type
+    // hasn't yet been widened to Optional in this parallel-agent change).
+    const position = {
+        marketId: strOrEmpty(payload["market_id"] ?? payload["marketId"]),
+        outcomeId: strOrEmpty(payload["outcome_id"] ?? payload["outcomeId"]),
+        outcomeLabel: strOrUndefined(payload["outcome_label"] ?? payload["outcomeLabel"]),
+        size,
+        entryPrice: entryPrice,
+        currentPrice: currentPrice,
+        unrealizedPnL: unrealizedPnL,
+        realizedPnL: floatOrUndefined(payload["realized_pnl"] ?? payload["realizedPnl"] ?? payload["realizedPnL"]),
+    };
+    return position;
+}
+/** Map a {@link Position} back to a `PositionV0` JSON object. */
+export function positionToV0(position) {
+    const out = {
+        market_id: position.marketId,
+        outcome_id: position.outcomeId,
+        shares: position.size,
+    };
+    if (position.outcomeLabel !== undefined && position.outcomeLabel !== "") {
+        out["outcome_label"] = position.outcomeLabel;
+    }
+    if (position.entryPrice !== undefined)
+        out["entry_price"] = position.entryPrice;
+    if (position.currentPrice !== undefined)
+        out["current_price"] = position.currentPrice;
+    if (position.unrealizedPnL !== undefined)
+        out["unrealized_pnl"] = position.unrealizedPnL;
+    if (position.realizedPnL !== undefined)
+        out["realized_pnl"] = position.realizedPnL;
+    return out;
+}
+// ---------------------------------------------------------------------------
+// Balance mappers
+// ---------------------------------------------------------------------------
+/**
+ * Map a `BalanceV0` JSON object to {@link Balance}.
+ *
+ * Hosted-mode semantic: PreFundedEscrow doesn't reserve funds for resting
+ * orders, so `available = total` and `locked = 0`. Concurrent limit orders
+ * may fail at fill time if cumulative cost exceeds the escrow balance.
+ */
+export function balanceFromV0(payload) {
+    const total = floatOrZero(payload["amount"] ?? payload["total"]);
+    const currency = strOrUndefined(payload["currency"]) ?? "USDC";
+    return {
+        currency,
+        total,
+        available: total,
+        locked: 0,
+    };
+}
+/** Map a {@link Balance} back to a `BalanceV0` JSON object. */
+export function balanceToV0(balance) {
+    return {
+        currency: balance.currency,
+        amount: balance.total,
+    };
+}
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+function strOrUndefined(value) {
+    if (value === null || value === undefined)
+        return undefined;
+    if (typeof value === "string")
+        return value || undefined;
+    return String(value);
+}
+function strOrEmpty(value) {
+    if (value === null || value === undefined)
+        return "";
+    if (typeof value === "string")
+        return value;
+    return String(value);
+}
+function floatOrUndefined(value) {
+    if (value === null || value === undefined)
+        return undefined;
+    if (typeof value === "number")
+        return Number.isFinite(value) ? value : undefined;
+    if (typeof value === "bigint")
+        return Number(value);
+    if (typeof value === "string") {
+        if (!value)
+            return undefined;
+        const parsed = Number(value);
+        return Number.isFinite(parsed) ? parsed : undefined;
+    }
+    return undefined;
+}
+function floatOrZero(value) {
+    const converted = floatOrUndefined(value);
+    return converted !== undefined ? converted : 0;
+}
+/**
+ * Parse an ISO-8601 string (or numeric) timestamp to milliseconds since epoch.
+ * Returns `0` if the input is null/undefined/empty/unparseable.
+ */
+function timestampToMs(value) {
+    if (value === null || value === undefined)
+        return 0;
+    if (typeof value === "number") {
+        return Number.isFinite(value) ? Math.trunc(value) : 0;
+    }
+    if (typeof value === "bigint")
+        return Number(value);
+    if (typeof value === "string") {
+        if (!value)
+            return 0;
+        const normalized = value.endsWith("Z")
+            ? value
+            : /[+-]\d{2}:?\d{2}$/.test(value)
+                ? value
+                : value + "Z";
+        const ms = Date.parse(normalized);
+        return Number.isFinite(ms) ? ms : 0;
+    }
+    return 0;
+}
+/** Convert milliseconds-since-epoch back to an ISO-8601 string. */
+function msToTimestamp(value) {
+    if (value === null || value === undefined)
+        return undefined;
+    if (typeof value === "string")
+        return value;
+    if (typeof value === "number" && Number.isFinite(value)) {
+        return new Date(value).toISOString();
+    }
+    if (typeof value === "bigint") {
+        return new Date(Number(value)).toISOString();
+    }
+    return undefined;
+}

package/dist/esm/pmxt/hosted-routing.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Hosted-mode HTTP routing for the pmxt TypeScript SDK.
+ *
+ * When a client is configured with a `pmxtApiKey`, supported method calls are
+ * dispatched to the pmxt-hosted trading API instead of the venue's native
+ * client. This module owns:
+ *
+ *   - the static route table mapping SDK method names to hosted endpoints,
+ *   - the venue allowlist for hosted trading,
+ *   - wallet address resolution for user-scoped reads/trades, and
+ *   - the low-level `_tradingRequest` HTTP helper.
+ *
+ * Mirrors `sdks/python/pmxt/_hosted_routing.py`.
+ */
+export type HttpMethod = "GET" | "POST" | "PUT" | "DELETE";
+export type HostedBase = "catalog" | "trading";
+export declare const HOSTED_CATALOG_BASE_URL = "https://api.pmxt.dev";
+export declare const HOSTED_TRADING_BASE_URL = "https://trade.pmxt.dev";
+export declare const HOSTED_TRADING_VENUES: ReadonlySet<string>;
+export interface HostedRoute {
+    method: HttpMethod;
+    path: string;
+    base: HostedBase;
+    requiresWalletAddress?: boolean;
+}
+export declare const HOSTED_METHOD_ROUTES: ReadonlyMap<string, HostedRoute>;
+/**
+ * Minimal duck-typed view of a venue client used by hosted-mode helpers.
+ *
+ * Defining this as a structural interface keeps `hosted-routing` decoupled
+ * from the concrete `Exchange` class and makes unit testing trivial.
+ */
+export interface HostedClientLike {
+    pmxtApiKey?: string;
+    exchangeName: string;
+    walletAddress?: string;
+}
+/**
+ * Throw {@link NotSupported} if the client is in hosted mode (i.e. has a
+ * `pmxtApiKey`) but targets a venue outside the hosted trading allowlist.
+ * No-op for non-hosted clients.
+ */
+export declare function ensureHostedTradingSupported(client: HostedClientLike): void;
+/**
+ * Resolve the wallet address to use for a user-scoped hosted call, preferring
+ * an explicit per-call override over the client default. Throws
+ * {@link MissingWalletAddress} when neither is set.
+ */
+export declare function resolveWalletAddress(client: HostedClientLike, override?: string): string;
+/**
+ * Substitute `{name}` placeholders in a route path with URL-encoded values
+ * from `params`. Throws if a referenced parameter is missing.
+ */
+export declare function formatRoutePath(route: HostedRoute, params: Record<string, string | number | undefined>): string;
+export interface TradingRequestOptions {
+    method: HttpMethod;
+    path: string;
+    body?: unknown;
+    params?: Record<string, string | number | boolean | undefined>;
+}
+/**
+ * Issue a request against the hosted trading API.
+ *
+ * NOTE: writes (POST/PUT/DELETE) are NEVER retried. `built_order_id` and
+ * `cancel_id` are single-use server-side, so replaying a lost response would
+ * 404 even though the original write succeeded. Callers needing retry logic
+ * must layer it on top with awareness of this invariant.
+ */
+export declare function _tradingRequest(client: HostedClientLike, opts: TradingRequestOptions): Promise<unknown>;

package/dist/esm/pmxt/hosted-routing.js

@@ -0,0 +1,119 @@
+/**
+ * Hosted-mode HTTP routing for the pmxt TypeScript SDK.
+ *
+ * When a client is configured with a `pmxtApiKey`, supported method calls are
+ * dispatched to the pmxt-hosted trading API instead of the venue's native
+ * client. This module owns:
+ *
+ *   - the static route table mapping SDK method names to hosted endpoints,
+ *   - the venue allowlist for hosted trading,
+ *   - wallet address resolution for user-scoped reads/trades, and
+ *   - the low-level `_tradingRequest` HTTP helper.
+ *
+ * Mirrors `sdks/python/pmxt/_hosted_routing.py`.
+ */
+import { NotSupported } from "./errors.js";
+import { MissingWalletAddress, raiseFromResponse } from "./hosted-errors.js";
+export const HOSTED_CATALOG_BASE_URL = "https://api.pmxt.dev";
+export const HOSTED_TRADING_BASE_URL = "https://trade.pmxt.dev";
+export const HOSTED_TRADING_VENUES = new Set([
+    "polymarket",
+    "opinion",
+]);
+export const HOSTED_METHOD_ROUTES = new Map([
+    ["createOrder", { method: "POST", path: "/v0/trade/build-order", base: "trading" }],
+    ["buildOrder", { method: "POST", path: "/v0/trade/build-order", base: "trading" }],
+    ["submitOrder", { method: "POST", path: "/v0/trade/submit-order", base: "trading" }],
+    ["cancelOrderBuild", { method: "POST", path: "/v0/orders/cancel/build", base: "trading" }],
+    ["cancelOrder", { method: "POST", path: "/v0/orders/cancel", base: "trading" }],
+    ["fetchOrder", { method: "GET", path: "/v0/orders/{order_id}", base: "trading" }],
+    ["fetchOpenOrders", { method: "GET", path: "/v0/orders/open", base: "trading", requiresWalletAddress: true }],
+    ["fetchMyTrades", { method: "GET", path: "/v0/user/{address}/trades", base: "trading", requiresWalletAddress: true }],
+    ["fetchBalance", { method: "GET", path: "/v0/user/{address}/balances", base: "trading", requiresWalletAddress: true }],
+    ["fetchPositions", { method: "GET", path: "/v0/user/{address}/positions", base: "trading", requiresWalletAddress: true }],
+    ["escrowApproveTx", { method: "POST", path: "/v0/escrow/approve", base: "trading" }],
+    ["escrowDepositTx", { method: "POST", path: "/v0/escrow/deposit", base: "trading" }],
+    ["escrowWithdrawTx", { method: "POST", path: "/v0/escrow/withdraw", base: "trading" }],
+    ["escrowWithdrawals", { method: "GET", path: "/v0/escrow/{address}/withdrawals", base: "trading", requiresWalletAddress: true }],
+]);
+/**
+ * Throw {@link NotSupported} if the client is in hosted mode (i.e. has a
+ * `pmxtApiKey`) but targets a venue outside the hosted trading allowlist.
+ * No-op for non-hosted clients.
+ */
+export function ensureHostedTradingSupported(client) {
+    if (!client.pmxtApiKey)
+        return;
+    if (!HOSTED_TRADING_VENUES.has(client.exchangeName)) {
+        throw new NotSupported(`Hosted trading is only supported for Polymarket and Opinion; ${client.exchangeName} is not supported with pmxtApiKey.`);
+    }
+}
+/**
+ * Resolve the wallet address to use for a user-scoped hosted call, preferring
+ * an explicit per-call override over the client default. Throws
+ * {@link MissingWalletAddress} when neither is set.
+ */
+export function resolveWalletAddress(client, override) {
+    if (override)
+        return override;
+    if (client.walletAddress)
+        return client.walletAddress;
+    throw new MissingWalletAddress("walletAddress is required for hosted-mode reads and trades; pass it to the exchange constructor or as an override.");
+}
+/**
+ * Substitute `{name}` placeholders in a route path with URL-encoded values
+ * from `params`. Throws if a referenced parameter is missing.
+ */
+export function formatRoutePath(route, params) {
+    return route.path.replace(/\{(\w+)\}/g, (_, key) => {
+        const value = params[key];
+        if (value === undefined || value === null) {
+            throw new Error(`path parameter cannot be undefined: ${key}`);
+        }
+        return encodeURIComponent(String(value));
+    });
+}
+/**
+ * Issue a request against the hosted trading API.
+ *
+ * NOTE: writes (POST/PUT/DELETE) are NEVER retried. `built_order_id` and
+ * `cancel_id` are single-use server-side, so replaying a lost response would
+ * 404 even though the original write succeeded. Callers needing retry logic
+ * must layer it on top with awareness of this invariant.
+ */
+export async function _tradingRequest(client, opts) {
+    if (!client.pmxtApiKey) {
+        throw new Error("hosted request requires pmxtApiKey");
+    }
+    const base = HOSTED_TRADING_BASE_URL.replace(/\/$/, "");
+    const path = opts.path.startsWith("/") ? opts.path : `/${opts.path}`;
+    let url = base + path;
+    if (opts.params) {
+        const qs = new URLSearchParams();
+        for (const [k, v] of Object.entries(opts.params)) {
+            if (v !== undefined)
+                qs.append(k, String(v));
+        }
+        const q = qs.toString();
+        if (q)
+            url += `?${q}`;
+    }
+    const headers = {
+        Authorization: `Bearer ${client.pmxtApiKey}`,
+    };
+    if (opts.body !== undefined) {
+        headers["Content-Type"] = "application/json";
+    }
+    const resp = await fetch(url, {
+        method: opts.method,
+        headers,
+        body: opts.body !== undefined ? JSON.stringify(opts.body) : undefined,
+    });
+    if (!resp.ok) {
+        await raiseFromResponse(resp);
+    }
+    const text = await resp.text();
+    if (!text)
+        return null;
+    return JSON.parse(text);
+}

package/dist/esm/pmxt/hosted-typed-data.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Hosted trading EIP-712 validation guardrails.
+ *
+ * Three layers (mirrors `sdks/python/pmxt/_hosted_typeddata.py`):
+ *   1. Schema validation — per-route shape, domain, types, message keys, deadline
+ *   2. Economic match — typed_data economics agree with the user's build request
+ *   3. Post-sign — exact 65-byte length, low-s canonical, v ∈ {27, 28}, recovery
+ *
+ * Layer 3 uses the optional `ethers` peer dependency for typed-data verification.
+ */
+import { TypedData } from "./signers.js";
+export type HostedRoute = "polymarket_buy" | "polymarket_sell" | "opinion_buy" | "opinion_sell_polygon" | "opinion_sell_bsc_pull" | "cancel_polymarket" | "cancel_opinion_polygon" | "cancel_opinion_bsc_pull";
+export declare const SECP256K1_HALF_N = 57896044618658097711785492504343953926418782139537452191302581570759080747168n;
+/**
+ * Validate the structural shape of a typed-data payload before signing.
+ * Throws {@link InvalidSignature} on any mismatch.
+ */
+export declare function validateTypedData(typedData: TypedData, route: string, walletAddress: string): void;
+/**
+ * Reject typed-data whose economics don't agree with the user's original
+ * build request / build response. Guards against a compromised server
+ * returning valid-shape typed-data with altered amounts or wrong target.
+ */
+export declare function validateEconomics(typedData: TypedData, route: string, buildRequest: any, buildResponse: any): void;
+/**
+ * Verify a signature against typed-data and return the normalized signature.
+ *
+ * Performs:
+ *   - exact 65-byte length (0x + 130 hex)
+ *   - low-s canonical check
+ *   - v ∈ {27, 28} (normalizes {0,1} → {27,28})
+ *   - typed-data recovery, asserting recovered address === walletAddress
+ *
+ * Throws {@link InvalidSignature} on any failure.
+ */
+export declare function verifySignature(typedData: TypedData, signature: string, walletAddress: string): string;