@guiie/buda-mcp 1.4.2 → 1.5.0

package/src/tools/receive_addresses.ts

@@ -0,0 +1,216 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+import { BudaClient, BudaApiError } from "../client.js";
+import { validateCurrency } from "../validation.js";
+import type { ReceiveAddressesResponse, SingleReceiveAddressResponse, ReceiveAddress } from "../types.js";
+
+export const createReceiveAddressToolSchema = {
+  name: "create_receive_address",
+  description:
+    "Generates a new receive address for a crypto currency. " +
+    "Creates a new blockchain deposit address for the given currency. " +
+    "Each call generates a distinct address. Not idempotent. " +
+    "Only applicable to crypto currencies (BTC, ETH, etc.). " +
+    "Requires BUDA_API_KEY and BUDA_API_SECRET. " +
+    "Example: 'Give me a fresh Bitcoin deposit address.'",
+  inputSchema: {
+    type: "object" as const,
+    properties: {
+      currency: {
+        type: "string",
+        description: "Currency code (e.g. 'BTC', 'ETH').",
+      },
+    },
+    required: ["currency"],
+  },
+};
+
+export const listReceiveAddressesToolSchema = {
+  name: "list_receive_addresses",
+  description:
+    "Lists all receive (deposit) addresses for a crypto currency on the authenticated Buda.com account. " +
+    "Returns an empty array if no addresses have been created yet. " +
+    "Requires BUDA_API_KEY and BUDA_API_SECRET. " +
+    "Example: 'What are my Bitcoin deposit addresses?'",
+  inputSchema: {
+    type: "object" as const,
+    properties: {
+      currency: {
+        type: "string",
+        description: "Currency code (e.g. 'BTC', 'ETH').",
+      },
+    },
+    required: ["currency"],
+  },
+};
+
+export const getReceiveAddressToolSchema = {
+  name: "get_receive_address",
+  description:
+    "Returns a single receive address by its ID for a given currency on Buda.com. " +
+    "Requires BUDA_API_KEY and BUDA_API_SECRET. " +
+    "Example: 'Get the details of my BTC receive address ID 42.'",
+  inputSchema: {
+    type: "object" as const,
+    properties: {
+      currency: {
+        type: "string",
+        description: "Currency code (e.g. 'BTC', 'ETH').",
+      },
+      id: {
+        type: "number",
+        description: "The numeric ID of the receive address.",
+      },
+    },
+    required: ["currency", "id"],
+  },
+};
+
+function normalizeAddress(a: ReceiveAddress) {
+  return {
+    id: a.id,
+    address: a.address,
+    currency: a.currency,
+    created_at: a.created_at,
+    label: a.label ?? null,
+  };
+}
+
+export async function handleListReceiveAddresses(
+  args: { currency: string },
+  client: BudaClient,
+): 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,
+    };
+  }
+
+  try {
+    const data = await client.get<ReceiveAddressesResponse>(
+      `/currencies/${currency.toUpperCase()}/receive_addresses`,
+    );
+    return {
+      content: [
+        {
+          type: "text",
+          text: JSON.stringify(
+            { receive_addresses: data.receive_addresses.map(normalizeAddress) },
+            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 handleGetReceiveAddress(
+  args: { currency: string; id: number },
+  client: BudaClient,
+): Promise<{ content: Array<{ type: "text"; text: string }>; isError?: boolean }> {
+  const { currency, id } = 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<SingleReceiveAddressResponse>(
+      `/currencies/${currency.toUpperCase()}/receive_addresses/${id}`,
+    );
+    return {
+      content: [{ type: "text", text: JSON.stringify(normalizeAddress(data.receive_address), 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 handleCreateReceiveAddress(
+  args: { currency: string },
+  client: BudaClient,
+): 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,
+    };
+  }
+
+  try {
+    const data = await client.post<SingleReceiveAddressResponse>(
+      `/currencies/${currency.toUpperCase()}/receive_addresses`,
+      {},
+    );
+    return {
+      content: [{ type: "text", text: JSON.stringify(normalizeAddress(data.receive_address), 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(
+    listReceiveAddressesToolSchema.name,
+    listReceiveAddressesToolSchema.description,
+    {
+      currency: z.string().min(2).max(10).describe("Currency code (e.g. 'BTC', 'ETH')."),
+    },
+    (args) => handleListReceiveAddresses(args, client),
+  );
+
+  server.tool(
+    getReceiveAddressToolSchema.name,
+    getReceiveAddressToolSchema.description,
+    {
+      currency: z.string().min(2).max(10).describe("Currency code (e.g. 'BTC', 'ETH')."),
+      id: z.number().int().positive().describe("The numeric ID of the receive address."),
+    },
+    (args) => handleGetReceiveAddress(args, client),
+  );
+
+  server.tool(
+    createReceiveAddressToolSchema.name,
+    createReceiveAddressToolSchema.description,
+    {
+      currency: z.string().min(2).max(10).describe("Currency code (e.g. 'BTC', 'ETH')."),
+    },
+    (args) => handleCreateReceiveAddress(args, client),
+  );
+}

package/src/tools/remittance_recipients.ts

@@ -0,0 +1,139 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+import { BudaClient, BudaApiError } from "../client.js";
+import type { RemittanceRecipientsResponse, SingleRemittanceRecipientResponse, RemittanceRecipient } from "../types.js";
+
+export const listToolSchema = {
+  name: "list_remittance_recipients",
+  description:
+    "Lists all saved remittance recipients (bank accounts) for the authenticated Buda.com account. " +
+    "Supports pagination. " +
+    "Requires BUDA_API_KEY and BUDA_API_SECRET. " +
+    "Example: 'Who are my saved remittance recipients?'",
+  inputSchema: {
+    type: "object" as const,
+    properties: {
+      per: {
+        type: "number",
+        description: "Results per page (default: 20, max: 300).",
+      },
+      page: {
+        type: "number",
+        description: "Page number (default: 1).",
+      },
+    },
+  },
+};
+
+export const getToolSchema = {
+  name: "get_remittance_recipient",
+  description:
+    "Returns a single saved remittance recipient by its ID on Buda.com. " +
+    "Fetches saved bank details for one recipient. " +
+    "Requires BUDA_API_KEY and BUDA_API_SECRET. " +
+    "Example: 'Show remittance recipient ID 5.'",
+  inputSchema: {
+    type: "object" as const,
+    properties: {
+      id: {
+        type: "number",
+        description: "The numeric ID of the remittance recipient.",
+      },
+    },
+    required: ["id"],
+  },
+};
+
+function normalizeRecipient(r: RemittanceRecipient) {
+  return {
+    id: r.id,
+    name: r.name,
+    bank: r.bank,
+    account_number: r.account_number,
+    currency: r.currency,
+    country: r.country ?? null,
+  };
+}
+
+export async function handleListRemittanceRecipients(
+  args: { per?: number; page?: number },
+  client: BudaClient,
+): Promise<{ content: Array<{ type: "text"; text: string }>; isError?: boolean }> {
+  try {
+    const params: Record<string, string | number> = {};
+    if (args.per !== undefined) params.per = args.per;
+    if (args.page !== undefined) params.page = args.page;
+
+    const data = await client.get<RemittanceRecipientsResponse>(
+      "/remittance_recipients",
+      Object.keys(params).length > 0 ? params : undefined,
+    );
+
+    return {
+      content: [
+        {
+          type: "text",
+          text: JSON.stringify(
+            {
+              remittance_recipients: data.remittance_recipients.map(normalizeRecipient),
+              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 async function handleGetRemittanceRecipient(
+  args: { id: number },
+  client: BudaClient,
+): Promise<{ content: Array<{ type: "text"; text: string }>; isError?: boolean }> {
+  try {
+    const data = await client.get<SingleRemittanceRecipientResponse>(`/remittance_recipients/${args.id}`);
+    return {
+      content: [{ type: "text", text: JSON.stringify(normalizeRecipient(data.remittance_recipient), 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(
+    listToolSchema.name,
+    listToolSchema.description,
+    {
+      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) => handleListRemittanceRecipients(args, client),
+  );
+
+  server.tool(
+    getToolSchema.name,
+    getToolSchema.description,
+    {
+      id: z.number().int().positive().describe("The numeric ID of the remittance recipient."),
+    },
+    (args) => handleGetRemittanceRecipient(args, client),
+  );
+}

package/src/tools/remittances.ts

@@ -0,0 +1,299 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+import { BudaClient, BudaApiError } from "../client.js";
+import { flattenAmount } from "../utils.js";
+import { validateCurrency } from "../validation.js";
+import type { RemittancesResponse, SingleRemittanceResponse, Remittance } from "../types.js";
+
+export const listRemittancesToolSchema = {
+  name: "list_remittances",
+  description:
+    "Returns all fiat remittance transfers for the authenticated Buda.com account. " +
+    "Supports pagination. All amounts are floats with separate _currency fields. " +
+    "Requires BUDA_API_KEY and BUDA_API_SECRET. " +
+    "Example: 'List my recent remittances.'",
+  inputSchema: {
+    type: "object" as const,
+    properties: {
+      per: {
+        type: "number",
+        description: "Results per page (default: 20, max: 300).",
+      },
+      page: {
+        type: "number",
+        description: "Page number (default: 1).",
+      },
+    },
+  },
+};
+
+export const quoteRemittanceToolSchema = {
+  name: "quote_remittance",
+  description:
+    "Creates a time-limited remittance quote without committing funds. " +
+    "Requests a price quote for a fiat remittance to a saved recipient. " +
+    "Returns a remittance object in 'quoted' state with an expiry timestamp. " +
+    "NOT idempotent — creates a new remittance record each call. " +
+    "To execute, call accept_remittance_quote with the returned ID before it expires. " +
+    "Requires BUDA_API_KEY and BUDA_API_SECRET. " +
+    "Example: 'Get a remittance quote to send 100000 CLP to recipient 5.'",
+  inputSchema: {
+    type: "object" as const,
+    properties: {
+      currency: {
+        type: "string",
+        description: "Fiat currency code (e.g. 'CLP', 'COP').",
+      },
+      amount: {
+        type: "number",
+        description: "Amount to remit (positive number).",
+      },
+      recipient_id: {
+        type: "number",
+        description: "ID of the saved remittance recipient.",
+      },
+    },
+    required: ["currency", "amount", "recipient_id"],
+  },
+};
+
+export const acceptRemittanceQuoteToolSchema = {
+  name: "accept_remittance_quote",
+  description:
+    "Accepts and executes a pending remittance quote. " +
+    "Commits a previously quoted remittance, triggering a real fiat transfer. " +
+    "IRREVERSIBLE once the transfer is initiated. " +
+    "You must pass confirmation_token='CONFIRM' to proceed. " +
+    "Requires BUDA_API_KEY and BUDA_API_SECRET. " +
+    "Example: \"Accept remittance quote 77 — set confirmation_token='CONFIRM'.\"",
+  inputSchema: {
+    type: "object" as const,
+    properties: {
+      id: {
+        type: "number",
+        description: "The numeric ID of the remittance quote to accept.",
+      },
+      confirmation_token: {
+        type: "string",
+        description: "Must be 'CONFIRM' to proceed. Any other value aborts.",
+      },
+    },
+    required: ["id", "confirmation_token"],
+  },
+};
+
+export const getRemittanceToolSchema = {
+  name: "get_remittance",
+  description:
+    "Returns a single remittance by its ID on Buda.com. " +
+    "Fetches current state and details. " +
+    "Requires BUDA_API_KEY and BUDA_API_SECRET. " +
+    "Example: 'What is the status of remittance 77?'",
+  inputSchema: {
+    type: "object" as const,
+    properties: {
+      id: {
+        type: "number",
+        description: "The numeric ID of the remittance.",
+      },
+    },
+    required: ["id"],
+  },
+};
+
+function normalizeRemittance(r: Remittance) {
+  const amount = flattenAmount(r.amount);
+  return {
+    id: r.id,
+    state: r.state,
+    currency: r.currency,
+    amount: amount.value,
+    amount_currency: amount.currency,
+    recipient_id: r.recipient_id,
+    created_at: r.created_at,
+    expires_at: r.expires_at ?? null,
+  };
+}
+
+export async function handleListRemittances(
+  args: { per?: number; page?: number },
+  client: BudaClient,
+): Promise<{ content: Array<{ type: "text"; text: string }>; isError?: boolean }> {
+  try {
+    const params: Record<string, string | number> = {};
+    if (args.per !== undefined) params.per = args.per;
+    if (args.page !== undefined) params.page = args.page;
+
+    const data = await client.get<RemittancesResponse>(
+      "/remittances",
+      Object.keys(params).length > 0 ? params : undefined,
+    );
+
+    return {
+      content: [
+        {
+          type: "text",
+          text: JSON.stringify(
+            {
+              remittances: data.remittances.map(normalizeRemittance),
+              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 async function handleGetRemittance(
+  args: { id: number },
+  client: BudaClient,
+): Promise<{ content: Array<{ type: "text"; text: string }>; isError?: boolean }> {
+  try {
+    const data = await client.get<SingleRemittanceResponse>(`/remittances/${args.id}`);
+    return {
+      content: [{ type: "text", text: JSON.stringify(normalizeRemittance(data.remittance), 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 handleQuoteRemittance(
+  args: { currency: string; amount: number; recipient_id: number },
+  client: BudaClient,
+): Promise<{ content: Array<{ type: "text"; text: string }>; isError?: boolean }> {
+  const { currency, amount, recipient_id } = 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.post<SingleRemittanceResponse>("/remittances", {
+      remittance: {
+        currency: currency.toUpperCase(),
+        amount: String(amount),
+        recipient_id,
+      },
+    });
+    return {
+      content: [{ type: "text", text: JSON.stringify(normalizeRemittance(data.remittance), 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 handleAcceptRemittanceQuote(
+  args: { id: number; confirmation_token: string },
+  client: BudaClient,
+): Promise<{ content: Array<{ type: "text"; text: string }>; isError?: boolean }> {
+  const { id, confirmation_token } = args;
+
+  if (confirmation_token !== "CONFIRM") {
+    return {
+      content: [
+        {
+          type: "text",
+          text: JSON.stringify({
+            error:
+              "Accepting a remittance quote is irreversible. Pass confirmation_token='CONFIRM' to proceed.",
+            code: "CONFIRMATION_REQUIRED",
+            remittance_id: id,
+          }),
+        },
+      ],
+      isError: true,
+    };
+  }
+
+  try {
+    const data = await client.put<SingleRemittanceResponse>(`/remittances/${id}`, {
+      remittance: { state: "confirming" },
+    });
+    return {
+      content: [{ type: "text", text: JSON.stringify(normalizeRemittance(data.remittance), 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(
+    listRemittancesToolSchema.name,
+    listRemittancesToolSchema.description,
+    {
+      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) => handleListRemittances(args, client),
+  );
+
+  server.tool(
+    getRemittanceToolSchema.name,
+    getRemittanceToolSchema.description,
+    {
+      id: z.number().int().positive().describe("The numeric ID of the remittance."),
+    },
+    (args) => handleGetRemittance(args, client),
+  );
+
+  server.tool(
+    quoteRemittanceToolSchema.name,
+    quoteRemittanceToolSchema.description,
+    {
+      currency: z.string().min(2).max(10).describe("Fiat currency code (e.g. 'CLP', 'COP')."),
+      amount: z.number().positive().describe("Amount to remit (positive number)."),
+      recipient_id: z.number().int().positive().describe("ID of the saved remittance recipient."),
+    },
+    (args) => handleQuoteRemittance(args, client),
+  );
+
+  server.tool(
+    acceptRemittanceQuoteToolSchema.name,
+    acceptRemittanceQuoteToolSchema.description,
+    {
+      id: z.number().int().positive().describe("The numeric ID of the remittance quote to accept."),
+      confirmation_token: z.string().describe("Must be 'CONFIRM' to proceed. Any other value aborts."),
+    },
+    (args) => handleAcceptRemittanceQuote(args, client),
+  );
+}

package/src/tools/simulate_order.ts

@@ -8,6 +8,7 @@ import type { TickerResponse, MarketResponse } from "../types.js";
 export const toolSchema = {
   name: "simulate_order",
   description:
+    "[DEPRECATED: prefer get_real_quotation for server-side accurate quotes] " +
     "Simulates a buy or sell order on Buda.com using live ticker data — no order is placed. " +
     "Returns estimated fill price, fee, total cost, and slippage vs mid-price. " +
     "Omit 'price' for a market order simulation; supply 'price' for a limit order simulation. " +