pmxt-core 2.23.0 → 2.25.0

package/dist/exchanges/polymarket_us/index.js

@@ -0,0 +1,366 @@
+"use strict";
+/**
+ * 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.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PolymarketUSExchange = exports.PolymarketUSNormalizer = void 0;
+const BaseExchange_1 = require("../../BaseExchange");
+const errors_1 = require("../../errors");
+const polymarket_us_1 = require("polymarket-us");
+const config_1 = require("./config");
+const normalizer_1 = require("./normalizer");
+const errors_2 = require("./errors");
+const websocket_1 = require("./websocket");
+const price_1 = require("./price");
+__exportStar(require("./config"), exports);
+__exportStar(require("./price"), exports);
+__exportStar(require("./errors"), exports);
+var normalizer_2 = require("./normalizer");
+Object.defineProperty(exports, "PolymarketUSNormalizer", { enumerable: true, get: function () { return normalizer_2.PolymarketUSNormalizer; } });
+class PolymarketUSExchange extends BaseExchange_1.PredictionMarketExchange {
+    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,
+    };
+    client;
+    normalizer;
+    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.
+     */
+    orderSlugCache = new Map();
+    wsWrapper;
+    constructor(credentials) {
+        super(credentials);
+        this.rateLimit = 100;
+        this.config = (0, config_1.getPolymarketUSConfig)();
+        this.normalizer = new normalizer_1.PolymarketUSNormalizer();
+        this.client = new polymarket_us_1.PolymarketUS({
+            keyId: credentials?.apiKey,
+            secretKey: credentials?.privateKey,
+            apiBaseUrl: this.config.apiUrl,
+            gatewayBaseUrl: this.config.gatewayUrl,
+        });
+    }
+    get name() {
+        return 'PolymarketUS';
+    }
+    // -------------------------------------------------------------------------
+    // Helpers
+    // -------------------------------------------------------------------------
+    requireAuth() {
+        if (!this.credentials?.apiKey || !this.credentials?.privateKey) {
+            throw new errors_1.AuthenticationError('PolymarketUS requires apiKey (keyId) and privateKey (secretKey) credentials.', 'PolymarketUS');
+        }
+    }
+    /**
+     * Wrap any SDK call so SDK errors get translated to PMXT error classes.
+     */
+    async run(fn) {
+        try {
+            return await fn();
+        }
+        catch (err) {
+            throw errors_2.polymarketUSErrorMapper.mapError(err);
+        }
+    }
+    cacheOrder(orderId, marketSlug) {
+        if (orderId && marketSlug) {
+            this.orderSlugCache.set(orderId, marketSlug);
+        }
+    }
+    /**
+     * 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.
+     */
+    slugFromId(id) {
+        if (id.endsWith(':long'))
+            return id.slice(0, -':long'.length);
+        if (id.endsWith(':short'))
+            return id.slice(0, -':short'.length);
+        return id;
+    }
+    // -------------------------------------------------------------------------
+    // Markets / Events
+    // -------------------------------------------------------------------------
+    async fetchMarketsImpl(params) {
+        return this.run(async () => {
+            // Direct slug / id / outcomeId lookup
+            const directSlug = params?.slug ||
+                params?.marketId ||
+                (params?.outcomeId ? this.slugFromId(params.outcomeId) : undefined);
+            if (directSlug) {
+                const resp = await this.client.markets.retrieveBySlug(directSlug);
+                return resp.market ? [this.normalizer.normalizeMarket(resp.market)] : [];
+            }
+            // Markets that belong to a specific event
+            if (params?.eventId) {
+                const eventResp = await this.client.events.retrieveBySlug(params.eventId);
+                return eventResp.event
+                    ? this.normalizer.normalizeMarketsFromEvent(eventResp.event)
+                    : [];
+            }
+            const resp = await this.client.markets.list({
+                active: true,
+                limit: params?.limit ?? 250,
+                offset: params?.offset ?? 0,
+            });
+            let markets = (resp.markets || []).map(m => this.normalizer.normalizeMarket(m));
+            if (params?.query) {
+                const q = params.query.toLowerCase();
+                markets = markets.filter(m => m.title.toLowerCase().includes(q) ||
+                    (m.description || '').toLowerCase().includes(q));
+            }
+            return markets;
+        });
+    }
+    async fetchEventsImpl(params) {
+        return this.run(async () => {
+            const directSlug = params?.eventId || params?.slug;
+            if (directSlug) {
+                const resp = await this.client.events.retrieveBySlug(directSlug);
+                return resp.event ? [this.normalizer.normalizeEvent(resp.event)] : [];
+            }
+            const resp = await this.client.events.list({
+                active: true,
+                limit: params?.limit ?? 100,
+                offset: params?.offset ?? 0,
+            });
+            let events = (resp.events || []).map(e => this.normalizer.normalizeEvent(e));
+            if (params?.query) {
+                const q = params.query.toLowerCase();
+                events = events.filter(e => e.title.toLowerCase().includes(q) ||
+                    (e.description || '').toLowerCase().includes(q));
+            }
+            return events;
+        });
+    }
+    async fetchOrderBook(id) {
+        return this.run(async () => {
+            const slug = this.slugFromId(id);
+            const book = await this.client.markets.book(slug);
+            return this.normalizer.normalizeOrderBook(book, id);
+        });
+    }
+    // -------------------------------------------------------------------------
+    // Account / Portfolio
+    // -------------------------------------------------------------------------
+    async fetchBalance(_address) {
+        this.requireAuth();
+        return this.run(async () => {
+            const resp = await this.client.account.balances();
+            if (!resp.balances || resp.balances.length === 0) {
+                return [];
+            }
+            return this.normalizer.normalizeBalance(resp.balances[0]);
+        });
+    }
+    async fetchPositions(_address) {
+        this.requireAuth();
+        return this.run(async () => {
+            const resp = await this.client.portfolio.positions({});
+            return this.normalizer.normalizePositions(resp.positions || {});
+        });
+    }
+    async fetchMyTrades(params) {
+        this.requireAuth();
+        return this.run(async () => {
+            const resp = await this.client.portfolio.activities({
+                types: ['ACTIVITY_TYPE_TRADE'],
+                limit: params?.limit ?? 100,
+                marketSlug: params?.marketId,
+            });
+            const activities = resp.activities || [];
+            const trades = [];
+            activities.forEach((activity, idx) => {
+                const trade = this.normalizer.normalizeUserTradeFromActivity(activity, idx);
+                if (trade)
+                    trades.push(trade);
+            });
+            return trades;
+        });
+    }
+    // -------------------------------------------------------------------------
+    // Orders
+    // -------------------------------------------------------------------------
+    async fetchOpenOrders(marketId) {
+        this.requireAuth();
+        return this.run(async () => {
+            const resp = await this.client.orders.list({
+                slugs: marketId ? [marketId] : undefined,
+            });
+            const raws = resp.orders || [];
+            return raws.map(raw => {
+                const normalized = this.normalizer.normalizeOrder(raw);
+                this.cacheOrder(normalized.id, raw.marketSlug);
+                return normalized;
+            });
+        });
+    }
+    async fetchOrder(orderId) {
+        this.requireAuth();
+        return this.run(async () => {
+            const resp = await this.client.orders.retrieve(orderId);
+            const raw = resp.order;
+            const normalized = this.normalizer.normalizeOrder(raw);
+            this.cacheOrder(normalized.id, raw.marketSlug);
+            return normalized;
+        });
+    }
+    async buildOrder(params) {
+        const isShort = params.outcomeId.endsWith(':short');
+        let intent;
+        if (params.side === 'buy' && !isShort)
+            intent = 'ORDER_INTENT_BUY_LONG';
+        else if (params.side === 'sell' && !isShort)
+            intent = 'ORDER_INTENT_SELL_LONG';
+        else if (params.side === 'buy' && isShort)
+            intent = 'ORDER_INTENT_BUY_SHORT';
+        else
+            intent = 'ORDER_INTENT_SELL_SHORT';
+        const sdkType = params.type === 'market'
+            ? 'ORDER_TYPE_MARKET'
+            : 'ORDER_TYPE_LIMIT';
+        const sdkParams = {
+            marketSlug: params.marketId,
+            intent,
+            type: sdkType,
+            quantity: params.amount,
+            tif: 'TIME_IN_FORCE_GOOD_TILL_CANCEL',
+        };
+        if (params.type === 'limit') {
+            if (params.price === undefined) {
+                throw new Error('Limit order requires price');
+            }
+            const rounded = (0, price_1.roundToTickSize)(params.price);
+            (0, price_1.validatePriceBounds)(rounded);
+            const longPrice = (0, price_1.toLongSidePrice)(intent, rounded);
+            sdkParams.price = (0, price_1.toAmount)(longPrice);
+        }
+        return {
+            exchange: this.name,
+            params,
+            raw: sdkParams,
+        };
+    }
+    async submitOrder(built) {
+        this.requireAuth();
+        const sdkParams = built.raw;
+        const response = await this.run(() => this.client.orders.create(sdkParams));
+        const newId = response.id;
+        this.cacheOrder(newId, built.params.marketId);
+        try {
+            return await this.fetchOrder(newId);
+        }
+        catch {
+            // Order may not yet be visible via retrieve. Fall back to a
+            // synthetic Order built from the original params.
+            return {
+                id: newId,
+                marketId: built.params.marketId,
+                outcomeId: built.params.outcomeId,
+                side: built.params.side,
+                type: built.params.type,
+                price: built.params.price ?? 0,
+                amount: built.params.amount,
+                status: 'open',
+                filled: 0,
+                remaining: built.params.amount,
+                timestamp: Date.now(),
+            };
+        }
+    }
+    async createOrder(params) {
+        const built = await this.buildOrder(params);
+        return this.submitOrder(built);
+    }
+    async cancelOrder(orderId) {
+        this.requireAuth();
+        let slug = this.orderSlugCache.get(orderId);
+        if (!slug) {
+            // Populate the cache by fetching the order first
+            const fetched = await this.fetchOrder(orderId);
+            slug = this.orderSlugCache.get(orderId) || fetched.marketId;
+        }
+        await this.run(() => this.client.orders.cancel(orderId, { marketSlug: slug }));
+        return this.fetchOrder(orderId);
+    }
+    // -------------------------------------------------------------------------
+    // WebSocket Streaming
+    // -------------------------------------------------------------------------
+    /**
+     * Lazily construct the WebSocket wrapper. The underlying SDK factory
+     * requires credentials even for the public market socket, so this
+     * method calls `requireAuth()` up front.
+     */
+    ensureWs() {
+        this.requireAuth();
+        if (!this.wsWrapper) {
+            this.wsWrapper = new websocket_1.PolymarketUSWebSocket(this.client, this.normalizer);
+        }
+        return this.wsWrapper;
+    }
+    async watchOrderBook(id, _limit) {
+        return this.run(() => this.ensureWs().watchOrderBook(id));
+    }
+    async watchTrades(id, _address, _since, _limit) {
+        return this.run(() => this.ensureWs().watchTrades(id));
+    }
+    // -------------------------------------------------------------------------
+    // Lifecycle
+    // -------------------------------------------------------------------------
+    async close() {
+        if (this.wsWrapper) {
+            await this.wsWrapper.close();
+            this.wsWrapper = undefined;
+        }
+    }
+}
+exports.PolymarketUSExchange = PolymarketUSExchange;

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

@@ -0,0 +1,8 @@
+/**
+ * Integration tests for PolymarketUSExchange.
+ *
+ * The `polymarket-us` SDK is fully mocked here so the tests run without
+ * touching the network. Each test instantiates a fresh exchange (and
+ * therefore a fresh mock client) so per-test mock setup is independent.
+ */
+export {};

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

@@ -0,0 +1,237 @@
+"use strict";
+/**
+ * Integration tests for PolymarketUSExchange.
+ *
+ * The `polymarket-us` SDK is fully mocked here so the tests run without
+ * touching the network. Each test instantiates a fresh exchange (and
+ * therefore a fresh mock client) so per-test mock setup is independent.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+jest.mock('polymarket-us', () => {
+    class PolymarketUSError extends Error {
+    }
+    class APIError extends PolymarketUSError {
+        status;
+        constructor(status, message) {
+            super(message);
+            this.status = status;
+        }
+    }
+    class AuthenticationError extends APIError {
+        constructor(m = 'auth') { super(401, m); }
+    }
+    class BadRequestError extends APIError {
+        constructor(m = 'bad request') { super(400, m); }
+    }
+    class NotFoundError extends APIError {
+        constructor(m = 'not found') { super(404, m); }
+    }
+    class RateLimitError extends APIError {
+        constructor(m = 'rate limit') { super(429, m); }
+    }
+    class InternalServerError extends APIError {
+        constructor(m = 'server') { super(500, m); }
+    }
+    const PolymarketUS = jest.fn().mockImplementation(() => ({
+        markets: {
+            list: jest.fn(),
+            book: jest.fn(),
+            retrieveBySlug: jest.fn(),
+        },
+        events: {
+            list: jest.fn(),
+            retrieveBySlug: jest.fn(),
+        },
+        orders: {
+            list: jest.fn(),
+            retrieve: jest.fn(),
+            create: jest.fn(),
+            cancel: jest.fn(),
+        },
+        portfolio: {
+            positions: jest.fn(),
+            activities: jest.fn(),
+        },
+        account: {
+            balances: jest.fn(),
+        },
+    }));
+    return {
+        PolymarketUS,
+        PolymarketUSError,
+        APIError,
+        AuthenticationError,
+        BadRequestError,
+        NotFoundError,
+        RateLimitError,
+        InternalServerError,
+    };
+});
+const index_1 = require("./index");
+const errors_1 = require("../../errors");
+const polymarket_us_1 = require("polymarket-us");
+const CREDS = { apiKey: 'k1', privateKey: 's1' };
+function getClient(exchange) {
+    return exchange.client;
+}
+function makeMarketDetail(slug = 'btc-100k') {
+    return {
+        id: 1,
+        slug,
+        title: `Market ${slug}`,
+        outcome: 'binary',
+        description: 'desc',
+        active: true,
+        closed: false,
+        liquidity: 100,
+        volume: 1000,
+        eventSlug: 'evt-1',
+    };
+}
+function makeSdkOrder(overrides = {}) {
+    return {
+        id: 'order-1',
+        marketSlug: 'btc-100k',
+        side: 'ORDER_SIDE_BUY',
+        type: 'ORDER_TYPE_LIMIT',
+        price: { value: '0.55', currency: 'USD' },
+        quantity: 10,
+        cumQuantity: 0,
+        leavesQuantity: 10,
+        tif: 'TIME_IN_FORCE_GOOD_TILL_CANCEL',
+        intent: 'ORDER_INTENT_BUY_LONG',
+        state: 'ORDER_STATE_NEW',
+        ...overrides,
+    };
+}
+describe('PolymarketUSExchange', () => {
+    describe('construction', () => {
+        it('constructs without credentials but rejects auth-required calls', async () => {
+            const ex = new index_1.PolymarketUSExchange();
+            await expect(ex.fetchBalance()).rejects.toBeInstanceOf(errors_1.AuthenticationError);
+        });
+        it('constructs with credentials and exposes the unified name', () => {
+            const ex = new index_1.PolymarketUSExchange(CREDS);
+            expect(ex.name).toBe('PolymarketUS');
+        });
+    });
+    describe('fetchMarkets', () => {
+        it('returns normalized markets from markets.list', async () => {
+            const ex = new index_1.PolymarketUSExchange(CREDS);
+            const client = getClient(ex);
+            client.markets.list.mockResolvedValue({
+                markets: [makeMarketDetail('btc-100k'), makeMarketDetail('eth-5k')],
+            });
+            const result = await ex.fetchMarkets();
+            expect(client.markets.list).toHaveBeenCalledWith({
+                active: true,
+                limit: 250,
+                offset: 0,
+            });
+            expect(result).toHaveLength(2);
+            expect(result[0].marketId).toBe('btc-100k');
+            expect(result[1].marketId).toBe('eth-5k');
+        });
+        it('uses retrieveBySlug for direct slug lookup', async () => {
+            const ex = new index_1.PolymarketUSExchange(CREDS);
+            const client = getClient(ex);
+            client.markets.retrieveBySlug.mockResolvedValue({
+                market: makeMarketDetail('btc-100k'),
+            });
+            const result = await ex.fetchMarkets({ slug: 'btc-100k' });
+            expect(client.markets.retrieveBySlug).toHaveBeenCalledWith('btc-100k');
+            expect(result).toHaveLength(1);
+            expect(result[0].marketId).toBe('btc-100k');
+        });
+    });
+    describe('fetchOrderBook', () => {
+        it('normalizes a market book', async () => {
+            const ex = new index_1.PolymarketUSExchange(CREDS);
+            const client = getClient(ex);
+            client.markets.book.mockResolvedValue({
+                marketSlug: 'btc-100k',
+                bids: [{ px: { value: '0.55', currency: 'USD' }, qty: '10' }],
+                offers: [{ px: { value: '0.57', currency: 'USD' }, qty: '5' }],
+                state: 'MARKET_STATE_OPEN',
+                transactTime: '2024-01-01T00:00:00Z',
+            });
+            const book = await ex.fetchOrderBook('btc-100k');
+            expect(client.markets.book).toHaveBeenCalledWith('btc-100k');
+            expect(book.bids).toEqual([{ price: 0.55, size: 10 }]);
+            expect(book.asks).toEqual([{ price: 0.57, size: 5 }]);
+        });
+    });
+    describe('buildOrder', () => {
+        it('builds a BUY LONG limit order at the user price', async () => {
+            const ex = new index_1.PolymarketUSExchange(CREDS);
+            const built = await ex.buildOrder({
+                marketId: 'btc-100k',
+                outcomeId: 'btc-100k:long',
+                side: 'buy',
+                type: 'limit',
+                amount: 10,
+                price: 0.55,
+            });
+            const raw = built.raw;
+            expect(raw.intent).toBe('ORDER_INTENT_BUY_LONG');
+            expect(raw.type).toBe('ORDER_TYPE_LIMIT');
+            expect(raw.marketSlug).toBe('btc-100k');
+            expect(raw.quantity).toBe(10);
+            expect(raw.price.value).toBe('0.550');
+        });
+        it('builds a BUY SHORT limit order using long-side price conversion', async () => {
+            const ex = new index_1.PolymarketUSExchange(CREDS);
+            const built = await ex.buildOrder({
+                marketId: 'btc-100k',
+                outcomeId: 'btc-100k:short',
+                side: 'buy',
+                type: 'limit',
+                amount: 10,
+                price: 0.40,
+            });
+            const raw = built.raw;
+            expect(raw.intent).toBe('ORDER_INTENT_BUY_SHORT');
+            expect(raw.price.value).toBe('0.600');
+        });
+    });
+    describe('cancelOrder', () => {
+        it('uses cached marketSlug when available', async () => {
+            const ex = new index_1.PolymarketUSExchange(CREDS);
+            const client = getClient(ex);
+            // Pre-populate cache by listing open orders
+            client.orders.list.mockResolvedValue({
+                orders: [makeSdkOrder({ id: 'order-123', marketSlug: 'btc-100k' })],
+            });
+            await ex.fetchOpenOrders();
+            client.orders.cancel.mockResolvedValue(undefined);
+            client.orders.retrieve.mockResolvedValue({
+                order: makeSdkOrder({ id: 'order-123', state: 'ORDER_STATE_CANCELED' }),
+            });
+            await ex.cancelOrder('order-123');
+            expect(client.orders.cancel).toHaveBeenCalledWith('order-123', {
+                marketSlug: 'btc-100k',
+            });
+        });
+        it('fetches the order first when slug is not cached', async () => {
+            const ex = new index_1.PolymarketUSExchange(CREDS);
+            const client = getClient(ex);
+            client.orders.retrieve.mockResolvedValue({
+                order: makeSdkOrder({ id: 'order-456', marketSlug: 'eth-5k' }),
+            });
+            client.orders.cancel.mockResolvedValue(undefined);
+            await ex.cancelOrder('order-456');
+            expect(client.orders.retrieve).toHaveBeenCalledWith('order-456');
+            expect(client.orders.cancel).toHaveBeenCalledWith('order-456', {
+                marketSlug: 'eth-5k',
+            });
+        });
+    });
+    describe('error mapping', () => {
+        it('translates SDK AuthenticationError into PMXT AuthenticationError', async () => {
+            const ex = new index_1.PolymarketUSExchange(CREDS);
+            const client = getClient(ex);
+            client.account.balances.mockRejectedValue(new polymarket_us_1.AuthenticationError('bad creds'));
+            await expect(ex.fetchBalance()).rejects.toBeInstanceOf(errors_1.AuthenticationError);
+        });
+    });
+});

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

@@ -0,0 +1,55 @@
+import type { Event as SdkEvent, MarketDetail, MarketBook, Order as SdkOrder, UserPosition, UserBalance, Activity } from 'polymarket-us';
+import { UnifiedMarket, UnifiedEvent, OrderBook, Order, Position, Balance, UserTrade } from '../../types';
+export declare class PolymarketUSNormalizer {
+    /**
+     * Normalize a single MarketDetail into a UnifiedMarket.
+     * The slug is the canonical PMXT marketId for Polymarket US.
+     */
+    normalizeMarket(detail: MarketDetail): UnifiedMarket;
+    /**
+     * Flatten an SDK Event's markets into UnifiedMarkets.
+     * Each market inherits the parent event's metadata.
+     */
+    normalizeMarketsFromEvent(event: SdkEvent): UnifiedMarket[];
+    /**
+     * Normalize an SDK Event into a UnifiedEvent.
+     */
+    normalizeEvent(event: SdkEvent): UnifiedEvent;
+    /**
+     * Internal helper that builds a UnifiedMarket from the gateway's real
+     * runtime shape. Handles inheritance from a parent event when the market
+     * is nested (fields like category/tags/endDate fall back to the parent).
+     */
+    private buildUnifiedMarket;
+    /**
+     * Normalize a MarketBook into a PMXT OrderBook.
+     *
+     * IMPORTANT: Polymarket US books are quoted in long-side prices. PMXT
+     * exposes the book as the LONG side directly:
+     *   - bids: levels where someone is bidding to BUY LONG (price = fromAmount(level.px))
+     *   - asks: levels where someone is offering to SELL LONG (price = fromAmount(level.px))
+     * The implicit short-side book is `1 - longPrice` for each level. Callers
+     * needing the short-side view must invert prices themselves.
+     */
+    normalizeOrderBook(book: MarketBook, _marketId: string): OrderBook;
+    /**
+     * Normalize an SDK Order into a PMXT Order.
+     * Prices are converted from long-side to user-facing using the order's intent.
+     */
+    normalizeOrder(order: SdkOrder): Order;
+    /**
+     * Normalize the SDK's positions map into an array of PMXT Positions.
+     * Positive netPosition -> long outcome; negative -> short outcome.
+     */
+    normalizePositions(positions: Record<string, UserPosition>): Position[];
+    /**
+     * Normalize a UserBalance into PMXT Balance[].
+     * Locked = total - available (clamped to >= 0).
+     */
+    normalizeBalance(balance: UserBalance): Balance[];
+    /**
+     * Normalize a single Activity into a UserTrade.
+     * Returns null for non-trade activities.
+     */
+    normalizeUserTradeFromActivity(activity: Activity, _index: number): UserTrade | null;
+}