get_available_banks

Instructions

Implementation Reference

• src/tools/banks.ts:28-80 (handler)

  The main handler function that validates currency, fetches banks from the Buda API (with caching), and returns the list of banks or an empty array on 404.

  export async function handleGetAvailableBanks(
    args: { currency: string },
    client: BudaClient,
    cache: MemoryCache,
  ): Promise<{ content: Array<{ type: "text"; text: string }>; isError?: boolean }> {
    const { currency } = args;
  
    const validationError = validateCurrency(currency);
    if (validationError) {
      return {
        content: [{ type: "text", text: JSON.stringify({ error: validationError, code: "INVALID_CURRENCY" }) }],
        isError: true,
      };
    }
  
    const currencyUpper = currency.toUpperCase();
  
    try {
      const data = await cache.getOrFetch<BanksResponse>(
        `banks:${currencyUpper}`,
        CACHE_TTL.BANKS,
        () => client.get<BanksResponse>(`/currencies/${currencyUpper}/banks`),
      );
  
      return {
        content: [
          {
            type: "text",
            text: JSON.stringify(
              {
                currency: currencyUpper,
                banks: data.banks.map((b) => ({ id: b.id, name: b.name, country: b.country ?? null })),
              },
              null,
              2,
            ),
          },
        ],
      };
    } catch (err) {
      // 404 means no banks exist for this currency — return empty list (not an error)
      if (err instanceof BudaApiError && err.status === 404) {
        return {
          content: [{ type: "text", text: JSON.stringify({ currency: currencyUpper, banks: [] }, null, 2) }],
        };
      }
      const msg = formatApiError(err);
      return {
        content: [{ type: "text", text: JSON.stringify(msg) }],
        isError: true,
      };
    }
  }

• src/tools/banks.ts:8-26 (schema)

  The tool schema defining name 'get_available_banks', description, and input schema requiring a 'currency' string.

  export const toolSchema = {
    name: "get_available_banks",
    description:
      "Returns banks available for deposits and withdrawals of a fiat currency on Buda.com. " +
      "Returns an empty banks array (not an error) if the currency has no associated banks " +
      "(e.g. crypto currencies or unsupported fiat currencies). " +
      "Results are cached for 60 seconds. " +
      "Example: 'Which banks can I use for CLP deposits?'",
    inputSchema: {
      type: "object" as const,
      properties: {
        currency: {
          type: "string",
          description: "Currency code (e.g. 'CLP', 'COP', 'PEN').",
        },
      },
      required: ["currency"],
    },
  };

• src/tools/banks.ts:82-91 (registration)

  Registers the tool with the McpServer using the schema name, description, a Zod-validated currency parameter, and a callback to the handler.

  export function register(server: McpServer, client: BudaClient, cache: MemoryCache): void {
    server.tool(
      toolSchema.name,
      toolSchema.description,
      {
        currency: z.string().min(2).max(10).describe("Currency code (e.g. 'CLP', 'COP', 'PEN')."),
      },
      (args) => handleGetAvailableBanks(args, client, cache),
    );
  }

• src/types.ts:130-138 (schema)

  Type definitions for Bank (id, name, country) and BanksResponse used by the handler.

  export interface Bank {
    id: string;
    name: string;
    country: string | null;
  }
  
  export interface BanksResponse {
    banks: Bank[];
  }

• src/validation.ts:24-30 (helper)

  The validateCurrency helper used by the handler to validate the currency input.

  export function validateCurrency(id: string): string | null {
    if (!CURRENCY_RE.test(id)) {
      return (
        `Invalid currency. ` +
        `Expected 2–10 alphanumeric characters (e.g. "BTC", "CLP", "USDC").`
      );
    }