get_orderbook

Instructions

Implementation Reference

• src/tools/market-data.ts:54-95 (handler)

  The main handler function for get_orderbook tool. Validates exchange and symbol, gets the exchange connector, fetches order book data, processes bids/asks with limit, calculates spread, and returns formatted JSON response.

  async ({ exchange, symbol, limit }) => {
    const validExchange = validateExchange(exchange);
    const validSymbol = validateSymbol(symbol);
  
    const connector = await getConnectorSafe(exchange);
    const orderbook = await connector.getOrderBook(validSymbol);
  
    const bids = orderbook.bids.slice(0, limit);
    const asks = orderbook.asks.slice(0, limit);
  
    const spread =
      orderbook.asks.length > 0 && orderbook.bids.length > 0
        ? orderbook.asks[0].price - orderbook.bids[0].price
        : null;
    const spreadPercent =
      spread !== null && orderbook.asks[0].price > 0
        ? (spread / orderbook.asks[0].price) * 100
        : null;
  
    return {
      content: [
        {
          type: 'text' as const,
          text: JSON.stringify(
            {
              symbol: orderbook.symbol,
              bids,
              asks,
              spread,
              spreadPercent,
              bidLevels: bids.length,
              askLevels: asks.length,
              timestamp: orderbook.timestamp,
              exchange: validExchange,
            },
            null,
            2
          ),
        },
      ],
    };
  }

• src/tools/market-data.ts:46-96 (registration)

  Tool registration in MCP server. Registers get_orderbook with name, description, and parameter schema (exchange, symbol, limit).

  server.tool(
    'get_orderbook',
    'Fetch order book depth (bids and asks) for a trading pair on a supported exchange',
    {
      exchange: ExchangeParam,
      symbol: SymbolParam,
      limit: LimitParam(10, 100),
    },
    async ({ exchange, symbol, limit }) => {
      const validExchange = validateExchange(exchange);
      const validSymbol = validateSymbol(symbol);
  
      const connector = await getConnectorSafe(exchange);
      const orderbook = await connector.getOrderBook(validSymbol);
  
      const bids = orderbook.bids.slice(0, limit);
      const asks = orderbook.asks.slice(0, limit);
  
      const spread =
        orderbook.asks.length > 0 && orderbook.bids.length > 0
          ? orderbook.asks[0].price - orderbook.bids[0].price
          : null;
      const spreadPercent =
        spread !== null && orderbook.asks[0].price > 0
          ? (spread / orderbook.asks[0].price) * 100
          : null;
  
      return {
        content: [
          {
            type: 'text' as const,
            text: JSON.stringify(
              {
                symbol: orderbook.symbol,
                bids,
                asks,
                spread,
                spreadPercent,
                bidLevels: bids.length,
                askLevels: asks.length,
                timestamp: orderbook.timestamp,
                exchange: validExchange,
              },
              null,
              2
            ),
          },
        ],
      };
    }
  );

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

  Zod schema definitions for get_orderbook parameters. ExchangeParam validates supported exchanges, SymbolParam for trading pairs, and LimitParam creates configurable number schemas with min/max/default.

  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)

  Symbol validation helper used by get_orderbook handler. Converts to uppercase and validates format (supports both BTC/USDT and BTCUSDT styles).

  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-14 (helper)

  Exchange validation helper used by get_orderbook handler. Validates against supported exchanges (mexc, gateio, bitget, kraken) and returns lowercase validated exchange name.

  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;
  }