get_market_volume

Instructions

Implementation Reference

• src/tools/volume.ts:36-79 (handler)

  The async handler function for the 'get_market_volume' tool. It validates the market_id, calls the Buda API endpoint /markets/{market_id}/volume, flattens the amount tuples (ask/bid volume for 24h and 7d), and returns the result as JSON.

    async ({ market_id }) => {
      try {
        const validationError = validateMarketId(market_id);
        if (validationError) {
          return {
            content: [{ type: "text", text: JSON.stringify({ error: validationError, code: "INVALID_MARKET_ID" }) }],
            isError: true,
          };
        }
  
        const data = await client.get<VolumeResponse>(
          `/markets/${market_id.toLowerCase()}/volume`,
        );
  
        const v = data.volume;
        const ask24 = flattenAmount(v.ask_volume_24h);
        const ask7d = flattenAmount(v.ask_volume_7d);
        const bid24 = flattenAmount(v.bid_volume_24h);
        const bid7d = flattenAmount(v.bid_volume_7d);
  
        const result = {
          market_id: v.market_id,
          ask_volume_24h: ask24.value,
          ask_volume_24h_currency: ask24.currency,
          ask_volume_7d: ask7d.value,
          ask_volume_7d_currency: ask7d.currency,
          bid_volume_24h: bid24.value,
          bid_volume_24h_currency: bid24.currency,
          bid_volume_7d: bid7d.value,
          bid_volume_7d_currency: bid7d.currency,
        };
  
        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/volume.ts:9-25 (schema)

  The tool schema definition including name, description, and inputSchema (market_id string parameter).

  export const toolSchema = {
    name: "get_market_volume",
    description:
      "Returns 24h and 7-day transacted volume for a Buda.com market, split by buy (bid) and sell (ask) side. " +
      "All volume values are floats in the base currency (e.g. BTC for BTC-CLP). " +
      "Example: 'How much Bitcoin was sold on BTC-CLP in the last 24 hours?'",
    inputSchema: {
      type: "object" as const,
      properties: {
        market_id: {
          type: "string",
          description: "Market ID (e.g. 'BTC-CLP', 'ETH-BTC').",
        },
      },
      required: ["market_id"],
    },
  };

• src/tools/volume.ts:27-80 (registration)

  The register() function that registers the tool with the MCP server using server.tool().

  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')."),
      },
      async ({ market_id }) => {
        try {
          const validationError = validateMarketId(market_id);
          if (validationError) {
            return {
              content: [{ type: "text", text: JSON.stringify({ error: validationError, code: "INVALID_MARKET_ID" }) }],
              isError: true,
            };
          }
  
          const data = await client.get<VolumeResponse>(
            `/markets/${market_id.toLowerCase()}/volume`,
          );
  
          const v = data.volume;
          const ask24 = flattenAmount(v.ask_volume_24h);
          const ask7d = flattenAmount(v.ask_volume_7d);
          const bid24 = flattenAmount(v.bid_volume_24h);
          const bid7d = flattenAmount(v.bid_volume_7d);
  
          const result = {
            market_id: v.market_id,
            ask_volume_24h: ask24.value,
            ask_volume_24h_currency: ask24.currency,
            ask_volume_7d: ask7d.value,
            ask_volume_7d_currency: ask7d.currency,
            bid_volume_24h: bid24.value,
            bid_volume_24h_currency: bid24.currency,
            bid_volume_7d: bid7d.value,
            bid_volume_7d_currency: bid7d.currency,
          };
  
          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:40-41 (registration)

  The top-level registration call that connects the volume tool to the MCP server via volume.register(server, client, cache).

  volume.register(server, client, cache);
  spread.register(server, client, cache);

• src/utils.ts:29-33 (helper)

  The flattenAmount helper used in the handler to convert Amount tuples [value_string, currency] into typed {value, currency} objects.

  export function flattenAmount(amount: Amount): { value: number; currency: string } {
    const value = parseFloat(amount[0]);
    if (isNaN(value)) throw new Error(`Invalid amount value: "${amount[0]}"`);
    return { value, currency: amount[1] };
  }