@catalyst-team/poly-mcp 0.1.0

package/src/tools/trade.ts

@@ -0,0 +1,417 @@
+/**
+ * Trade Tools - MCP tools for trading execution
+ *
+ * These tools enable actual trading on Polymarket when private key is configured.
+ * API credentials are automatically derived from the private key using createOrDeriveApiKey().
+ *
+ * Required environment variable:
+ * - POLY_PRIVATE_KEY: Wallet private key for signing transactions
+ */
+
+import type { PolymarketSDK } from '@catalyst-team/poly-sdk';
+import type { ToolDefinition } from '../types.js';
+import {
+  validateConditionId,
+  validateOutcome,
+  validateSide,
+  validatePrice,
+  validatePositiveNumber,
+  wrapError,
+  McpToolError,
+  ErrorCode,
+} from '../errors.js';
+import { TradingClient, RateLimiter } from '@catalyst-team/poly-sdk';
+import type { OrderResult } from '@catalyst-team/poly-sdk';
+
+// Singleton trading client instance (lazily initialized)
+let tradingClient: TradingClient | null = null;
+let tradingClientInitialized = false;
+
+/**
+ * Get or create the TradingClient instance
+ * Uses the signer from SDK's clobApi
+ */
+async function getTradingClient(sdk: PolymarketSDK): Promise<TradingClient> {
+  // Check if signer is available
+  const sdkAny = sdk as unknown as { clobApi?: { signer?: unknown; config?: { chainId?: number } } };
+  const signer = sdkAny.clobApi?.signer;
+
+  if (!signer) {
+    throw new McpToolError(
+      ErrorCode.AUTH_REQUIRED,
+      'Trading requires a private key. Configure POLY_PRIVATE_KEY environment variable.'
+    );
+  }
+
+  // Create trading client if not exists
+  if (!tradingClient) {
+    const signerAny = signer as { privateKey?: string };
+    const privateKey = signerAny.privateKey;
+
+    if (!privateKey) {
+      throw new McpToolError(
+        ErrorCode.AUTH_REQUIRED,
+        'Cannot extract private key from signer. Ensure POLY_PRIVATE_KEY is configured correctly.'
+      );
+    }
+
+    const chainId = sdkAny.clobApi?.config?.chainId || 137;
+    const rateLimiter = new RateLimiter();
+
+    tradingClient = new TradingClient(rateLimiter, {
+      privateKey,
+      chainId,
+    });
+  }
+
+  // Initialize if needed
+  if (!tradingClientInitialized) {
+    await tradingClient.initialize();
+    tradingClientInitialized = true;
+  }
+
+  return tradingClient;
+}
+
+export const tradeToolDefinitions: ToolDefinition[] = [
+  {
+    name: 'place_limit_order',
+    description: 'Place a limit order on a market (requires API key)',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        conditionId: {
+          type: 'string',
+        },
+        outcome: {
+          type: 'string',
+          enum: ['Yes', 'No'],
+        },
+        side: {
+          type: 'string',
+          enum: ['BUY', 'SELL'],
+        },
+        price: {
+          type: 'number',
+          description: 'Limit price (0.001 to 0.999)',
+        },
+        size: {
+          type: 'number',
+          description: 'Number of shares',
+        },
+        orderType: {
+          type: 'string',
+          enum: ['GTC', 'GTD'],
+          default: 'GTC',
+        },
+      },
+      required: ['conditionId', 'outcome', 'side', 'price', 'size'],
+    },
+  },
+  {
+    name: 'place_market_order',
+    description: 'Place a market order on a market (requires API key)',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        conditionId: {
+          type: 'string',
+        },
+        outcome: {
+          type: 'string',
+          enum: ['Yes', 'No'],
+        },
+        side: {
+          type: 'string',
+          enum: ['BUY', 'SELL'],
+        },
+        amount: {
+          type: 'number',
+          description: 'Amount in USDC',
+        },
+        maxSlippage: {
+          type: 'number',
+          description: 'Maximum acceptable slippage (e.g., 0.02 for 2%)',
+          default: 0.02,
+        },
+      },
+      required: ['conditionId', 'outcome', 'side', 'amount'],
+    },
+  },
+  {
+    name: 'cancel_order',
+    description: 'Cancel an open order (requires API key)',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        orderId: {
+          type: 'string',
+          description: 'Order ID to cancel',
+        },
+      },
+      required: ['orderId'],
+    },
+  },
+  {
+    name: 'get_my_orders',
+    description: 'Get your open orders (requires API key)',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        status: {
+          type: 'string',
+          enum: ['LIVE', 'FILLED', 'CANCELLED'],
+          default: 'LIVE',
+        },
+      },
+    },
+  },
+];
+
+// Check if trading is configured (basic check)
+function checkTradingEnabled(sdk: PolymarketSDK): void {
+  if (!sdk.clobApi) {
+    throw new McpToolError(
+      ErrorCode.AUTH_REQUIRED,
+      'Trading requires SDK to be properly initialized'
+    );
+  }
+
+  // Check if signer is available
+  const sdkAny = sdk as unknown as { clobApi?: { signer?: unknown } };
+  if (!sdkAny.clobApi?.signer) {
+    throw new McpToolError(
+      ErrorCode.AUTH_REQUIRED,
+      'Trading requires a private key. Configure POLY_PRIVATE_KEY environment variable.'
+    );
+  }
+}
+
+export interface PlaceLimitOrderInput {
+  conditionId: string;
+  outcome: 'Yes' | 'No';
+  side: 'BUY' | 'SELL';
+  price: number;
+  size: number;
+  orderType?: 'GTC' | 'GTD';
+}
+
+export interface PlaceMarketOrderInput {
+  conditionId: string;
+  outcome: 'Yes' | 'No';
+  side: 'BUY' | 'SELL';
+  amount: number;
+  maxSlippage?: number;
+}
+
+export interface CancelOrderInput {
+  orderId: string;
+}
+
+export interface GetMyOrdersInput {
+  status?: 'LIVE' | 'FILLED' | 'CANCELLED';
+}
+
+export async function handlePlaceLimitOrder(
+  sdk: PolymarketSDK,
+  input: PlaceLimitOrderInput
+): Promise<unknown> {
+  checkTradingEnabled(sdk);
+  validateConditionId(input.conditionId);
+  validateOutcome(input.outcome);
+  validateSide(input.side);
+  validatePrice(input.price);
+  validatePositiveNumber(input.size, 'size');
+
+  try {
+    // Get token ID for the outcome
+    const market = await sdk.clobApi.getMarket(input.conditionId);
+    const token = market.tokens.find(
+      (t) => t.outcome.toLowerCase() === input.outcome.toLowerCase()
+    );
+
+    if (!token) {
+      throw new McpToolError(
+        ErrorCode.MARKET_NOT_FOUND,
+        `Token for outcome ${input.outcome} not found`
+      );
+    }
+
+    // Get trading client (lazily initialized)
+    const client = await getTradingClient(sdk);
+
+    // Place the limit order
+    const result: OrderResult = await client.createOrder({
+      tokenId: token.tokenId,
+      side: input.side,
+      price: input.price,
+      size: input.size,
+      orderType: input.orderType || 'GTC',
+    });
+
+    return {
+      success: result.success,
+      orderId: result.orderId,
+      orderIds: result.orderIds,
+      market: {
+        conditionId: input.conditionId,
+        question: market.question,
+        outcome: input.outcome,
+      },
+      order: {
+        side: input.side,
+        price: input.price,
+        size: input.size,
+        orderType: input.orderType || 'GTC',
+      },
+      transactionHashes: result.transactionHashes,
+      errorMsg: result.errorMsg,
+    };
+  } catch (err) {
+    throw wrapError(err);
+  }
+}
+
+export async function handlePlaceMarketOrder(
+  sdk: PolymarketSDK,
+  input: PlaceMarketOrderInput
+): Promise<unknown> {
+  checkTradingEnabled(sdk);
+  validateConditionId(input.conditionId);
+  validateOutcome(input.outcome);
+  validateSide(input.side);
+  validatePositiveNumber(input.amount, 'amount');
+
+  try {
+    // Get token ID for the outcome
+    const market = await sdk.clobApi.getMarket(input.conditionId);
+    const token = market.tokens.find(
+      (t) => t.outcome.toLowerCase() === input.outcome.toLowerCase()
+    );
+
+    if (!token) {
+      throw new McpToolError(
+        ErrorCode.MARKET_NOT_FOUND,
+        `Token for outcome ${input.outcome} not found`
+      );
+    }
+
+    // Get trading client (lazily initialized)
+    const client = await getTradingClient(sdk);
+
+    // Get current price for slippage calculation
+    const currentPrice = token.price;
+    const maxSlippage = input.maxSlippage || 0.02; // Default 2%
+
+    // Calculate price limit based on side and slippage
+    // For BUY: max price we're willing to pay = current * (1 + slippage)
+    // For SELL: min price we're willing to accept = current * (1 - slippage)
+    const priceLimit = input.side === 'BUY'
+      ? Math.min(currentPrice * (1 + maxSlippage), 0.999)
+      : Math.max(currentPrice * (1 - maxSlippage), 0.001);
+
+    // Place the market order
+    const result: OrderResult = await client.createMarketOrder({
+      tokenId: token.tokenId,
+      side: input.side,
+      amount: input.amount,
+      price: priceLimit,
+      orderType: 'FOK', // Fill or Kill for market orders
+    });
+
+    return {
+      success: result.success,
+      orderId: result.orderId,
+      orderIds: result.orderIds,
+      market: {
+        conditionId: input.conditionId,
+        question: market.question,
+        outcome: input.outcome,
+      },
+      order: {
+        side: input.side,
+        amount: input.amount,
+        priceLimit,
+        maxSlippage,
+      },
+      transactionHashes: result.transactionHashes,
+      errorMsg: result.errorMsg,
+    };
+  } catch (err) {
+    throw wrapError(err);
+  }
+}
+
+export async function handleCancelOrder(
+  sdk: PolymarketSDK,
+  input: CancelOrderInput
+): Promise<unknown> {
+  checkTradingEnabled(sdk);
+
+  if (!input.orderId) {
+    throw new McpToolError(ErrorCode.INVALID_INPUT, 'Order ID is required');
+  }
+
+  try {
+    // Get trading client (lazily initialized)
+    const client = await getTradingClient(sdk);
+
+    // Cancel the order
+    const result: OrderResult = await client.cancelOrder(input.orderId);
+
+    return {
+      success: result.success,
+      orderId: input.orderId,
+      message: result.success
+        ? `Order ${input.orderId} cancelled successfully`
+        : `Failed to cancel order ${input.orderId}`,
+    };
+  } catch (err) {
+    throw wrapError(err);
+  }
+}
+
+export async function handleGetMyOrders(
+  sdk: PolymarketSDK,
+  input: GetMyOrdersInput
+): Promise<unknown> {
+  checkTradingEnabled(sdk);
+
+  try {
+    // Get trading client (lazily initialized)
+    const client = await getTradingClient(sdk);
+
+    // Note: TradingClient only supports getting open (LIVE) orders
+    // For FILLED/CANCELLED, we would need to query trades history
+    const status = input.status || 'LIVE';
+
+    if (status !== 'LIVE') {
+      // For non-LIVE orders, return a note about limitation
+      return {
+        orders: [],
+        status,
+        note: `Currently only LIVE orders are supported. Use get_trader_trades for historical order information.`,
+      };
+    }
+
+    // Get open orders
+    const orders = await client.getOpenOrders();
+
+    return {
+      orders: orders.map(o => ({
+        id: o.id,
+        status: o.status,
+        tokenId: o.tokenId,
+        side: o.side,
+        price: o.price,
+        originalSize: o.originalSize,
+        remainingSize: o.remainingSize,
+        createdAt: o.createdAt,
+      })),
+      count: orders.length,
+      status: 'LIVE',
+    };
+  } catch (err) {
+    throw wrapError(err);
+  }
+}