get_orderbook

Instructions

Implementation Reference

• src/tools/orderbook.ts:46-91 (handler)

  The async handler function for get_orderbook. Validates market_id, fetches order book from Buda API via cache, slices bids/asks by optional limit, maps price/amount to floats, and returns the result.

    async ({ market_id, limit }) => {
      try {
        const validationError = validateMarketId(market_id);
        if (validationError) {
          return {
            content: [{ type: "text", text: JSON.stringify({ error: validationError, code: "INVALID_MARKET_ID" }) }],
            isError: true,
          };
        }
  
        const id = market_id.toLowerCase();
        const data = await cache.getOrFetch<OrderBookResponse>(
          `orderbook:${id}`,
          CACHE_TTL.ORDERBOOK,
          () => client.get<OrderBookResponse>(`/markets/${id}/order_book`),
        );
  
        const book = data.order_book;
        const bids = limit ? book.bids.slice(0, limit) : book.bids;
        const asks = limit ? book.asks.slice(0, limit) : book.asks;
  
        const result = {
          bids: bids.map(([price, amount]) => ({
            price: parseFloat(price),
            amount: parseFloat(amount),
          })),
          asks: asks.map(([price, amount]) => ({
            price: parseFloat(price),
            amount: parseFloat(amount),
          })),
          bid_count: book.bids.length,
          ask_count: book.asks.length,
        };
  
        return {
          content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
        };
      } catch (err) {
        const msg = formatApiError(err);
        return {
          content: [{ type: "text", text: JSON.stringify(msg) }],
          isError: true,
        };
      }
    },
  );

• src/tools/orderbook.ts:8-29 (schema)

  The schema definition for get_orderbook, including its name, description, and inputSchema with market_id (string, required) and limit (number, optional).

  export const toolSchema = {
    name: "get_orderbook",
    description:
      "Returns the current order book for a Buda.com market as typed objects with float price and amount fields. " +
      "Bids are sorted highest-price first; asks lowest-price first. " +
      "Prices are in the quote currency; amounts are in the base currency. " +
      "Example: 'What are the top 5 buy and sell orders for BTC-CLP right now?'",
    inputSchema: {
      type: "object" as const,
      properties: {
        market_id: {
          type: "string",
          description: "Market ID (e.g. 'BTC-CLP', 'ETH-BTC').",
        },
        limit: {
          type: "number",
          description: "Maximum number of levels to return per side (default: all).",
        },
      },
      required: ["market_id"],
    },
  };

• src/tools/orderbook.ts:31-92 (registration)

  Registration function that calls server.tool() with the schema name, description, Zod-validated params, and the handler.

  export function register(server: McpServer, client: BudaClient, cache: MemoryCache): void {
    server.tool(
      toolSchema.name,
      toolSchema.description,
      {
        market_id: z
          .string()
          .describe("Market ID (e.g. 'BTC-CLP', 'ETH-BTC')."),
        limit: z
          .number()
          .int()
          .positive()
          .optional()
          .describe("Maximum number of levels to return per side (default: all)."),
      },
      async ({ market_id, limit }) => {
        try {
          const validationError = validateMarketId(market_id);
          if (validationError) {
            return {
              content: [{ type: "text", text: JSON.stringify({ error: validationError, code: "INVALID_MARKET_ID" }) }],
              isError: true,
            };
          }
  
          const id = market_id.toLowerCase();
          const data = await cache.getOrFetch<OrderBookResponse>(
            `orderbook:${id}`,
            CACHE_TTL.ORDERBOOK,
            () => client.get<OrderBookResponse>(`/markets/${id}/order_book`),
          );
  
          const book = data.order_book;
          const bids = limit ? book.bids.slice(0, limit) : book.bids;
          const asks = limit ? book.asks.slice(0, limit) : book.asks;
  
          const result = {
            bids: bids.map(([price, amount]) => ({
              price: parseFloat(price),
              amount: parseFloat(amount),
            })),
            asks: asks.map(([price, amount]) => ({
              price: parseFloat(price),
              amount: parseFloat(amount),
            })),
            bid_count: book.bids.length,
            ask_count: book.asks.length,
          };
  
          return {
            content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
          };
        } catch (err) {
          const msg = formatApiError(err);
          return {
            content: [{ type: "text", text: JSON.stringify(msg) }],
            isError: true,
          };
        }
      },
    );
  }

• src/index.ts:12-38 (registration)

  Import and registration of the orderbook tool in the main stdio server entry point.

  import * as orderbook from "./tools/orderbook.js";
  import * as trades from "./tools/trades.js";
  import * as volume from "./tools/volume.js";
  import * as spread from "./tools/spread.js";
  import * as compareMarkets from "./tools/compare_markets.js";
  import * as priceHistory from "./tools/price_history.js";
  import * as arbitrage from "./tools/arbitrage.js";
  import * as marketSummary from "./tools/market_summary.js";
  import * as simulateOrder from "./tools/simulate_order.js";
  import * as positionSize from "./tools/calculate_position_size.js";
  import * as marketSentiment from "./tools/market_sentiment.js";
  import * as technicalIndicators from "./tools/technical_indicators.js";
  import * as banks from "./tools/banks.js";
  import * as quotation from "./tools/quotation.js";
  import * as stableLiquidity from "./tools/stable_liquidity.js";
  import { handleMarketSummary } from "./tools/market_summary.js";
  
  const client = new BudaClient();
  
  const server = new McpServer({
    name: "buda-mcp",
    version: VERSION,
  });
  
  markets.register(server, client, cache);
  ticker.register(server, client, cache);
  orderbook.register(server, client, cache);

• src/types.ts:53-60 (helper)

  Type definitions for OrderBook (asks/bids as string tuple arrays) and OrderBookResponse used by the handler.

  export interface OrderBook {
    asks: [string, string][];
    bids: [string, string][];
  }
  
  export interface OrderBookResponse {
    order_book: OrderBook;
  }