@catalyst-team/poly-sdk 0.4.5 → 0.4.7

package/dist/src/services/order-manager.js

@@ -8,7 +8,125 @@
  * - Auto-validates orders before submission (market state, balance, precision)
  * - Auto-watches orders after creation
  *
- * Platform-Specific Implementation:
+ * ============================================================================
+ * ORDER TYPES AND LIFECYCLE
+ * ============================================================================
+ *
+ * Polymarket supports 4 order types, each with different lifecycle patterns:
+ *
+ * ┌─────────────────────────────────────────────────────────────────────────┐
+ * │ LIMIT ORDERS (createOrder)                                             │
+ * ├─────────────────────────────────────────────────────────────────────────┤
+ * │                                                                         │
+ * │ GTC (Good Till Cancelled) - Default limit order                        │
+ * │ ─────────────────────────────────────────────────────────────────────── │
+ * │ Lifecycle: PENDING → OPEN → PARTIALLY_FILLED* → FILLED or CANCELLED    │
+ * │ Duration:  seconds → minutes → hours → days (until filled/cancelled)   │
+ * │                                                                         │
+ * │   ┌─────────┐    placed     ┌──────┐   partial    ┌──────────────────┐ │
+ * │   │ PENDING │ ───────────→ │ OPEN │ ──────────→ │ PARTIALLY_FILLED │ │
+ * │   └─────────┘              └──────┘             └──────────────────┘ │
+ * │        │                       │                        │            │
+ * │        │ reject                │ cancel                 │ fill/cancel│
+ * │        ↓                       ↓                        ↓            │
+ * │   ┌──────────┐           ┌───────────┐            ┌────────┐        │
+ * │   │ REJECTED │           │ CANCELLED │            │ FILLED │        │
+ * │   └──────────┘           └───────────┘            └────────┘        │
+ * │                                                                       │
+ * │ GTD (Good Till Date) - Limit order with expiration                   │
+ * │ ─────────────────────────────────────────────────────────────────────  │
+ * │ Lifecycle: Same as GTC, but auto-expires at specified time           │
+ * │ Duration:  seconds → specified expiration time                        │
+ * │ Additional terminal state: EXPIRED (when expiration time reached)    │
+ * │                                                                         │
+ * ├─────────────────────────────────────────────────────────────────────────┤
+ * │ MARKET ORDERS (createMarketOrder)                                      │
+ * ├─────────────────────────────────────────────────────────────────────────┤
+ * │                                                                         │
+ * │ FOK (Fill Or Kill) - Must fill completely or cancel immediately       │
+ * │ ───────────────────────────────────────────────────────────────────────│
+ * │ Lifecycle: PENDING → FILLED (success) or PENDING → CANCELLED (fail)   │
+ * │ Duration:  milliseconds (instant execution)                           │
+ * │ Key: NO partial fills - all or nothing                                │
+ * │                                                                         │
+ * │   ┌─────────┐    full fill    ┌────────┐                              │
+ * │   │ PENDING │ ─────────────→ │ FILLED │                              │
+ * │   └─────────┘                └────────┘                              │
+ * │        │                                                               │
+ * │        │ cannot fill completely                                        │
+ * │        ↓                                                               │
+ * │   ┌───────────┐                                                        │
+ * │   │ CANCELLED │  (filledSize = 0)                                     │
+ * │   └───────────┘                                                        │
+ * │                                                                         │
+ * │ FAK (Fill And Kill) - Fill what's available, cancel the rest          │
+ * │ ───────────────────────────────────────────────────────────────────────│
+ * │ Lifecycle: PENDING → FILLED or PENDING → CANCELLED (with partial fill)│
+ * │ Duration:  milliseconds (instant execution)                           │
+ * │ Key: May have partial fills, remainder is cancelled immediately       │
+ * │                                                                         │
+ * │   ┌─────────┐    full fill    ┌────────┐                              │
+ * │   │ PENDING │ ─────────────→ │ FILLED │                              │
+ * │   └─────────┘                └────────┘                              │
+ * │        │                                                               │
+ * │        │ partial fill + cancel rest                                    │
+ * │        ↓                                                               │
+ * │   ┌───────────┐                                                        │
+ * │   │ CANCELLED │  (filledSize > 0, cancelledSize > 0)                  │
+ * │   └───────────┘                                                        │
+ * │                                                                         │
+ * └─────────────────────────────────────────────────────────────────────────┘
+ *
+ * ============================================================================
+ * WHY ORDERMANAGER SUPPORTS ALL ORDER TYPES
+ * ============================================================================
+ *
+ * The key insight is that despite different lifecycles, all order types share
+ * the same underlying status model and event stream:
+ *
+ * 1. UNIFIED STATUS MODEL
+ *    All orders use the same OrderStatus enum: PENDING, OPEN, PARTIALLY_FILLED,
+ *    FILLED, CANCELLED, EXPIRED. The difference is which transitions are valid
+ *    and how quickly they occur.
+ *
+ * 2. SAME WEBSOCKET/POLLING EVENTS
+ *    RealtimeServiceV2's `clob_user` topic emits the same USER_ORDER and
+ *    USER_TRADE events for all order types. The eventType field indicates:
+ *    - PLACEMENT: Order entered the system
+ *    - UPDATE: Order was modified (fill, partial fill)
+ *    - CANCELLATION: Order was cancelled
+ *
+ * 3. STATUS TRANSITION VALIDATION
+ *    The isValidStatusTransition() function handles all valid paths:
+ *    - GTC/GTD: PENDING → OPEN → PARTIALLY_FILLED → FILLED/CANCELLED
+ *    - FOK: PENDING → FILLED or PENDING → CANCELLED (no PARTIALLY_FILLED)
+ *    - FAK: PENDING → FILLED or PENDING → CANCELLED (filledSize may be > 0)
+ *
+ * 4. TERMINAL STATE HANDLING
+ *    All order types eventually reach a terminal state (FILLED, CANCELLED,
+ *    EXPIRED). OrderManager auto-unwatches orders when they reach terminal
+ *    states, regardless of order type.
+ *
+ * 5. FILL EVENT DETECTION
+ *    Whether fills come rapidly (FOK/FAK) or slowly (GTC/GTD), the same
+ *    fill detection logic works: compare filledSize changes and emit
+ *    order_partially_filled or order_filled events.
+ *
+ * Key differences in behavior:
+ * ┌─────────────┬─────────────────────────────────────────────────────────┐
+ * │ Order Type  │ Behavior                                                │
+ * ├─────────────┼─────────────────────────────────────────────────────────┤
+ * │ GTC/GTD     │ May emit many events over long time (hours/days)       │
+ * │             │ watchOrder() monitors until filled/cancelled/expired    │
+ * ├─────────────┼─────────────────────────────────────────────────────────┤
+ * │ FOK/FAK     │ Emit 1-2 events almost instantly (milliseconds)        │
+ * │             │ watchOrder() monitors briefly, auto-unwatches quickly   │
+ * └─────────────┴─────────────────────────────────────────────────────────┘
+ *
+ * ============================================================================
+ * PLATFORM-SPECIFIC IMPLEMENTATION
+ * ============================================================================
+ *
  * This is a Polymarket-specific implementation. The design allows future extraction
  * to interfaces if supporting multiple prediction markets, but for now we focus on
  * clean encapsulation with Polymarket details in private methods.
@@ -36,13 +154,29 @@
  *   console.log(`On-chain settled: ${event.transactionHash}`);
  * });
  *
- * // Create order (auto-validates + auto-watches)
- * const result = await orderMgr.createOrder({
+ * // Create limit order (GTC by default)
+ * const limitResult = await orderMgr.createOrder({
  *   tokenId: '0x...',
  *   side: 'BUY',
  *   price: 0.52,
  *   size: 100,
  * });
+ *
+ * // Create market order (FOK - fill completely or cancel)
+ * const fokResult = await orderMgr.createMarketOrder({
+ *   tokenId: '0x...',
+ *   side: 'BUY',
+ *   amount: 50, // $50 USDC
+ *   orderType: 'FOK',
+ * });
+ *
+ * // Create market order (FAK - fill what's available)
+ * const fakResult = await orderMgr.createMarketOrder({
+ *   tokenId: '0x...',
+ *   side: 'BUY',
+ *   amount: 50,
+ *   orderType: 'FAK',
+ * });
  * ```
  */
 import { EventEmitter } from 'events';
@@ -53,6 +187,219 @@ import { createUnifiedCache } from '../core/unified-cache.js';
 import { OrderStatus } from '../core/types.js';
 import { isTerminalStatus, isValidStatusTransition } from '../core/order-status.js';
 import { PolymarketError, ErrorCode } from '../core/errors.js';
+/**
+ * Internal implementation of OrderHandle.
+ *
+ * Lifecycle:
+ * 1. Constructor receives orderManager ref and an executor function
+ * 2. Status starts at 'created'
+ * 3. Executor is invoked immediately (fire-and-forget)
+ * 4. On success: stores orderId, subscribes to OrderManager events
+ * 5. On rejection: transitions to 'rejected', resolves promise
+ * 6. On terminal events: resolves promise, removes listeners
+ */
+export class OrderHandleImpl {
+    orderManager;
+    executor;
+    _orderId;
+    _status = 'created';
+    _fills = [];
+    _order = null;
+    _reason;
+    _resolve;
+    _promise;
+    _handlers = new Map();
+    _eventCleanup = null;
+    constructor(orderManager, executor) {
+        this.orderManager = orderManager;
+        this.executor = executor;
+        this._promise = new Promise((resolve) => {
+            this._resolve = resolve;
+        });
+        // Fire-and-forget execution
+        this.execute();
+    }
+    // ===== PromiseLike implementation =====
+    then(onfulfilled, onrejected) {
+        return this._promise.then(onfulfilled, onrejected);
+    }
+    // ===== Chainable lifecycle callbacks =====
+    onAccepted(handler) {
+        this.addHandler('accepted', handler);
+        return this;
+    }
+    onPartialFill(handler) {
+        this.addHandler('partial_fill', handler);
+        return this;
+    }
+    onFilled(handler) {
+        this.addHandler('filled', handler);
+        return this;
+    }
+    onRejected(handler) {
+        this.addHandler('rejected', handler);
+        return this;
+    }
+    onCancelled(handler) {
+        this.addHandler('cancelled', handler);
+        return this;
+    }
+    onExpired(handler) {
+        this.addHandler('expired', handler);
+        return this;
+    }
+    // ===== Operations =====
+    async cancel() {
+        if (!this._orderId)
+            return false;
+        if (this.isTerminal())
+            return false;
+        const result = await this.orderManager.cancelOrder(this._orderId);
+        return result.success;
+    }
+    // ===== State query =====
+    get orderId() {
+        return this._orderId;
+    }
+    get status() {
+        return this._status;
+    }
+    // ===== Private implementation =====
+    async execute() {
+        try {
+            const result = await this.executor();
+            if (!result.success || !result.orderId) {
+                // Order rejected by API or validation
+                this._status = 'rejected';
+                this._reason = result.errorMsg || 'Order rejected';
+                this.invokeHandlers('rejected', this._reason);
+                this._resolve({
+                    status: 'rejected',
+                    order: null,
+                    fills: [],
+                    reason: this._reason,
+                });
+                return;
+            }
+            // Store orderId and subscribe to events
+            this._orderId = result.orderId;
+            this.subscribeToEvents();
+        }
+        catch (error) {
+            // Unexpected error during execution
+            this._status = 'rejected';
+            this._reason = error instanceof Error ? error.message : String(error);
+            this.invokeHandlers('rejected', this._reason);
+            this._resolve({
+                status: 'rejected',
+                order: null,
+                fills: [],
+                reason: this._reason,
+            });
+        }
+    }
+    subscribeToEvents() {
+        const onOpened = (order) => {
+            if (order.id !== this._orderId)
+                return;
+            this._status = 'open';
+            this._order = order;
+            this.invokeHandlers('accepted', order);
+        };
+        const onPartialFill = (fill) => {
+            if (fill.orderId !== this._orderId)
+                return;
+            this._status = 'partially_filled';
+            this._order = fill.order;
+            this._fills.push(fill);
+            this.invokeHandlers('partial_fill', fill);
+        };
+        const onFilled = (fill) => {
+            if (fill.orderId !== this._orderId)
+                return;
+            this._status = 'filled';
+            this._order = fill.order;
+            this._fills.push(fill);
+            this.invokeHandlers('filled', fill);
+            this.resolveTerminal('filled');
+        };
+        const onCancelled = (event) => {
+            if (event.orderId !== this._orderId)
+                return;
+            this._status = 'cancelled';
+            this._order = event.order;
+            this.invokeHandlers('cancelled', event.order);
+            this.resolveTerminal('cancelled', 'Order cancelled');
+        };
+        const onExpired = (event) => {
+            if (event.orderId !== this._orderId)
+                return;
+            this._status = 'expired';
+            this._order = event.order;
+            this.invokeHandlers('expired', event.order);
+            this.resolveTerminal('expired', 'Order expired');
+        };
+        const onRejected = (event) => {
+            if (event.orderId !== this._orderId)
+                return;
+            this._status = 'rejected';
+            this._reason = event.reason;
+            this.invokeHandlers('rejected', event.reason);
+            this.resolveTerminal('rejected', event.reason);
+        };
+        this.orderManager.on('order_opened', onOpened);
+        this.orderManager.on('order_partially_filled', onPartialFill);
+        this.orderManager.on('order_filled', onFilled);
+        this.orderManager.on('order_cancelled', onCancelled);
+        this.orderManager.on('order_expired', onExpired);
+        this.orderManager.on('order_rejected', onRejected);
+        this._eventCleanup = () => {
+            this.orderManager.removeListener('order_opened', onOpened);
+            this.orderManager.removeListener('order_partially_filled', onPartialFill);
+            this.orderManager.removeListener('order_filled', onFilled);
+            this.orderManager.removeListener('order_cancelled', onCancelled);
+            this.orderManager.removeListener('order_expired', onExpired);
+            this.orderManager.removeListener('order_rejected', onRejected);
+        };
+    }
+    resolveTerminal(status, reason) {
+        this.cleanup();
+        this._resolve({
+            status,
+            order: this._order,
+            fills: this._fills,
+            reason,
+        });
+    }
+    cleanup() {
+        if (this._eventCleanup) {
+            this._eventCleanup();
+            this._eventCleanup = null;
+        }
+    }
+    isTerminal() {
+        return this._status === 'filled' || this._status === 'cancelled' || this._status === 'rejected' || this._status === 'expired';
+    }
+    addHandler(event, handler) {
+        if (!this._handlers.has(event)) {
+            this._handlers.set(event, []);
+        }
+        this._handlers.get(event).push(handler);
+    }
+    invokeHandlers(event, ...args) {
+        const handlers = this._handlers.get(event);
+        if (!handlers)
+            return;
+        for (const handler of handlers) {
+            try {
+                handler(...args);
+            }
+            catch {
+                // Swallow handler errors to avoid breaking the lifecycle
+            }
+        }
+    }
+}
 // ============================================================================
 // OrderManager Implementation
 // ============================================================================
@@ -75,7 +422,10 @@ export class OrderManager extends EventEmitter {
         this.config = {
             ...config,
             chainId: config.chainId ?? 137,
-            mode: config.mode ?? 'hybrid',
+            // Bug 24 fix: Default to 'websocket' mode instead of 'hybrid'
+            // Polling mechanism can update watched orders with incorrect tokenId,
+            // causing fill events to be processed with wrong token type
+            mode: config.mode ?? 'websocket',
             pollingInterval: config.pollingInterval ?? 5000,
             polygonRpcUrl: config.polygonRpcUrl ?? 'https://polygon-rpc.com',
         };
@@ -173,8 +523,13 @@ export class OrderManager extends EventEmitter {
         // Submit order via TradingService
         const result = await this.tradingService.createLimitOrder(params);
         if (result.success && result.orderId) {
-            // Auto-watch the order
-            this.watchOrder(result.orderId, metadata);
+            // Auto-watch the order with initial order info (Bug 24 fix)
+            this.watchOrder(result.orderId, metadata, {
+                tokenId: params.tokenId,
+                side: params.side,
+                price: params.price,
+                size: params.size,
+            });
             // Emit order_created event
             this.emit('order_created', {
                 id: result.orderId,
@@ -191,6 +546,73 @@ export class OrderManager extends EventEmitter {
         }
         return result;
     }
+    /**
+     * Create and submit a market order (FOK or FAK)
+     *
+     * Market order lifecycle:
+     * - FOK (Fill Or Kill): Must fill completely or cancels immediately
+     *   PENDING → FILLED (success) or PENDING → CANCELLED (failed to fill)
+     * - FAK (Fill And Kill): Fills what it can, cancels the rest
+     *   PENDING → PARTIALLY_FILLED + CANCELLED (partial) or PENDING → FILLED (complete)
+     *
+     * Auto-validates (Polymarket-specific):
+     * - Minimum value ($1)
+     *
+     * Auto-watches: Starts monitoring immediately after creation
+     * Note: Market orders typically complete very quickly (within seconds)
+     *
+     * @param params Market order parameters
+     * @param metadata Optional metadata for tracking
+     * @returns Order result with orderId or error
+     */
+    async createMarketOrder(params, metadata) {
+        this.ensureInitialized();
+        // Validate market order (Polymarket-specific checks)
+        try {
+            await this.validateMarketOrder(params);
+        }
+        catch (error) {
+            const rejectEvent = {
+                params: params, // MarketOrderParams is compatible enough
+                reason: error instanceof Error ? error.message : String(error),
+                timestamp: Date.now(),
+            };
+            this.emit('order_rejected', rejectEvent);
+            return {
+                success: false,
+                errorMsg: rejectEvent.reason,
+            };
+        }
+        // Submit market order via TradingService
+        const result = await this.tradingService.createMarketOrder(params);
+        if (result.success && result.orderId) {
+            // Auto-watch the order with initial order info (Bug 24 fix)
+            this.watchOrder(result.orderId, {
+                ...metadata,
+                orderType: params.orderType || 'FOK', // Track order type for lifecycle handling
+            }, {
+                tokenId: params.tokenId,
+                side: params.side,
+                price: params.price,
+                size: params.amount,
+            });
+            // Emit order_created event
+            this.emit('order_created', {
+                id: result.orderId,
+                status: OrderStatus.PENDING,
+                tokenId: params.tokenId,
+                side: params.side,
+                price: params.price || 0, // Market orders may not have a fixed price
+                originalSize: params.amount, // For market orders, amount is in USDC
+                filledSize: 0,
+                remainingSize: params.amount,
+                associateTrades: [],
+                createdAt: Date.now(),
+                orderType: params.orderType || 'FOK',
+            });
+        }
+        return result;
+    }
     /**
      * Cancel an order
      * Auto-unwatches after cancellation
@@ -204,6 +626,21 @@ export class OrderManager extends EventEmitter {
         }
         return result;
     }
+    /**
+     * Cancel all open orders for this wallet.
+     * Useful for cleanup on strategy shutdown.
+     */
+    async cancelAllOrders() {
+        this.ensureInitialized();
+        const result = await this.tradingService.cancelAllOrders();
+        if (result.success) {
+            // Unwatch all orders
+            for (const orderId of this.watchedOrders.keys()) {
+                this.unwatchOrder(orderId);
+            }
+        }
+        return result;
+    }
     /**
      * Get order details
      * Fetches from TradingService (CLOB API)
@@ -228,36 +665,93 @@ export class OrderManager extends EventEmitter {
         return result;
     }
     // ============================================================================
+    // Public API - OrderHandle (Fluent Lifecycle)
+    // ============================================================================
+    /**
+     * Place a limit order and return a fluent OrderHandle.
+     *
+     * The handle is PromiseLike - await it for the terminal result.
+     * Chain lifecycle callbacks for real-time updates.
+     *
+     * @param params Limit order parameters
+     * @param metadata Optional metadata for tracking
+     * @returns OrderHandle - chainable, awaitable order lifecycle
+     *
+     * @example
+     * ```typescript
+     * const handle = orderManager.placeOrder({
+     *   tokenId: '0x...',
+     *   side: 'BUY',
+     *   price: 0.52,
+     *   size: 100,
+     * });
+     *
+     * handle
+     *   .onAccepted((order) => console.log('Live:', order.id))
+     *   .onFilled((fill) => console.log('Done!'));
+     *
+     * const result = await handle;
+     * ```
+     */
+    placeOrder(params, metadata) {
+        return new OrderHandleImpl(this, () => this.createOrder(params, metadata));
+    }
+    /**
+     * Place a market order (FOK/FAK) and return a fluent OrderHandle.
+     *
+     * @param params Market order parameters
+     * @param metadata Optional metadata for tracking
+     * @returns OrderHandle - chainable, awaitable order lifecycle
+     *
+     * @example
+     * ```typescript
+     * const result = await orderManager.placeMarketOrder({
+     *   tokenId: '0x...',
+     *   side: 'BUY',
+     *   amount: 50,
+     *   orderType: 'FOK',
+     * });
+     * console.log(result.status); // 'filled' or 'cancelled'
+     * ```
+     */
+    placeMarketOrder(params, metadata) {
+        return new OrderHandleImpl(this, () => this.createMarketOrder(params, metadata));
+    }
+    // ============================================================================
     // Public API - Order Monitoring
     // ============================================================================
     /**
-     * Manually watch an order
-     * Used for monitoring externally-created orders
+     * Watch an order by ID
      *
-     * @param orderId Order ID to watch
-     * @param metadata Optional metadata
+     * @param orderId - Order ID to watch
+     * @param metadata - Optional metadata for strategy context
+     * @param initialOrderInfo - Optional initial order info (tokenId, side, price, size)
+     *                           to avoid relying on polling for accurate token type
      */
-    watchOrder(orderId, metadata) {
+    watchOrder(orderId, metadata, initialOrderInfo) {
         if (this.watchedOrders.has(orderId)) {
             return; // Already watching
         }
         // Create initial watched state
+        // Bug 24 fix: Use initialOrderInfo if provided to ensure correct tokenId
         const watched = {
             orderId,
             order: {
                 id: orderId,
                 status: OrderStatus.PENDING,
-                tokenId: '',
-                side: 'BUY',
-                price: 0,
-                originalSize: 0,
+                tokenId: initialOrderInfo?.tokenId || '',
+                side: initialOrderInfo?.side || 'BUY',
+                price: initialOrderInfo?.price || 0,
+                originalSize: initialOrderInfo?.size || 0,
                 filledSize: 0,
-                remainingSize: 0,
+                remainingSize: initialOrderInfo?.size || 0,
                 associateTrades: [],
                 createdAt: Date.now(),
             },
             metadata,
             lastStatus: OrderStatus.PENDING,
+            // Bug 24 fix: Store initialTokenId to protect from polling overwrites
+            initialTokenId: initialOrderInfo?.tokenId,
         };
         this.watchedOrders.set(orderId, watched);
         // Start monitoring based on mode
@@ -325,6 +819,22 @@ export class OrderManager extends EventEmitter {
         // Note: Balance and market state checks would require additional service dependencies
         // For now, we rely on TradingService validation
     }
+    /**
+     * Validate market order parameters before submission
+     * Market orders have simpler validation than limit orders
+     */
+    async validateMarketOrder(params) {
+        // 1. Minimum value validation (Polymarket: $1)
+        if (params.amount < 1) {
+            throw new PolymarketError(ErrorCode.ORDER_REJECTED, `Order amount must be at least $1 (got $${params.amount.toFixed(2)})`);
+        }
+        // 2. Validate order type if specified
+        if (params.orderType && !['FOK', 'FAK'].includes(params.orderType)) {
+            throw new PolymarketError(ErrorCode.ORDER_REJECTED, `Invalid market order type: ${params.orderType}. Must be FOK or FAK.`);
+        }
+        // Note: Price validation is optional for market orders
+        // If price is provided, it's used as a limit price (max for BUY, min for SELL)
+    }
     // ============================================================================
     // Private - WebSocket Monitoring (Polymarket-specific)
     // ============================================================================
@@ -339,17 +849,29 @@ export class OrderManager extends EventEmitter {
         // (We use dynamic import to avoid circular dependencies)
         const { RealtimeServiceV2 } = await import('./realtime-service-v2.js');
         this.realtimeService = new RealtimeServiceV2({ autoReconnect: true });
-        // Connect to WebSocket
+        // Connect to WebSocket and wait for connection to be established
+        // connect() is async and returns a Promise that resolves when connected
         if (this.realtimeService) {
-            this.realtimeService.connect();
+            console.log(`[OrderManager] Connecting to WebSocket...`);
+            await this.realtimeService.connect();
+            console.log(`[OrderManager] WebSocket connected successfully`);
         }
         // Subscribe to user events (requires credentials)
+        // Now safe to subscribe since connection is established
         const credentials = this.tradingService.getCredentials();
         if (credentials && this.realtimeService) {
-            this.realtimeService.subscribeUserEvents(credentials, {
+            console.log(`[OrderManager] Subscribing to user events...`);
+            // Map ApiCredentials (key) to ClobApiKeyCreds (apiKey) format
+            const clobAuth = {
+                apiKey: credentials.key,
+                secret: credentials.secret,
+                passphrase: credentials.passphrase,
+            };
+            this.realtimeService.subscribeUserEvents(clobAuth, {
                 onOrder: this.handleUserOrder.bind(this),
                 onTrade: this.handleUserTrade.bind(this),
             });
+            console.log(`[OrderManager] User events subscription complete`);
         }
     }
     /**
@@ -368,17 +890,17 @@ export class OrderManager extends EventEmitter {
         // Update order state
         watched.order.price = userOrder.price;
         watched.order.originalSize = userOrder.originalSize;
-        watched.order.filledSize = userOrder.matchedSize;
-        watched.order.remainingSize = userOrder.originalSize - userOrder.matchedSize;
+        watched.order.filledSize = userOrder.sizeMatched;
+        watched.order.remainingSize = userOrder.originalSize - userOrder.sizeMatched;
         // Infer new status
         let newStatus = watched.lastStatus;
         if (userOrder.eventType === 'PLACEMENT') {
             newStatus = OrderStatus.OPEN;
         }
         else if (userOrder.eventType === 'UPDATE') {
-            if (userOrder.matchedSize > 0) {
+            if (userOrder.sizeMatched > 0) {
                 newStatus =
-                    userOrder.matchedSize >= userOrder.originalSize
+                    userOrder.sizeMatched >= userOrder.originalSize
                         ? OrderStatus.FILLED
                         : OrderStatus.PARTIALLY_FILLED;
             }
@@ -394,31 +916,105 @@ export class OrderManager extends EventEmitter {
     /**
      * Handle USER_TRADE WebSocket event (Polymarket-specific)
      * Triggered when: MATCHED, MINED, CONFIRMED
+     *
+     * Order lookup priority:
+     * 1. takerOrderId - if we placed a market order (FOK/FAK) or taker limit order
+     * 2. makerOrders[].orderId - if our limit order was matched as maker
      */
     async handleUserTrade(userTrade) {
-        const watched = this.watchedOrders.get(userTrade.market);
-        if (!watched)
+        // Debug: Log all incoming USER_TRADE events
+        console.log(`[OrderManager] WebSocket USER_TRADE received:`, {
+            tradeId: userTrade.tradeId,
+            takerOrderId: userTrade.takerOrderId,
+            makerOrderIds: userTrade.makerOrders?.map(m => m.orderId),
+            size: userTrade.size,
+            price: userTrade.price,
+            status: userTrade.status,
+            watchedOrderCount: this.watchedOrders.size,
+        });
+        // Find the watched order using takerOrderId or makerOrders
+        let watched;
+        let makerInfo;
+        // Priority 1: Check if we're the taker
+        if (userTrade.takerOrderId) {
+            watched = this.watchedOrders.get(userTrade.takerOrderId);
+        }
+        // Priority 2: Check if we're a maker
+        if (!watched && userTrade.makerOrders) {
+            for (const maker of userTrade.makerOrders) {
+                watched = this.watchedOrders.get(maker.orderId);
+                if (watched) {
+                    makerInfo = maker;
+                    break;
+                }
+            }
+        }
+        if (!watched) {
+            console.log(`[OrderManager] USER_TRADE not for any watched order, ignoring`);
             return;
+        }
+        console.log(`[OrderManager] USER_TRADE matched watched order: ${watched.orderId}`);
+        // Bug 16 Fix: When we're the maker, use maker-specific matchedAmount and price
+        // userTrade.size is the TOTAL trade size (sum of all makers), not our individual fill
+        // Bug 20 Fix: Previously used wrong field name (matched_size instead of matched_amount)
+        // Now correctly reading matched_amount from Polymarket API
+        const rawMatchedAmount = makerInfo?.matchedAmount;
+        let fillSize = rawMatchedAmount ?? userTrade.size;
+        // Debug: Log raw values for verification
+        if (makerInfo) {
+            console.log(`[OrderManager] Maker fill debug:`, {
+                rawMatchedAmount,
+                makerOrdersLength: userTrade.makerOrders?.length,
+                willApplyFallback: fillSize === 0 || fillSize === undefined,
+                makerOrdersDetail: userTrade.makerOrders?.map(m => ({
+                    orderId: m.orderId?.slice(0, 12),
+                    matchedAmount: m.matchedAmount,
+                    price: m.price,
+                })),
+            });
+        }
+        // Fallback: if matchedAmount is 0/undefined and we're a maker, use trade size
+        // This shouldn't happen now that we're reading the correct field, but kept as safety
+        if (makerInfo && (fillSize === 0 || fillSize === undefined)) {
+            console.log(`[OrderManager] Fallback applied: using userTrade.size ${userTrade.size} instead of ${fillSize}`);
+            fillSize = userTrade.size;
+        }
+        const fillPrice = makerInfo?.price ?? userTrade.price;
+        console.log(`[OrderManager] USER_TRADE fill details:`, {
+            isMaker: !!makerInfo,
+            fillSize,
+            fillPrice,
+            tradeTotalSize: userTrade.size,
+        });
         // Deduplicate events
-        const eventKey = `trade_${userTrade.tradeId}_${userTrade.status}_${userTrade.timestamp}`;
+        // When we're maker, include our orderId in the key to handle multiple makers in same trade
+        const eventKey = makerInfo
+            ? `trade_${userTrade.tradeId}_${userTrade.status}_${watched.orderId}`
+            : `trade_${userTrade.tradeId}_${userTrade.status}_${userTrade.timestamp}`;
         if (this.processedEvents.has(eventKey))
             return;
         this.processedEvents.add(eventKey);
         // Emit fill event
-        const isCompleteFill = watched.order.filledSize + userTrade.size >= watched.order.originalSize;
+        // Calculate remaining size after this fill
+        const remainingAfterFill = watched.order.originalSize - (watched.order.filledSize + fillSize);
+        // Complete fill if: sum >= originalSize OR remaining is zero/negative
+        // Note: For market orders (FOK/FAK), originalSize is in USDC but filledSize is in shares,
+        // causing remainingAfterFill to be negative. This is still a complete fill.
+        const isCompleteFill = watched.order.filledSize + fillSize >= watched.order.originalSize ||
+            remainingAfterFill <= 0;
         const fillEvent = {
             orderId: watched.orderId,
             order: watched.order,
             fill: {
                 tradeId: userTrade.tradeId,
-                size: userTrade.size,
-                price: userTrade.price,
+                size: fillSize,
+                price: fillPrice,
                 fee: 0, // Fee info not in UserTrade
                 timestamp: userTrade.timestamp,
                 transactionHash: userTrade.transactionHash,
             },
-            cumulativeFilled: watched.order.filledSize + userTrade.size,
-            remainingSize: watched.order.originalSize - (watched.order.filledSize + userTrade.size),
+            cumulativeFilled: watched.order.filledSize + fillSize,
+            remainingSize: watched.order.originalSize - (watched.order.filledSize + fillSize),
             isCompleteFill,
         };
         if (isCompleteFill) {
@@ -485,7 +1081,12 @@ export class OrderManager extends EventEmitter {
         // Only emit if this is an actual increase from a previously known state
         if (newFilledSize > oldFilledSize && oldFilledSize >= 0) {
             const fillDelta = newFilledSize - oldFilledSize;
-            const isCompleteFill = freshOrder.remainingSize === 0;
+            // Check for complete fill using status (preferred) or remainingSize
+            // Note: For market orders (FOK/FAK), remainingSize may be negative due to unit mismatch
+            // (originalSize is in USDC, filledSize is in shares), so we rely on status
+            const isCompleteFill = freshOrder.status === OrderStatus.FILLED ||
+                freshOrder.remainingSize === 0 ||
+                freshOrder.remainingSize <= 0;
             // Deduplicate fill events using fill size as key
             const eventKey = `fill_${orderId}_${newFilledSize}`;
             if (!this.processedEvents.has(eventKey)) {