get_trades

Instructions

Implementation Reference

• src/tools/market-data.ts:98-142 (handler)

  Main MCP tool registration and handler implementation for get_trades. Defines the tool with parameters (exchange, symbol, limit), validates inputs, retrieves trades from the exchange connector, and returns formatted trade data with summary statistics.

  server.tool(
    'get_trades',
    'Get recent trades for a trading pair on a supported exchange',
    {
      exchange: ExchangeParam,
      symbol: SymbolParam,
      limit: LimitParam(20, 100),
    },
    async ({ exchange, symbol, limit }) => {
      const validExchange = validateExchange(exchange);
      const validSymbol = validateSymbol(symbol);
  
      const connector = await getConnectorSafe(exchange);
      const trades = await connector.getRecentTrades(validSymbol);
  
      const limitedTrades = trades.slice(0, limit);
  
      const buyTrades = limitedTrades.filter((t) => t.side === 'buy');
      const sellTrades = limitedTrades.filter((t) => t.side === 'sell');
      const totalVolume = limitedTrades.reduce((sum, trade) => sum + trade.price * trade.amount, 0);
  
      return {
        content: [
          {
            type: 'text' as const,
            text: JSON.stringify(
              {
                symbol: validSymbol,
                trades: limitedTrades,
                summary: {
                  totalTrades: limitedTrades.length,
                  buyTrades: buyTrades.length,
                  sellTrades: sellTrades.length,
                  totalVolume,
                },
                exchange: validExchange,
              },
              null,
              2
            ),
          },
        ],
      };
    }
  );

• src/utils/validators.ts:3-21 (schema)

  Schema definitions for the get_trades tool parameters: ExchangeParam (validates exchange string), SymbolParam (validates trading pair symbol), and LimitParam (numeric limit with min/max constraints and default value).

  export const ExchangeParam = z
    .string()
    .describe('Exchange to query. Supported: mexc, gateio, bitget, kraken');
  
  export const SymbolParam = z.string().describe('Trading pair symbol (e.g., BTC/USDT, INDY/USDT)');
  
  export const OptionalSymbolParam = z
    .string()
    .optional()
    .describe('Optional trading pair to filter by (e.g., BTC/USDT). Returns all if omitted.');
  
  export function LimitParam(defaultValue: number, max: number) {
    return z
      .number()
      .min(1)
      .max(max)
      .default(defaultValue)
      .describe(`Number of results to return (default: ${defaultValue}, max: ${max})`);
  }

• src/utils/validators.ts:23-32 (helper)

  Helper function validateSymbol that validates and normalizes trading pair symbols (converts to uppercase, checks format like BTC/USDT or BTCUSDT).

  export function validateSymbol(symbol: string): string {
    if (!symbol) {
      throw new Error('Symbol is required');
    }
    const upper = symbol.toUpperCase();
    if (!/^[A-Z]+\/[A-Z]+$/.test(upper) && !/^[A-Z]+[A-Z]+$/.test(upper)) {
      throw new Error(`Invalid symbol format: ${symbol}. Expected: BTC/USDT or BTCUSDT`);
    }
    return upper;
  }

• src/exchange/exchange-manager.ts:6-25 (helper)

  Helper functions for exchange management: validateExchange (checks against supported exchanges list) and getConnectorSafe (retrieves the exchange connector with error handling).

  export function validateExchange(exchange: string): SupportedExchange {
    const lower = exchange.toLowerCase();
    if (!(SUPPORTED_EXCHANGES as readonly string[]).includes(lower)) {
      throw new Error(
        `Unsupported exchange: ${exchange}. Supported: ${SUPPORTED_EXCHANGES.join(', ')}`
      );
    }
    return lower as SupportedExchange;
  }
  
  export async function getConnectorSafe(exchange: string): Promise<BaseExchangeConnector> {
    const validExchange = validateExchange(exchange);
    const { ExchangeFactory } = await import('@3rd-eye-labs/openmm');
    try {
      return await ExchangeFactory.getExchange(validExchange as any);
    } catch (error) {
      const message = error instanceof Error ? error.message : String(error);
      throw new Error(`Failed to connect to ${validExchange}: ${message}`);
    }
  }

• src/tools/index.ts:9-9 (registration)

  Registration call that registers all market data tools (including get_trades) with the MCP server.

  registerMarketDataTools(server);