@guiie/buda-mcp 1.4.2 → 1.5.0

package/src/tools/cancel_all_orders.ts

@@ -0,0 +1,117 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+import { BudaClient, BudaApiError } from "../client.js";
+import { validateMarketId } from "../validation.js";
+import type { CancelAllOrdersResponse } from "../types.js";
+
+export const toolSchema = {
+  name: "cancel_all_orders",
+  description:
+    "Cancel all open orders on Buda.com, optionally filtered by a specific market. " +
+    "Pass market_id='*' to cancel across all markets, or a specific market ID (e.g. 'BTC-CLP'). " +
+    "IMPORTANT: This action is irreversible. Pass confirmation_token='CONFIRM' to execute. " +
+    "Requires BUDA_API_KEY and BUDA_API_SECRET.",
+  inputSchema: {
+    type: "object" as const,
+    properties: {
+      market_id: {
+        type: "string",
+        description: "Market ID (e.g. 'BTC-CLP') or '*' to cancel orders across all markets.",
+      },
+      confirmation_token: {
+        type: "string",
+        description:
+          "Safety confirmation. Must equal exactly 'CONFIRM' (case-sensitive) to execute. " +
+          "Any other value will reject the request without canceling.",
+      },
+    },
+    required: ["market_id", "confirmation_token"],
+  },
+};
+
+type CancelAllOrdersArgs = {
+  market_id: string;
+  confirmation_token: string;
+};
+
+export async function handleCancelAllOrders(
+  args: CancelAllOrdersArgs,
+  client: BudaClient,
+): Promise<{ content: Array<{ type: "text"; text: string }>; isError?: boolean }> {
+  const { market_id, confirmation_token } = args;
+
+  if (confirmation_token !== "CONFIRM") {
+    return {
+      content: [
+        {
+          type: "text",
+          text: JSON.stringify({
+            error:
+              "Orders not canceled. confirmation_token must equal 'CONFIRM' to execute. " +
+              "Review and set confirmation_token='CONFIRM' to proceed.",
+            code: "CONFIRMATION_REQUIRED",
+            preview: { market_id },
+          }),
+        },
+      ],
+      isError: true,
+    };
+  }
+
+  if (market_id !== "*") {
+    const validationError = validateMarketId(market_id);
+    if (validationError) {
+      return {
+        content: [
+          { type: "text", text: JSON.stringify({ error: validationError, code: "INVALID_MARKET_ID" }) },
+        ],
+        isError: true,
+      };
+    }
+  }
+
+  try {
+    const params =
+      market_id !== "*" ? { market_id: market_id.toLowerCase() } : undefined;
+
+    const data = await client.delete<CancelAllOrdersResponse>(`/orders`, params);
+
+    return {
+      content: [
+        {
+          type: "text",
+          text: JSON.stringify({ canceled_count: data.canceled_count, market_id }),
+        },
+      ],
+    };
+  } catch (err) {
+    const msg =
+      err instanceof BudaApiError
+        ? { error: err.message, code: err.status, path: err.path }
+        : { error: String(err), code: "UNKNOWN" };
+    return {
+      content: [{ type: "text", text: JSON.stringify(msg) }],
+      isError: true,
+    };
+  }
+}
+
+export function register(server: McpServer, client: BudaClient): void {
+  server.tool(
+    toolSchema.name,
+    toolSchema.description,
+    {
+      market_id: z
+        .string()
+        .min(1)
+        .describe("Market ID (e.g. 'BTC-CLP') or '*' to cancel orders across all markets."),
+      confirmation_token: z
+        .string()
+        .describe(
+          "Safety confirmation. Must equal exactly 'CONFIRM' (case-sensitive) to execute. " +
+            "Any other value will reject the request without canceling.",
+        ),
+    },
+    (args) => handleCancelAllOrders(args, client),
+  );
+}

package/src/tools/cancel_order_by_client_id.ts

@@ -0,0 +1,132 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+import { BudaClient, BudaApiError } from "../client.js";
+import { flattenAmount } from "../utils.js";
+import type { OrderResponse, Order } from "../types.js";
+
+export const toolSchema = {
+  name: "cancel_order_by_client_id",
+  description:
+    "Cancel an open order by its client-assigned ID on Buda.com. " +
+    "IMPORTANT: Pass confirmation_token='CONFIRM' to execute. " +
+    "Requires BUDA_API_KEY and BUDA_API_SECRET.",
+  inputSchema: {
+    type: "object" as const,
+    properties: {
+      client_id: {
+        type: "string",
+        description: "The client ID string assigned when placing the order.",
+      },
+      confirmation_token: {
+        type: "string",
+        description:
+          "Safety confirmation. Must equal exactly 'CONFIRM' (case-sensitive) to execute. " +
+          "Any other value will reject the request without canceling.",
+      },
+    },
+    required: ["client_id", "confirmation_token"],
+  },
+};
+
+type CancelOrderByClientIdArgs = {
+  client_id: string;
+  confirmation_token: string;
+};
+
+function normalizeOrder(o: Order) {
+  const amount = flattenAmount(o.amount);
+  const originalAmount = flattenAmount(o.original_amount);
+  const tradedAmount = flattenAmount(o.traded_amount);
+  const totalExchanged = flattenAmount(o.total_exchanged);
+  const paidFee = flattenAmount(o.paid_fee);
+  const limitPrice = o.limit ? flattenAmount(o.limit) : null;
+
+  return {
+    id: o.id,
+    type: o.type,
+    state: o.state,
+    created_at: o.created_at,
+    market_id: o.market_id,
+    fee_currency: o.fee_currency,
+    price_type: o.price_type,
+    order_type: o.order_type,
+    client_id: o.client_id,
+    limit_price: limitPrice ? limitPrice.value : null,
+    limit_price_currency: limitPrice ? limitPrice.currency : null,
+    amount: amount.value,
+    amount_currency: amount.currency,
+    original_amount: originalAmount.value,
+    original_amount_currency: originalAmount.currency,
+    traded_amount: tradedAmount.value,
+    traded_amount_currency: tradedAmount.currency,
+    total_exchanged: totalExchanged.value,
+    total_exchanged_currency: totalExchanged.currency,
+    paid_fee: paidFee.value,
+    paid_fee_currency: paidFee.currency,
+  };
+}
+
+export async function handleCancelOrderByClientId(
+  args: CancelOrderByClientIdArgs,
+  client: BudaClient,
+): Promise<{ content: Array<{ type: "text"; text: string }>; isError?: boolean }> {
+  const { client_id, confirmation_token } = args;
+
+  if (confirmation_token !== "CONFIRM") {
+    return {
+      content: [
+        {
+          type: "text",
+          text: JSON.stringify({
+            error:
+              "Order not canceled. confirmation_token must equal 'CONFIRM' to execute. " +
+              "Verify the client ID and set confirmation_token='CONFIRM' to proceed.",
+            code: "CONFIRMATION_REQUIRED",
+            client_id,
+          }),
+        },
+      ],
+      isError: true,
+    };
+  }
+
+  try {
+    const data = await client.put<OrderResponse>(
+      `/orders/by-client-id/${encodeURIComponent(client_id)}`,
+      { order: { state: "canceling" } },
+    );
+
+    return {
+      content: [{ type: "text", text: JSON.stringify(normalizeOrder(data.order), null, 2) }],
+    };
+  } catch (err) {
+    const msg =
+      err instanceof BudaApiError
+        ? { error: err.message, code: err.status, path: err.path }
+        : { error: String(err), code: "UNKNOWN" };
+    return {
+      content: [{ type: "text", text: JSON.stringify(msg) }],
+      isError: true,
+    };
+  }
+}
+
+export function register(server: McpServer, client: BudaClient): void {
+  server.tool(
+    toolSchema.name,
+    toolSchema.description,
+    {
+      client_id: z
+        .string()
+        .min(1)
+        .describe("The client ID string assigned when placing the order."),
+      confirmation_token: z
+        .string()
+        .describe(
+          "Safety confirmation. Must equal exactly 'CONFIRM' (case-sensitive) to execute. " +
+            "Any other value will reject the request without canceling.",
+        ),
+    },
+    (args) => handleCancelOrderByClientId(args, client),
+  );
+}

package/src/tools/deposits.ts

@@ -0,0 +1,230 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+import { BudaClient, BudaApiError } from "../client.js";
+import { validateCurrency } from "../validation.js";
+import { flattenAmount } from "../utils.js";
+import type { DepositsResponse, SingleDepositResponse, Deposit } from "../types.js";
+
+export const getDepositHistoryToolSchema = {
+  name: "get_deposit_history",
+  description:
+    "Returns deposit history for a currency on the authenticated Buda.com account. " +
+    "Supports state filtering and pagination. All amounts are floats with separate _currency fields. " +
+    "Requires BUDA_API_KEY and BUDA_API_SECRET. " +
+    "Example: 'Show my last 10 BTC deposits.'",
+  inputSchema: {
+    type: "object" as const,
+    properties: {
+      currency: {
+        type: "string",
+        description: "Currency code (e.g. 'BTC', 'CLP').",
+      },
+      state: {
+        type: "string",
+        description: "Filter by state: 'pending_info', 'pending', 'confirmed', 'anulled', 'retained'.",
+      },
+      per: {
+        type: "number",
+        description: "Results per page (default: 20, max: 300).",
+      },
+      page: {
+        type: "number",
+        description: "Page number (default: 1).",
+      },
+    },
+    required: ["currency"],
+  },
+};
+
+type GetDepositHistoryArgs = {
+  currency: string;
+  state?: "pending_info" | "pending" | "confirmed" | "anulled" | "retained";
+  per?: number;
+  page?: number;
+};
+
+function normalizeDeposit(d: Deposit) {
+  const amount = flattenAmount(d.amount);
+  const fee = flattenAmount(d.fee);
+  return {
+    id: d.id,
+    state: d.state,
+    currency: d.currency,
+    amount: amount.value,
+    amount_currency: amount.currency,
+    fee: fee.value,
+    fee_currency: fee.currency,
+    created_at: d.created_at,
+    updated_at: d.updated_at,
+    transfer_account_id: d.transfer_account_id,
+    transaction_hash: d.transaction_hash,
+  };
+}
+
+export async function handleGetDepositHistory(
+  args: GetDepositHistoryArgs,
+  client: BudaClient,
+): Promise<{ content: Array<{ type: "text"; text: string }>; isError?: boolean }> {
+  const { currency, state, per, page } = args;
+
+  const validationError = validateCurrency(currency);
+  if (validationError) {
+    return {
+      content: [{ type: "text", text: JSON.stringify({ error: validationError, code: "INVALID_CURRENCY" }) }],
+      isError: true,
+    };
+  }
+
+  try {
+    const params: Record<string, string | number> = {};
+    if (state) params.state = state;
+    if (per !== undefined) params.per = per;
+    if (page !== undefined) params.page = page;
+
+    const data = await client.get<DepositsResponse>(
+      `/currencies/${currency.toUpperCase()}/deposits`,
+      Object.keys(params).length > 0 ? params : undefined,
+    );
+
+    return {
+      content: [
+        {
+          type: "text",
+          text: JSON.stringify(
+            {
+              deposits: data.deposits.map(normalizeDeposit),
+              meta: data.meta,
+            },
+            null,
+            2,
+          ),
+        },
+      ],
+    };
+  } catch (err) {
+    const msg =
+      err instanceof BudaApiError
+        ? { error: err.message, code: err.status, path: err.path }
+        : { error: String(err), code: "UNKNOWN" };
+    return {
+      content: [{ type: "text", text: JSON.stringify(msg) }],
+      isError: true,
+    };
+  }
+}
+
+export const createFiatDepositToolSchema = {
+  name: "create_fiat_deposit",
+  description:
+    "Record a fiat deposit on Buda.com. " +
+    "IMPORTANT: Calling this twice creates duplicate records — the confirmation guard is critical. " +
+    "Pass confirmation_token='CONFIRM' to execute. " +
+    "Requires BUDA_API_KEY and BUDA_API_SECRET.",
+  inputSchema: {
+    type: "object" as const,
+    properties: {
+      currency: { type: "string", description: "Fiat currency code (e.g. 'CLP', 'COP', 'PEN')." },
+      amount: { type: "number", description: "Deposit amount." },
+      bank: { type: "string", description: "Bank name or identifier for the deposit source." },
+      confirmation_token: {
+        type: "string",
+        description: "Safety confirmation. Must equal exactly 'CONFIRM' (case-sensitive) to execute.",
+      },
+    },
+    required: ["currency", "amount", "confirmation_token"],
+  },
+};
+
+type CreateFiatDepositArgs = {
+  currency: string;
+  amount: number;
+  bank?: string;
+  confirmation_token: string;
+};
+
+export async function handleCreateFiatDeposit(
+  args: CreateFiatDepositArgs,
+  client: BudaClient,
+): Promise<{ content: Array<{ type: "text"; text: string }>; isError?: boolean }> {
+  const { currency, amount, bank, confirmation_token } = args;
+
+  if (confirmation_token !== "CONFIRM") {
+    return {
+      content: [
+        {
+          type: "text",
+          text: JSON.stringify({
+            error:
+              "Deposit not created. confirmation_token must equal 'CONFIRM' to execute. " +
+              "Review the details and set confirmation_token='CONFIRM' to proceed.",
+            code: "CONFIRMATION_REQUIRED",
+            preview: { currency, amount, bank },
+          }),
+        },
+      ],
+      isError: true,
+    };
+  }
+
+  const validationError = validateCurrency(currency);
+  if (validationError) {
+    return {
+      content: [{ type: "text", text: JSON.stringify({ error: validationError, code: "INVALID_CURRENCY" }) }],
+      isError: true,
+    };
+  }
+
+  try {
+    const payload: Record<string, unknown> = { amount: String(amount) };
+    if (bank) payload.bank = bank;
+
+    const data = await client.post<SingleDepositResponse>(
+      `/currencies/${currency.toUpperCase()}/deposits`,
+      payload,
+    );
+
+    return {
+      content: [{ type: "text", text: JSON.stringify(normalizeDeposit(data.deposit), null, 2) }],
+    };
+  } catch (err) {
+    const msg =
+      err instanceof BudaApiError
+        ? { error: err.message, code: err.status, path: err.path }
+        : { error: String(err), code: "UNKNOWN" };
+    return {
+      content: [{ type: "text", text: JSON.stringify(msg) }],
+      isError: true,
+    };
+  }
+}
+
+export function register(server: McpServer, client: BudaClient): void {
+  server.tool(
+    getDepositHistoryToolSchema.name,
+    getDepositHistoryToolSchema.description,
+    {
+      currency: z.string().min(2).max(10).describe("Currency code (e.g. 'BTC', 'CLP')."),
+      state: z
+        .enum(["pending_info", "pending", "confirmed", "anulled", "retained"])
+        .optional()
+        .describe("Filter by state."),
+      per: z.number().int().min(1).max(300).optional().describe("Results per page (default: 20, max: 300)."),
+      page: z.number().int().min(1).optional().describe("Page number (default: 1)."),
+    },
+    (args) => handleGetDepositHistory(args, client),
+  );
+
+  server.tool(
+    createFiatDepositToolSchema.name,
+    createFiatDepositToolSchema.description,
+    {
+      currency: z.string().min(2).max(10).describe("Fiat currency code (e.g. 'CLP', 'COP', 'PEN')."),
+      amount: z.number().positive().describe("Deposit amount."),
+      bank: z.string().optional().describe("Bank name or identifier for the deposit source."),
+      confirmation_token: z
+        .string()
+        .describe("Safety confirmation. Must equal exactly 'CONFIRM' (case-sensitive) to execute."),
+    },
+    (args) => handleCreateFiatDeposit(args, client),
+  );
+}

package/src/tools/fees.ts

@@ -0,0 +1,91 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+import { BudaClient, BudaApiError } from "../client.js";
+import { validateCurrency } from "../validation.js";
+import { flattenAmount } from "../utils.js";
+import type { FeesResponse } from "../types.js";
+
+export const toolSchema = {
+  name: "get_network_fees",
+  description:
+    "Returns the deposit or withdrawal network fee schedule for a currency on Buda.com. " +
+    "Useful before initiating a transfer to preview costs. " +
+    "Requires BUDA_API_KEY and BUDA_API_SECRET. " +
+    "Example: 'What are the withdrawal fees for BTC?'",
+  inputSchema: {
+    type: "object" as const,
+    properties: {
+      currency: {
+        type: "string",
+        description: "Currency code (e.g. 'BTC', 'ETH', 'CLP').",
+      },
+      type: {
+        type: "string",
+        description: "Fee direction: 'deposit' or 'withdrawal'.",
+      },
+    },
+    required: ["currency", "type"],
+  },
+};
+
+type GetNetworkFeesArgs = { currency: string; type: "deposit" | "withdrawal" };
+
+export async function handleGetNetworkFees(
+  args: GetNetworkFeesArgs,
+  client: BudaClient,
+): Promise<{ content: Array<{ type: "text"; text: string }>; isError?: boolean }> {
+  const { currency, type } = args;
+
+  const validationError = validateCurrency(currency);
+  if (validationError) {
+    return {
+      content: [{ type: "text", text: JSON.stringify({ error: validationError, code: "INVALID_CURRENCY" }) }],
+      isError: true,
+    };
+  }
+
+  try {
+    const data = await client.get<FeesResponse>(`/currencies/${currency.toUpperCase()}/fees/${type}`);
+
+    const fees = data.fees.map((f) => {
+      const baseFee = flattenAmount(f.base_fee);
+      return {
+        name: f.name,
+        fee_type: f.fee_type,
+        base_fee: baseFee.value,
+        base_fee_currency: baseFee.currency,
+        percent: f.percent !== null ? parseFloat(f.percent) : null,
+      };
+    });
+
+    return {
+      content: [
+        {
+          type: "text",
+          text: JSON.stringify({ currency: currency.toUpperCase(), type, fees }, null, 2),
+        },
+      ],
+    };
+  } catch (err) {
+    const msg =
+      err instanceof BudaApiError
+        ? { error: err.message, code: err.status, path: err.path }
+        : { error: String(err), code: "UNKNOWN" };
+    return {
+      content: [{ type: "text", text: JSON.stringify(msg) }],
+      isError: true,
+    };
+  }
+}
+
+export function register(server: McpServer, client: BudaClient): void {
+  server.tool(
+    toolSchema.name,
+    toolSchema.description,
+    {
+      currency: z.string().min(2).max(10).describe("Currency code (e.g. 'BTC', 'ETH', 'CLP')."),
+      type: z.enum(["deposit", "withdrawal"]).describe("Fee direction: 'deposit' or 'withdrawal'."),
+    },
+    (args) => handleGetNetworkFees(args, client),
+  );
+}