pmxt-core 2.23.0 → 2.25.0

package/dist/exchanges/kalshi/api.d.ts

@@ -1,6 +1,6 @@
 /**
  * Auto-generated from /home/runner/work/pmxt/pmxt/core/specs/kalshi/Kalshi.yaml
- * Generated at: 2026-04-04T07:52:19.224Z
+ * Generated at: 2026-04-06T19:59:33.306Z
  * Do not edit manually -- run "npm run fetch:openapi" to regenerate.
  */
 export declare const kalshiApiSpec: {

package/dist/exchanges/kalshi/api.js

@@ -3,7 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.kalshiApiSpec = void 0;
 /**
  * Auto-generated from /home/runner/work/pmxt/pmxt/core/specs/kalshi/Kalshi.yaml
- * Generated at: 2026-04-04T07:52:19.224Z
+ * Generated at: 2026-04-06T19:59:33.306Z
  * Do not edit manually -- run "npm run fetch:openapi" to regenerate.
  */
 exports.kalshiApiSpec = {

package/dist/exchanges/limitless/api.d.ts

@@ -1,6 +1,6 @@
 /**
  * Auto-generated from /home/runner/work/pmxt/pmxt/core/specs/limitless/Limitless.yaml
- * Generated at: 2026-04-04T07:52:19.272Z
+ * Generated at: 2026-04-06T19:59:33.358Z
  * Do not edit manually -- run "npm run fetch:openapi" to regenerate.
  */
 export declare const limitlessApiSpec: {

package/dist/exchanges/limitless/api.js

@@ -3,7 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.limitlessApiSpec = void 0;
 /**
  * Auto-generated from /home/runner/work/pmxt/pmxt/core/specs/limitless/Limitless.yaml
- * Generated at: 2026-04-04T07:52:19.272Z
+ * Generated at: 2026-04-06T19:59:33.358Z
  * Do not edit manually -- run "npm run fetch:openapi" to regenerate.
  */
 exports.limitlessApiSpec = {

package/dist/exchanges/myriad/api.d.ts

@@ -1,6 +1,6 @@
 /**
  * Auto-generated from /home/runner/work/pmxt/pmxt/core/specs/myriad/myriad.yaml
- * Generated at: 2026-04-04T07:52:19.286Z
+ * Generated at: 2026-04-06T19:59:33.373Z
  * Do not edit manually -- run "npm run fetch:openapi" to regenerate.
  */
 export declare const myriadApiSpec: {

package/dist/exchanges/myriad/api.js

@@ -3,7 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.myriadApiSpec = void 0;
 /**
  * Auto-generated from /home/runner/work/pmxt/pmxt/core/specs/myriad/myriad.yaml
- * Generated at: 2026-04-04T07:52:19.286Z
+ * Generated at: 2026-04-06T19:59:33.373Z
  * Do not edit manually -- run "npm run fetch:openapi" to regenerate.
  */
 exports.myriadApiSpec = {

package/dist/exchanges/opinion/api.d.ts

@@ -1,6 +1,6 @@
 /**
  * Auto-generated from /home/runner/work/pmxt/pmxt/core/specs/opinion/opinion-openapi.yaml
- * Generated at: 2026-04-04T07:52:19.290Z
+ * Generated at: 2026-04-06T19:59:33.380Z
  * Do not edit manually -- run "npm run fetch:openapi" to regenerate.
  */
 export declare const opinionApiSpec: {

package/dist/exchanges/opinion/api.js

@@ -3,7 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.opinionApiSpec = void 0;
 /**
  * Auto-generated from /home/runner/work/pmxt/pmxt/core/specs/opinion/opinion-openapi.yaml
- * Generated at: 2026-04-04T07:52:19.290Z
+ * Generated at: 2026-04-06T19:59:33.380Z
  * Do not edit manually -- run "npm run fetch:openapi" to regenerate.
  */
 exports.opinionApiSpec = {

package/dist/exchanges/polymarket/api-clob.d.ts

@@ -1,6 +1,6 @@
 /**
  * Auto-generated from /home/runner/work/pmxt/pmxt/core/specs/polymarket/PolymarketClobAPI.yaml
- * Generated at: 2026-04-04T07:52:19.235Z
+ * Generated at: 2026-04-06T19:59:33.315Z
  * Do not edit manually -- run "npm run fetch:openapi" to regenerate.
  */
 export declare const polymarketClobSpec: {

package/dist/exchanges/polymarket/api-clob.js

@@ -3,7 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.polymarketClobSpec = void 0;
 /**
  * Auto-generated from /home/runner/work/pmxt/pmxt/core/specs/polymarket/PolymarketClobAPI.yaml
- * Generated at: 2026-04-04T07:52:19.235Z
+ * Generated at: 2026-04-06T19:59:33.315Z
  * Do not edit manually -- run "npm run fetch:openapi" to regenerate.
  */
 exports.polymarketClobSpec = {

package/dist/exchanges/polymarket/api-data.d.ts

@@ -1,6 +1,6 @@
 /**
  * Auto-generated from /home/runner/work/pmxt/pmxt/core/specs/polymarket/Polymarket_Data_API.yaml
- * Generated at: 2026-04-04T07:52:19.249Z
+ * Generated at: 2026-04-06T19:59:33.333Z
  * Do not edit manually -- run "npm run fetch:openapi" to regenerate.
  */
 export declare const polymarketDataSpec: {

package/dist/exchanges/polymarket/api-data.js

@@ -3,7 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.polymarketDataSpec = void 0;
 /**
  * Auto-generated from /home/runner/work/pmxt/pmxt/core/specs/polymarket/Polymarket_Data_API.yaml
- * Generated at: 2026-04-04T07:52:19.249Z
+ * Generated at: 2026-04-06T19:59:33.333Z
  * Do not edit manually -- run "npm run fetch:openapi" to regenerate.
  */
 exports.polymarketDataSpec = {

package/dist/exchanges/polymarket/api-gamma.d.ts

@@ -1,6 +1,6 @@
 /**
  * Auto-generated from /home/runner/work/pmxt/pmxt/core/specs/polymarket/PolymarketGammaAPI.yaml
- * Generated at: 2026-04-04T07:52:19.246Z
+ * Generated at: 2026-04-06T19:59:33.328Z
  * Do not edit manually -- run "npm run fetch:openapi" to regenerate.
  */
 export declare const polymarketGammaSpec: {

package/dist/exchanges/polymarket/api-gamma.js

@@ -3,7 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.polymarketGammaSpec = void 0;
 /**
  * Auto-generated from /home/runner/work/pmxt/pmxt/core/specs/polymarket/PolymarketGammaAPI.yaml
- * Generated at: 2026-04-04T07:52:19.246Z
+ * Generated at: 2026-04-06T19:59:33.328Z
  * Do not edit manually -- run "npm run fetch:openapi" to regenerate.
  */
 exports.polymarketGammaSpec = {

package/dist/exchanges/polymarket/auth.js

@@ -158,22 +158,56 @@ class PolymarketAuth {
         if (this.clobClient) {
             return this.clobClient;
         }
-        // 1. Determine proxy and signature type early
+        // 1. Determine proxy and signature type early.
+        //
+        // Important: if signatureType is not provided we MUST run discovery
+        // even when funderAddress is provided. Previously this branch was
+        // skipped whenever funderAddress was set, which silently defaulted
+        // signatureType to 0 (EOA). For wallets whose funds live on a Gnosis
+        // Safe (the modern Polymarket onboarding default) the CLOB then
+        // reports balance "0" instead of the real value, with no error.
+        const sigTypeProvided = this.credentials.signatureType !== undefined && this.credentials.signatureType !== null;
         let proxyAddress = this.credentials.funderAddress || undefined;
-        let signatureType = this.mapSignatureType(this.credentials.signatureType);
-        if (!proxyAddress) {
-            const discovered = await this.discoverProxy();
-            proxyAddress = discovered.proxyAddress;
-            if (this.credentials.signatureType === undefined || this.credentials.signatureType === null) {
-                signatureType = discovered.signatureType;
+        let signatureType = sigTypeProvided
+            ? this.mapSignatureType(this.credentials.signatureType)
+            : undefined;
+        // Run discovery if either piece is missing. Note: discoverProxy()
+        // returns a synthetic { proxyAddress: signerEOA, signatureType: 0 }
+        // fallback when its HTTP call fails — that fallback should NOT be
+        // used to populate signatureType when funderAddress is already set,
+        // because it would silently assign EOA semantics to a Gnosis Safe.
+        let discoverySucceeded = false;
+        if (!proxyAddress || signatureType === undefined) {
+            try {
+                const discovered = await this.discoverProxy();
+                discoverySucceeded =
+                    !!this.discoveredProxyAddress &&
+                        this.discoveredSignatureType !== undefined;
+                if (!proxyAddress) {
+                    proxyAddress = discovered.proxyAddress;
+                }
+                if (signatureType === undefined && discoverySucceeded) {
+                    signatureType = discovered.signatureType;
+                }
+            }
+            catch {
+                // Discovery failure is handled by the heuristic below.
             }
         }
         // Get API credentials (L1 auth)
-        // Pass signature type if we know it (some accounts need it for derivation?)
         const apiCreds = await this.getApiCredentials();
         // 3. Defaults
         const signerAddress = this.signer.address;
         const finalProxyAddress = (proxyAddress || signerAddress);
+        // If signature type is still unknown, infer from address relationship:
+        // when the funder differs from the signer EOA, the funder must be a
+        // proxy/safe — default to Gnosis Safe (2), which is what Polymarket
+        // has created for new accounts since 2023. Users on the legacy
+        // Polymarket Proxy (1) need to set signatureType explicitly.
+        if (signatureType === undefined) {
+            signatureType =
+                finalProxyAddress.toLowerCase() !== signerAddress.toLowerCase() ? 2 : 0;
+        }
         const finalSignatureType = signatureType;
         // Create L2-authenticated client
         // console.log(`[PolymarketAuth] Initializing ClobClient | Signer: ${signerAddress} | Funder: ${finalProxyAddress} | SigType: ${finalSignatureType}`);

package/dist/exchanges/polymarket/index.js

@@ -357,45 +357,82 @@ class PolymarketExchange extends BaseExchange_1.PredictionMarketExchange {
             const client = await auth.getClobClient();
             // Polymarket relies strictly on USDC (Polygon)
             const USDC_DECIMALS = 6;
-            // Try fetching from CLOB client first
+            // Try fetching from CLOB client first.
+            //
+            // Note on the bundled @polymarket/clob-client error model: its HTTP
+            // wrapper swallows axios errors and RETURNS an envelope shaped like
+            // { error, status } instead of throwing. We must therefore validate
+            // the shape of the result before using it, otherwise downstream
+            // parseFloat() yields NaN and the on-chain fallback never triggers.
             let total = 0;
+            let clobBalanceAvailable = false;
             try {
                 const balRes = await client.getBalanceAllowance({
                     asset_type: clob_client_1.AssetType.COLLATERAL,
                 });
-                const rawBalance = parseFloat(balRes.balance);
-                total = rawBalance / Math.pow(10, USDC_DECIMALS);
+                if (balRes && typeof balRes.balance === 'string') {
+                    const rawBalance = parseFloat(balRes.balance);
+                    if (Number.isFinite(rawBalance)) {
+                        total = rawBalance / Math.pow(10, USDC_DECIMALS);
+                        clobBalanceAvailable = true;
+                    }
+                }
+                // If balRes was an error envelope, fall through to on-chain.
             }
             catch (clobError) {
-                // If CLOB fails or returns 0 (suspiciously), we can try on-chain
-                // but let's assume we proceed to on-chain check if total is 0
-                // or just do on-chain check always for robustness if possible.
-                // For now, let's trust CLOB but add On-Chain fallback if CLOB returns 0.
+                // Network/transport error — fall through to on-chain.
             }
             // On-Chain Fallback/Check (Robustness)
-            // If CLOB reported 0, let's verify on-chain because sometimes CLOB is behind or confused about proxies
-            if (total === 0) {
+            // Trigger when CLOB couldn't tell us, or reported a true zero (CLOB
+            // can lag or be confused about proxies for newly funded wallets).
+            if (!clobBalanceAvailable || total === 0) {
                 try {
                     const targetAddress = await auth.getEffectiveFunderAddress();
                     const balances = await this.getAddressOnChainBalance(targetAddress);
-                    total = balances[0]?.total ?? 0;
+                    const onChain = balances[0]?.total ?? 0;
+                    if (onChain > 0) {
+                        total = onChain;
+                    }
                 }
                 catch {
                 }
             }
-            // 2. Fetch open orders to calculate locked funds
-            // We only care about BUY orders for USDC balance locking
-            const openOrders = await client.getOpenOrders({});
+            // 2. Fetch open orders to calculate locked funds.
+            // We only care about BUY orders for USDC balance locking.
+            //
+            // The bundled @polymarket/clob-client throws "response.data is not
+            // iterable" from inside its getOpenOrders pagination loop whenever
+            // the CLOB API returns an HTTP error envelope (the library spreads
+            // response.data unconditionally). This is the root cause of #72:
+            // a wallet that has not completed Polymarket onboarding triggers an
+            // upstream auth/setup rejection that surfaces here as an opaque
+            // TypeError. Catch it and translate to a clear AuthenticationError.
             let locked = 0;
-            if (openOrders && Array.isArray(openOrders)) {
-                for (const order of openOrders) {
-                    if (order.side === clob_client_1.Side.BUY) {
-                        const remainingSize = parseFloat(order.original_size) - parseFloat(order.size_matched);
-                        const price = parseFloat(order.price);
-                        locked += remainingSize * price;
+            try {
+                const openOrders = await client.getOpenOrders({});
+                if (Array.isArray(openOrders)) {
+                    for (const order of openOrders) {
+                        if (order.side === clob_client_1.Side.BUY) {
+                            const remainingSize = parseFloat(order.original_size) - parseFloat(order.size_matched);
+                            const price = parseFloat(order.price);
+                            locked += remainingSize * price;
+                        }
                     }
                 }
             }
+            catch (ordersError) {
+                const msg = String(ordersError?.message ?? ordersError);
+                if (msg.includes('is not iterable')) {
+                    throw new errors_1.AuthenticationError('Polymarket CLOB rejected the request to list open orders. ' +
+                        'This usually means the wallet has not completed Polymarket ' +
+                        'onboarding (no proxy/safe exists for this signer), or that ' +
+                        'funderAddress / signatureType need to be passed explicitly. ' +
+                        'Visit https://polymarket.com to complete account setup, or ' +
+                        'pass funderAddress and signatureType in credentials.', 'Polymarket');
+                }
+                // Unexpected failure — surface through the standard mapper.
+                throw ordersError;
+            }
             return [{
                     currency: 'USDC',
                     total: total,

package/dist/exchanges/polymarket_us/config.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Polymarket US runtime configuration.
+ *
+ * Hand-authored single source of truth for base URLs and config factory
+ * for the Polymarket US exchange adapter (wraps the polymarket-us SDK).
+ */
+export declare const POLYMARKET_US_API_BASE_URL = "https://api.polymarket.us";
+export declare const POLYMARKET_US_GATEWAY_BASE_URL = "https://gateway.polymarket.us";
+export interface PolymarketUSConfig {
+    /** Base REST API URL */
+    apiUrl: string;
+    /** Gateway URL (used by the SDK for order signing / submission) */
+    gatewayUrl: string;
+}
+/**
+ * Return a typed config object for the Polymarket US API.
+ */
+export declare function getPolymarketUSConfig(): PolymarketUSConfig;

package/dist/exchanges/polymarket_us/config.js

@@ -0,0 +1,22 @@
+"use strict";
+/**
+ * Polymarket US runtime configuration.
+ *
+ * Hand-authored single source of truth for base URLs and config factory
+ * for the Polymarket US exchange adapter (wraps the polymarket-us SDK).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.POLYMARKET_US_GATEWAY_BASE_URL = exports.POLYMARKET_US_API_BASE_URL = void 0;
+exports.getPolymarketUSConfig = getPolymarketUSConfig;
+// -- Base URL constants -------------------------------------------------------
+exports.POLYMARKET_US_API_BASE_URL = "https://api.polymarket.us";
+exports.POLYMARKET_US_GATEWAY_BASE_URL = "https://gateway.polymarket.us";
+/**
+ * Return a typed config object for the Polymarket US API.
+ */
+function getPolymarketUSConfig() {
+    return {
+        apiUrl: exports.POLYMARKET_US_API_BASE_URL,
+        gatewayUrl: exports.POLYMARKET_US_GATEWAY_BASE_URL,
+    };
+}

package/dist/exchanges/polymarket_us/errors.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Maps polymarket-us SDK errors to PMXT unified error classes.
+ *
+ * The SDK exposes typed error subclasses (AuthenticationError,
+ * BadRequestError, NotFoundError, RateLimitError, InternalServerError,
+ * APIError, PolymarketUSError) so we can dispatch on instance rather
+ * than inspecting raw HTTP responses.
+ */
+/**
+ * Polymarket US -> PMXT error mapper.
+ */
+export declare class PolymarketUSErrorMapper {
+    /**
+     * Map an unknown error thrown by the polymarket-us SDK (or any
+     * other source) to a PMXT error class instance.
+     */
+    mapError(error: unknown): Error;
+}
+export declare const polymarketUSErrorMapper: PolymarketUSErrorMapper;

package/dist/exchanges/polymarket_us/errors.js

@@ -0,0 +1,123 @@
+"use strict";
+/**
+ * Maps polymarket-us SDK errors to PMXT unified error classes.
+ *
+ * The SDK exposes typed error subclasses (AuthenticationError,
+ * BadRequestError, NotFoundError, RateLimitError, InternalServerError,
+ * APIError, PolymarketUSError) so we can dispatch on instance rather
+ * than inspecting raw HTTP responses.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.polymarketUSErrorMapper = exports.PolymarketUSErrorMapper = void 0;
+const polymarket_us_1 = require("polymarket-us");
+const errors_1 = require("../../errors");
+const EXCHANGE_NAME = 'PolymarketUS';
+/**
+ * Construct a generic PMXT error for cases where no more specific
+ * mapping applies. Uses BaseError directly since the project does not
+ * yet expose an `ExchangeError` class.
+ */
+function genericExchangeError(message) {
+    return new errors_1.BaseError(message, 500, 'EXCHANGE_ERROR', false, EXCHANGE_NAME);
+}
+/**
+ * Polymarket US -> PMXT error mapper.
+ */
+class PolymarketUSErrorMapper {
+    /**
+     * Map an unknown error thrown by the polymarket-us SDK (or any
+     * other source) to a PMXT error class instance.
+     */
+    mapError(error) {
+        // Already a PMXT error: pass through unchanged so callers can
+        // rely on `instanceof` checks (e.g. AuthenticationError thrown
+        // by `requireAuth` before any SDK call).
+        if (error instanceof errors_1.BaseError) {
+            return error;
+        }
+        // Authentication
+        if (error instanceof polymarket_us_1.AuthenticationError) {
+            return new errors_1.AuthenticationError(error.message, EXCHANGE_NAME);
+        }
+        // Rate limit
+        if (error instanceof polymarket_us_1.RateLimitError) {
+            return new errors_1.RateLimitExceeded(error.message, undefined, EXCHANGE_NAME);
+        }
+        // Not found - inspect message to discriminate order vs market
+        if (error instanceof polymarket_us_1.NotFoundError) {
+            const lower = (error.message || '').toLowerCase();
+            if (lower.includes('order')) {
+                return new errors_1.OrderNotFound(error.message, EXCHANGE_NAME);
+            }
+            if (lower.includes('market')) {
+                return new errors_1.MarketNotFound(error.message, EXCHANGE_NAME);
+            }
+            return genericExchangeError(error.message);
+        }
+        // Internal server error -> retryable unavailable
+        if (error instanceof polymarket_us_1.InternalServerError) {
+            return new errors_1.ExchangeNotAvailable(error.message, EXCHANGE_NAME);
+        }
+        // Bad request - inspect for known sub-categories
+        if (error instanceof polymarket_us_1.BadRequestError) {
+            return mapBadRequest(error.message);
+        }
+        // Generic API error - dispatch on status code
+        if (error instanceof polymarket_us_1.APIError) {
+            return mapByStatus(error.status, error.message);
+        }
+        // Catch-all SDK base class
+        if (error instanceof polymarket_us_1.PolymarketUSError) {
+            return genericExchangeError(error.message);
+        }
+        // Anything else
+        const message = String(error?.message ?? error);
+        return genericExchangeError(message);
+    }
+}
+exports.PolymarketUSErrorMapper = PolymarketUSErrorMapper;
+function mapBadRequest(message) {
+    const lower = (message || '').toLowerCase();
+    if (lower.includes('insufficient') ||
+        lower.includes('buying power') ||
+        lower.includes('balance')) {
+        return new errors_1.InsufficientFunds(message, EXCHANGE_NAME);
+    }
+    if (lower.includes('invalid order') ||
+        lower.includes('price') ||
+        lower.includes('quantity') ||
+        lower.includes('tick') ||
+        lower.includes('self-match') ||
+        lower.includes('self_match')) {
+        return new errors_1.InvalidOrder(message, EXCHANGE_NAME);
+    }
+    if (lower.includes('market')) {
+        if (lower.includes('not found')) {
+            return new errors_1.MarketNotFound(message, EXCHANGE_NAME);
+        }
+        if (lower.includes('closed') ||
+            lower.includes('expired') ||
+            lower.includes('halted') ||
+            lower.includes('suspended')) {
+            return new errors_1.InvalidOrder(message, EXCHANGE_NAME);
+        }
+    }
+    return new errors_1.BadRequest(message, EXCHANGE_NAME);
+}
+function mapByStatus(status, message) {
+    if (status === 401) {
+        return new errors_1.AuthenticationError(message, EXCHANGE_NAME);
+    }
+    if (status === 404) {
+        return genericExchangeError(message);
+    }
+    if (status === 429) {
+        return new errors_1.RateLimitExceeded(message, undefined, EXCHANGE_NAME);
+    }
+    if (status >= 500 && status < 600) {
+        return new errors_1.ExchangeNotAvailable(message, EXCHANGE_NAME);
+    }
+    return new errors_1.BadRequest(message, EXCHANGE_NAME);
+}
+// Singleton instance for convenience
+exports.polymarketUSErrorMapper = new PolymarketUSErrorMapper();

package/dist/exchanges/polymarket_us/errors.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/exchanges/polymarket_us/errors.test.js

@@ -0,0 +1,54 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const errors_1 = require("./errors");
+const polymarket_us_1 = require("polymarket-us");
+const errors_2 = require("../../errors");
+describe('PolymarketUSErrorMapper', () => {
+    const mapper = new errors_1.PolymarketUSErrorMapper();
+    test('maps SDK AuthenticationError -> PMXT AuthenticationError', () => {
+        const mapped = mapper.mapError(new polymarket_us_1.AuthenticationError('bad token'));
+        expect(mapped).toBeInstanceOf(errors_2.AuthenticationError);
+        expect(mapped.exchange).toBe('PolymarketUS');
+    });
+    test('maps BadRequestError("Insufficient buying power") -> InsufficientFunds', () => {
+        const mapped = mapper.mapError(new polymarket_us_1.BadRequestError('Insufficient buying power'));
+        expect(mapped).toBeInstanceOf(errors_2.InsufficientFunds);
+    });
+    test('maps BadRequestError("Invalid price tick") -> InvalidOrder', () => {
+        const mapped = mapper.mapError(new polymarket_us_1.BadRequestError('Invalid price tick'));
+        expect(mapped).toBeInstanceOf(errors_2.InvalidOrder);
+    });
+    test('maps BadRequestError("Self-match prevented") -> InvalidOrder', () => {
+        const mapped = mapper.mapError(new polymarket_us_1.BadRequestError('Self-match prevented'));
+        expect(mapped).toBeInstanceOf(errors_2.InvalidOrder);
+    });
+    test('maps NotFoundError("Order not found") -> OrderNotFound', () => {
+        const mapped = mapper.mapError(new polymarket_us_1.NotFoundError('Order not found'));
+        expect(mapped).toBeInstanceOf(errors_2.OrderNotFound);
+    });
+    test('maps NotFoundError("Market not found") -> MarketNotFound', () => {
+        const mapped = mapper.mapError(new polymarket_us_1.NotFoundError('Market not found'));
+        expect(mapped).toBeInstanceOf(errors_2.MarketNotFound);
+    });
+    test('maps RateLimitError -> RateLimitExceeded', () => {
+        const mapped = mapper.mapError(new polymarket_us_1.RateLimitError('slow down'));
+        expect(mapped).toBeInstanceOf(errors_2.RateLimitExceeded);
+    });
+    test('maps InternalServerError -> ExchangeNotAvailable', () => {
+        const mapped = mapper.mapError(new polymarket_us_1.InternalServerError('boom'));
+        expect(mapped).toBeInstanceOf(errors_2.ExchangeNotAvailable);
+    });
+    test('maps generic Error -> generic exchange BaseError', () => {
+        const mapped = mapper.mapError(new Error('something failed'));
+        expect(mapped).toBeInstanceOf(errors_2.BaseError);
+        expect(mapped.exchange).toBe('PolymarketUS');
+        expect(mapped.code).toBe('EXCHANGE_ERROR');
+        expect(mapped.message).toBe('something failed');
+    });
+    test('maps plain object -> generic exchange BaseError', () => {
+        const mapped = mapper.mapError({ message: 'plain object error' });
+        expect(mapped).toBeInstanceOf(errors_2.BaseError);
+        expect(mapped.exchange).toBe('PolymarketUS');
+        expect(mapped.message).toBe('plain object error');
+    });
+});

package/dist/exchanges/polymarket_us/index.d.ts

@@ -0,0 +1,90 @@
+/**
+ * Polymarket US exchange adapter.
+ *
+ * Wraps the official `polymarket-us` SDK to expose Polymarket US under the
+ * unified PMXT `PredictionMarketExchange` interface.
+ *
+ * Notes:
+ *  - PMXT `marketId` corresponds to the Polymarket US market `slug`.
+ *  - Outcomes are encoded as `${slug}:long` and `${slug}:short`.
+ *  - Polymarket US books and orders are quoted in long-side prices; helpers
+ *    in `./price` perform the side-aware conversion.
+ *  - The SDK requires `marketSlug` in the cancel body, but PMXT
+ *    `cancelOrder(orderId)` does not. We maintain an in-memory cache mapping
+ *    orderId -> marketSlug populated whenever we observe an order.
+ */
+import { PredictionMarketExchange, ExchangeCredentials, MarketFetchParams, EventFetchParams, MyTradesParams } from '../../BaseExchange';
+import { UnifiedMarket, UnifiedEvent, OrderBook, Trade, UserTrade, Order, Position, Balance, CreateOrderParams, BuiltOrder } from '../../types';
+export * from './config';
+export * from './price';
+export * from './errors';
+export { PolymarketUSNormalizer } from './normalizer';
+export declare class PolymarketUSExchange extends PredictionMarketExchange {
+    readonly has: {
+        fetchMarkets: true;
+        fetchEvents: true;
+        fetchOHLCV: false;
+        fetchOrderBook: true;
+        fetchTrades: false;
+        createOrder: true;
+        cancelOrder: true;
+        fetchOrder: true;
+        fetchOpenOrders: true;
+        fetchPositions: true;
+        fetchBalance: true;
+        watchAddress: false;
+        unwatchAddress: false;
+        watchOrderBook: true;
+        watchTrades: true;
+        fetchMyTrades: true;
+        fetchClosedOrders: false;
+        fetchAllOrders: false;
+        buildOrder: true;
+        submitOrder: true;
+    };
+    private readonly client;
+    private readonly normalizer;
+    private readonly config;
+    /**
+     * Maps PMXT orderId -> Polymarket US marketSlug. Populated whenever we
+     * observe an order (create, fetch, list) so that `cancelOrder(orderId)`
+     * can supply the SDK-required `marketSlug` body field.
+     */
+    private readonly orderSlugCache;
+    private wsWrapper?;
+    constructor(credentials?: ExchangeCredentials);
+    get name(): string;
+    private requireAuth;
+    /**
+     * Wrap any SDK call so SDK errors get translated to PMXT error classes.
+     */
+    private run;
+    private cacheOrder;
+    /**
+     * Strip a trailing `:long` or `:short` suffix from a PMXT identifier
+     * to recover the bare Polymarket US market slug. If no suffix is
+     * present the input is returned unchanged.
+     */
+    private slugFromId;
+    protected fetchMarketsImpl(params?: MarketFetchParams): Promise<UnifiedMarket[]>;
+    protected fetchEventsImpl(params: EventFetchParams): Promise<UnifiedEvent[]>;
+    fetchOrderBook(id: string): Promise<OrderBook>;
+    fetchBalance(_address?: string): Promise<Balance[]>;
+    fetchPositions(_address?: string): Promise<Position[]>;
+    fetchMyTrades(params?: MyTradesParams): Promise<UserTrade[]>;
+    fetchOpenOrders(marketId?: string): Promise<Order[]>;
+    fetchOrder(orderId: string): Promise<Order>;
+    buildOrder(params: CreateOrderParams): Promise<BuiltOrder>;
+    submitOrder(built: BuiltOrder): Promise<Order>;
+    createOrder(params: CreateOrderParams): Promise<Order>;
+    cancelOrder(orderId: string): Promise<Order>;
+    /**
+     * Lazily construct the WebSocket wrapper. The underlying SDK factory
+     * requires credentials even for the public market socket, so this
+     * method calls `requireAuth()` up front.
+     */
+    private ensureWs;
+    watchOrderBook(id: string, _limit?: number): Promise<OrderBook>;
+    watchTrades(id: string, _address?: string, _since?: number, _limit?: number): Promise<Trade[]>;
+    close(): Promise<void>;
+}