get_trades

Instructions

Implementation Reference

• src/tools/trades.ts:59-101 (handler)

  The async handler function that executes the get_trades tool logic: validates market_id, builds request params, calls the Buda API /markets/{market_id}/trades endpoint, maps the response entries (timestamp_ms, amount, price, direction), and returns the result.

  async ({ market_id, limit, timestamp }) => {
    try {
      const validationError = validateMarketId(market_id);
      if (validationError) {
        return {
          content: [{ type: "text", text: JSON.stringify({ error: validationError, code: "INVALID_MARKET_ID" }) }],
          isError: true,
        };
      }
  
      const params: Record<string, string | number> = {};
      if (limit !== undefined) params.limit = limit;
      if (timestamp !== undefined) params.timestamp = timestamp;
  
      const data = await client.get<TradesResponse>(
        `/markets/${market_id.toLowerCase()}/trades`,
        Object.keys(params).length > 0 ? params : undefined,
      );
  
      const t = data.trades;
      const result = {
        timestamp: t.timestamp,
        last_timestamp: t.last_timestamp,
        market_id: t.market_id,
        entries: t.entries.map(([tsMs, amount, price, direction]) => ({
          timestamp_ms: parseInt(tsMs, 10),
          amount: parseFloat(amount),
          price: parseFloat(price),
          direction,
        })),
      };
  
      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/trades.ts:8-34 (schema)

  The JSON schema and Zod definitions for the get_trades tool, defining input parameters: market_id (required string), limit (optional number, 1-100), and timestamp (optional number, Unix seconds).

  export const toolSchema = {
    name: "get_trades",
    description:
      "Returns recent trade history for a Buda.com market as typed objects. Each entry has " +
      "timestamp_ms (integer), amount (float, base currency), price (float, quote currency), " +
      "and direction ('buy' or 'sell'). " +
      "Example: 'What was the last executed price for BTC-CLP and was it a buy or sell?'",
    inputSchema: {
      type: "object" as const,
      properties: {
        market_id: {
          type: "string",
          description: "Market ID (e.g. 'BTC-CLP', 'ETH-BTC').",
        },
        limit: {
          type: "number",
          description: "Number of trades to return (default: 50, max: 100).",
        },
        timestamp: {
          type: "number",
          description:
            "Unix timestamp (seconds) to paginate from. Returns trades older than this timestamp.",
        },
      },
      required: ["market_id"],
    },
  };

• src/index.ts:39-39 (registration)

  Registration of the get_trades tool: calls trades.register(server, client, cache) to wire the tool into the MCP server.

  trades.register(server, client, cache);

• src/tools/trades.ts:36-103 (registration)

  The register() function that calls server.tool() with the schema and handler, registering get_trades on the MCP server.

  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()
          .min(1)
          .max(100)
          .optional()
          .describe("Number of trades to return (default: 50, max: 100)."),
        timestamp: z
          .number()
          .int()
          .optional()
          .describe(
            "Unix timestamp (seconds) to paginate from. Returns trades older than this timestamp.",
          ),
      },
      async ({ market_id, limit, timestamp }) => {
        try {
          const validationError = validateMarketId(market_id);
          if (validationError) {
            return {
              content: [{ type: "text", text: JSON.stringify({ error: validationError, code: "INVALID_MARKET_ID" }) }],
              isError: true,
            };
          }
  
          const params: Record<string, string | number> = {};
          if (limit !== undefined) params.limit = limit;
          if (timestamp !== undefined) params.timestamp = timestamp;
  
          const data = await client.get<TradesResponse>(
            `/markets/${market_id.toLowerCase()}/trades`,
            Object.keys(params).length > 0 ? params : undefined,
          );
  
          const t = data.trades;
          const result = {
            timestamp: t.timestamp,
            last_timestamp: t.last_timestamp,
            market_id: t.market_id,
            entries: t.entries.map(([tsMs, amount, price, direction]) => ({
              timestamp_ms: parseInt(tsMs, 10),
              amount: parseFloat(amount),
              price: parseFloat(price),
              direction,
            })),
          };
  
          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/types.ts:64-74 (helper)

  Type definitions: Trades interface (timestamp, last_timestamp, market_id, entries tuple) and TradesResponse wrapper interface used by the handler.

  export interface Trades {
    timestamp: string;
    last_timestamp: string;
    market_id: string;
    /** Each entry: [timestamp_ms, amount, price, direction] */
    entries: [string, string, string, string][];
  }
  
  export interface TradesResponse {
    trades: Trades;
  }