@guiie/buda-mcp 1.4.2 → 1.5.1

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),
+  );
+}

package/src/tools/lightning.ts

@@ -0,0 +1,247 @@
+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 { LightningWithdrawalResponse, LightningInvoiceResponse } from "../types.js";
+
+export const lightningWithdrawalToolSchema = {
+  name: "lightning_withdrawal",
+  description:
+    "Pay a Bitcoin Lightning Network invoice from your Buda.com LN-BTC reserve. " +
+    "IMPORTANT: Funds leave the account immediately on success. " +
+    "Pass confirmation_token='CONFIRM' to execute. " +
+    "Requires BUDA_API_KEY and BUDA_API_SECRET.",
+  inputSchema: {
+    type: "object" as const,
+    properties: {
+      invoice: {
+        type: "string",
+        description: "BOLT-11 Lightning invoice string (starts with 'lnbc', 'lntb', etc.).",
+      },
+      confirmation_token: {
+        type: "string",
+        description:
+          "Safety confirmation. Must equal exactly 'CONFIRM' (case-sensitive) to execute. " +
+          "Any other value will reject the request without paying.",
+      },
+    },
+    required: ["invoice", "confirmation_token"],
+  },
+};
+
+export const createLightningInvoiceToolSchema = {
+  name: "create_lightning_invoice",
+  description:
+    "Create a Bitcoin Lightning Network invoice on Buda.com to receive a payment. " +
+    "No funds leave the account — no confirmation required. " +
+    "Requires BUDA_API_KEY and BUDA_API_SECRET.",
+  inputSchema: {
+    type: "object" as const,
+    properties: {
+      amount_satoshis: {
+        type: "number",
+        description: "Invoice amount in satoshis (positive integer).",
+      },
+      description: {
+        type: "string",
+        description: "Optional payment description (max 140 characters).",
+      },
+      expiry_seconds: {
+        type: "number",
+        description: "Invoice expiry in seconds (60–86400, default: 3600).",
+      },
+    },
+    required: ["amount_satoshis"],
+  },
+};
+
+type LightningWithdrawalArgs = {
+  invoice: string;
+  confirmation_token: string;
+};
+
+type CreateLightningInvoiceArgs = {
+  amount_satoshis: number;
+  description?: string;
+  expiry_seconds?: number;
+};
+
+export async function handleLightningWithdrawal(
+  args: LightningWithdrawalArgs,
+  client: BudaClient,
+): Promise<{ content: Array<{ type: "text"; text: string }>; isError?: boolean }> {
+  const { invoice, confirmation_token } = args;
+
+  if (confirmation_token !== "CONFIRM") {
+    const preview = invoice.length > 20 ? invoice.substring(0, 20) + "..." : invoice;
+    return {
+      content: [
+        {
+          type: "text",
+          text: JSON.stringify({
+            error:
+              "Lightning withdrawal not executed. confirmation_token must equal 'CONFIRM' to execute. " +
+              "Review the invoice and set confirmation_token='CONFIRM' to proceed.",
+            code: "CONFIRMATION_REQUIRED",
+            preview: { invoice_preview: preview },
+          }),
+        },
+      ],
+      isError: true,
+    };
+  }
+
+  const BOLT11_RE = /^ln(bc|tb|bcrt)\d/i;
+  if (!BOLT11_RE.test(invoice)) {
+    return {
+      content: [{
+        type: "text",
+        text: JSON.stringify({
+          error:
+            "Invalid Lightning invoice format. " +
+            "Expected a BOLT-11 string starting with 'lnbc', 'lntb', or 'lnbcrt'.",
+          code: "INVALID_INVOICE",
+        }),
+      }],
+      isError: true,
+    };
+  }
+
+  try {
+    const data = await client.post<LightningWithdrawalResponse>(
+      `/reserves/ln-btc/withdrawals`,
+      { invoice },
+    );
+
+    const lw = data.lightning_withdrawal;
+    const amount = flattenAmount(lw.amount);
+    const fee = flattenAmount(lw.fee);
+
+    return {
+      content: [
+        {
+          type: "text",
+          text: JSON.stringify(
+            {
+              id: lw.id,
+              state: lw.state,
+              amount: amount.value,
+              amount_currency: amount.currency,
+              fee: fee.value,
+              fee_currency: fee.currency,
+              payment_hash: lw.payment_hash,
+              created_at: lw.created_at,
+            },
+            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 async function handleCreateLightningInvoice(
+  args: CreateLightningInvoiceArgs,
+  client: BudaClient,
+): Promise<{ content: Array<{ type: "text"; text: string }>; isError?: boolean }> {
+  const { amount_satoshis, description, expiry_seconds } = args;
+
+  try {
+    const invoicePayload: Record<string, unknown> = { amount: amount_satoshis };
+    if (description !== undefined) invoicePayload.description = description;
+    if (expiry_seconds !== undefined) invoicePayload.expiry = expiry_seconds;
+
+    const data = await client.post<LightningInvoiceResponse>(
+      `/lightning_network_invoices`,
+      { lightning_network_invoice: invoicePayload },
+    );
+
+    const inv = data.lightning_network_invoice;
+    const amount = flattenAmount(inv.amount);
+
+    return {
+      content: [
+        {
+          type: "text",
+          text: JSON.stringify(
+            {
+              id: inv.id,
+              payment_request: inv.payment_request,
+              amount_satoshis: amount.value,
+              description: inv.description,
+              expires_at: inv.expires_at,
+              state: inv.state,
+              created_at: inv.created_at,
+            },
+            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(
+    lightningWithdrawalToolSchema.name,
+    lightningWithdrawalToolSchema.description,
+    {
+      invoice: z
+        .string()
+        .min(50)
+        .describe("BOLT-11 Lightning invoice string (starts with 'lnbc', 'lntb', etc.)."),
+      confirmation_token: z
+        .string()
+        .describe(
+          "Safety confirmation. Must equal exactly 'CONFIRM' (case-sensitive) to execute. " +
+            "Any other value will reject the request without paying.",
+        ),
+    },
+    (args) => handleLightningWithdrawal(args, client),
+  );
+
+  server.tool(
+    createLightningInvoiceToolSchema.name,
+    createLightningInvoiceToolSchema.description,
+    {
+      amount_satoshis: z
+        .number()
+        .int()
+        .positive()
+        .describe("Invoice amount in satoshis (positive integer)."),
+      description: z
+        .string()
+        .max(140)
+        .optional()
+        .describe("Optional payment description (max 140 characters)."),
+      expiry_seconds: z
+        .number()
+        .int()
+        .min(60)
+        .max(86400)
+        .optional()
+        .describe("Invoice expiry in seconds (60–86400, default: 3600)."),
+    },
+    (args) => handleCreateLightningInvoice(args, client),
+  );
+}

package/src/tools/order_lookup.ts

@@ -0,0 +1,139 @@
+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 getOrderToolSchema = {
+  name: "get_order",
+  description:
+    "Returns a single order by its numeric ID on Buda.com. " +
+    "Fetches full detail including state, amounts, fees, and timestamps. " +
+    "All monetary amounts are floats with separate _currency fields. " +
+    "Requires BUDA_API_KEY and BUDA_API_SECRET. " +
+    "Example: 'Show me the details of order 987654.'",
+  inputSchema: {
+    type: "object" as const,
+    properties: {
+      order_id: {
+        type: "number",
+        description: "The numeric ID of the order.",
+      },
+    },
+    required: ["order_id"],
+  },
+};
+
+export const getOrderByClientIdToolSchema = {
+  name: "get_order_by_client_id",
+  description:
+    "Returns an order by the client-assigned ID you set at placement on Buda.com. " +
+    "All monetary amounts are floats with separate _currency fields. " +
+    "Requires BUDA_API_KEY and BUDA_API_SECRET. " +
+    "Example: 'Find my order with client ID my-bot-order-42.'",
+  inputSchema: {
+    type: "object" as const,
+    properties: {
+      client_id: {
+        type: "string",
+        description: "The client ID string assigned when placing the order.",
+      },
+    },
+    required: ["client_id"],
+  },
+};
+
+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 handleGetOrder(
+  args: { order_id: number },
+  client: BudaClient,
+): Promise<{ content: Array<{ type: "text"; text: string }>; isError?: boolean }> {
+  try {
+    const data = await client.get<OrderResponse>(`/orders/${args.order_id}`);
+    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 async function handleGetOrderByClientId(
+  args: { client_id: string },
+  client: BudaClient,
+): Promise<{ content: Array<{ type: "text"; text: string }>; isError?: boolean }> {
+  try {
+    const data = await client.get<OrderResponse>(`/orders/by-client-id/${encodeURIComponent(args.client_id)}`);
+    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(
+    getOrderToolSchema.name,
+    getOrderToolSchema.description,
+    {
+      order_id: z.number().int().positive().describe("The numeric ID of the order."),
+    },
+    (args) => handleGetOrder(args, client),
+  );
+
+  server.tool(
+    getOrderByClientIdToolSchema.name,
+    getOrderByClientIdToolSchema.description,
+    {
+      client_id: z.string().min(1).describe("The client ID string assigned when placing the order."),
+    },
+    (args) => handleGetOrderByClientId(args, client),
+  );
+}