@guiie/buda-mcp 1.4.2 → 1.5.0

package/server.json

@@ -6,12 +6,12 @@
     "url": "https://github.com/gtorreal/buda-mcp",
     "source": "github"
   },
-  "version": "1.4.2",
+  "version": "1.5.0",
   "packages": [
     {
       "registryType": "npm",
       "identifier": "@guiie/buda-mcp",
-      "version": "1.4.2",
+      "version": "1.5.0",
       "transport": {
         "type": "stdio"
       }

package/src/cache.ts

@@ -45,6 +45,7 @@ export const CACHE_TTL = {
   MARKETS: 60_000,
   TICKER: 5_000,
   ORDERBOOK: 3_000,
+  BANKS: 60_000,
 } as const;
 
 export const cache = new MemoryCache();

package/src/client.ts

@@ -173,4 +173,24 @@ export class BudaClient {
     );
     return this.handleResponse<T>(response, path);
   }
+
+  async delete<T>(path: string, params?: Record<string, string | number>): Promise<T> {
+    const url = new URL(`${this.baseUrl}${path}.json`);
+
+    if (params) {
+      for (const [key, value] of Object.entries(params)) {
+        url.searchParams.set(key, String(value));
+      }
+    }
+
+    const urlPath = url.pathname + url.search;
+    const headers: Record<string, string> = {
+      Accept: "application/json",
+      "User-Agent": `buda-mcp/${VERSION}`,
+      ...this.authHeaders("DELETE", urlPath),
+    };
+
+    const response = await this.fetchWithRetry(url, { method: "DELETE", headers }, path);
+    return this.handleResponse<T>(response, path);
+  }
 }

package/src/http.ts

@@ -24,6 +24,21 @@ import * as positionSize from "./tools/calculate_position_size.js";
 import * as marketSentiment from "./tools/market_sentiment.js";
 import * as technicalIndicators from "./tools/technical_indicators.js";
 import * as deadMansSwitch from "./tools/dead_mans_switch.js";
+import * as banks from "./tools/banks.js";
+import * as account from "./tools/account.js";
+import * as balance from "./tools/balance.js";
+import * as orderLookup from "./tools/order_lookup.js";
+import * as networkFees from "./tools/fees.js";
+import * as deposits from "./tools/deposits.js";
+import * as withdrawals from "./tools/withdrawals.js";
+import * as receiveAddresses from "./tools/receive_addresses.js";
+import * as remittances from "./tools/remittances.js";
+import * as remittanceRecipients from "./tools/remittance_recipients.js";
+import * as quotation from "./tools/quotation.js";
+import * as cancelAllOrders from "./tools/cancel_all_orders.js";
+import * as cancelOrderByClientId from "./tools/cancel_order_by_client_id.js";
+import * as batchOrders from "./tools/batch_orders.js";
+import * as lightning from "./tools/lightning.js";
 import { handleMarketSummary } from "./tools/market_summary.js";
 
 const PORT = parseInt(process.env.PORT ?? "3000", 10);
@@ -50,9 +65,11 @@ const PUBLIC_TOOL_SCHEMAS = [
   arbitrage.toolSchema,
   marketSummary.toolSchema,
   simulateOrder.toolSchema,
+  quotation.toolSchema,
   positionSize.toolSchema,
   marketSentiment.toolSchema,
   technicalIndicators.toolSchema,
+  banks.toolSchema,
 ];
 
 const AUTH_TOOL_SCHEMAS = [
@@ -63,6 +80,29 @@ const AUTH_TOOL_SCHEMAS = [
   deadMansSwitch.toolSchema,
   deadMansSwitch.renewToolSchema,
   deadMansSwitch.disarmToolSchema,
+  account.toolSchema,
+  balance.toolSchema,
+  orderLookup.getOrderToolSchema,
+  orderLookup.getOrderByClientIdToolSchema,
+  networkFees.toolSchema,
+  deposits.getDepositHistoryToolSchema,
+  withdrawals.getWithdrawalHistoryToolSchema,
+  receiveAddresses.listReceiveAddressesToolSchema,
+  receiveAddresses.getReceiveAddressToolSchema,
+  remittances.listRemittancesToolSchema,
+  remittances.getRemittanceToolSchema,
+  remittances.quoteRemittanceToolSchema,
+  remittances.acceptRemittanceQuoteToolSchema,
+  remittanceRecipients.listToolSchema,
+  remittanceRecipients.getToolSchema,
+  receiveAddresses.createReceiveAddressToolSchema,
+  cancelAllOrders.toolSchema,
+  cancelOrderByClientId.toolSchema,
+  batchOrders.toolSchema,
+  withdrawals.createWithdrawalToolSchema,
+  deposits.createFiatDepositToolSchema,
+  lightning.lightningWithdrawalToolSchema,
+  lightning.createLightningInvoiceToolSchema,
 ];
 
 function createServer(): McpServer {
@@ -82,9 +122,11 @@ function createServer(): McpServer {
   arbitrage.register(server, client, reqCache);
   marketSummary.register(server, client, reqCache);
   simulateOrder.register(server, client, reqCache);
+  quotation.register(server, client);
   positionSize.register(server);
   marketSentiment.register(server, client, reqCache);
   technicalIndicators.register(server, client);
+  banks.register(server, client, reqCache);
 
   if (authEnabled) {
     balances.register(server, client);
@@ -92,6 +134,19 @@ function createServer(): McpServer {
     placeOrder.register(server, client);
     cancelOrder.register(server, client);
     deadMansSwitch.register(server, client);
+    account.register(server, client);
+    balance.register(server, client);
+    orderLookup.register(server, client);
+    networkFees.register(server, client);
+    deposits.register(server, client);
+    withdrawals.register(server, client);
+    receiveAddresses.register(server, client);
+    remittances.register(server, client);
+    remittanceRecipients.register(server, client);
+    cancelAllOrders.register(server, client);
+    cancelOrderByClientId.register(server, client);
+    batchOrders.register(server, client);
+    lightning.register(server, client);
   }
 
   // MCP Resources

package/src/index.ts

@@ -25,6 +25,21 @@ import * as positionSize from "./tools/calculate_position_size.js";
 import * as marketSentiment from "./tools/market_sentiment.js";
 import * as technicalIndicators from "./tools/technical_indicators.js";
 import * as deadMansSwitch from "./tools/dead_mans_switch.js";
+import * as banks from "./tools/banks.js";
+import * as account from "./tools/account.js";
+import * as balance from "./tools/balance.js";
+import * as orderLookup from "./tools/order_lookup.js";
+import * as networkFees from "./tools/fees.js";
+import * as deposits from "./tools/deposits.js";
+import * as withdrawals from "./tools/withdrawals.js";
+import * as receiveAddresses from "./tools/receive_addresses.js";
+import * as remittances from "./tools/remittances.js";
+import * as remittanceRecipients from "./tools/remittance_recipients.js";
+import * as quotation from "./tools/quotation.js";
+import * as cancelAllOrders from "./tools/cancel_all_orders.js";
+import * as cancelOrderByClientId from "./tools/cancel_order_by_client_id.js";
+import * as batchOrders from "./tools/batch_orders.js";
+import * as lightning from "./tools/lightning.js";
 import { handleMarketSummary } from "./tools/market_summary.js";
 
 const client = new BudaClient(
@@ -50,9 +65,11 @@ priceHistory.register(server, client, cache);
 arbitrage.register(server, client, cache);
 marketSummary.register(server, client, cache);
 simulateOrder.register(server, client, cache);
+quotation.register(server, client);
 positionSize.register(server);
 marketSentiment.register(server, client, cache);
 technicalIndicators.register(server, client);
+banks.register(server, client, cache);
 
 // Auth-gated tools — only registered when API credentials are present
 if (client.hasAuth()) {
@@ -61,6 +78,19 @@ if (client.hasAuth()) {
   placeOrder.register(server, client);
   cancelOrder.register(server, client);
   deadMansSwitch.register(server, client);
+  account.register(server, client);
+  balance.register(server, client);
+  orderLookup.register(server, client);
+  networkFees.register(server, client);
+  deposits.register(server, client);
+  withdrawals.register(server, client);
+  receiveAddresses.register(server, client);
+  remittances.register(server, client);
+  remittanceRecipients.register(server, client);
+  cancelAllOrders.register(server, client);
+  cancelOrderByClientId.register(server, client);
+  batchOrders.register(server, client);
+  lightning.register(server, client);
 }
 
 // MCP Resources

package/src/tools/account.ts

@@ -0,0 +1,66 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { BudaClient, BudaApiError } from "../client.js";
+import { flattenAmount } from "../utils.js";
+import type { MeResponse } from "../types.js";
+
+export const toolSchema = {
+  name: "get_account_info",
+  description:
+    "Returns the authenticated user's profile on Buda.com. " +
+    "Fetches account details including email, display name, pubsub key, and monthly transacted amounts. " +
+    "Read-only; no side effects. " +
+    "Requires BUDA_API_KEY and BUDA_API_SECRET. " +
+    "Example: 'What is my account email and how much have I transacted this month?'",
+  inputSchema: {
+    type: "object" as const,
+    properties: {},
+  },
+};
+
+export async function handleGetAccountInfo(
+  client: BudaClient,
+): Promise<{ content: Array<{ type: "text"; text: string }>; isError?: boolean }> {
+  try {
+    const data = await client.get<MeResponse>("/me");
+    const me = data.me;
+    const monthly = flattenAmount(me.monthly_transacted);
+
+    return {
+      content: [
+        {
+          type: "text",
+          text: JSON.stringify(
+            {
+              id: me.id,
+              email: me.email,
+              name: me.name ?? null,
+              monthly_transacted: monthly.value,
+              monthly_transacted_currency: monthly.currency,
+              pubsub_key: me.pubsub_key ?? null,
+            },
+            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,
+    {},
+    () => handleGetAccountInfo(client),
+  );
+}

package/src/tools/balance.ts

@@ -0,0 +1,94 @@
+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 { SingleBalanceResponse } from "../types.js";
+
+export const toolSchema = {
+  name: "get_balance",
+  description:
+    "Returns the balance for a single currency for the authenticated Buda.com account. " +
+    "Fetches total, available, frozen, and pending-withdrawal amounts as floats with separate _currency fields. " +
+    "Requires BUDA_API_KEY and BUDA_API_SECRET. " +
+    "Example: 'How much ETH do I have available?'",
+  inputSchema: {
+    type: "object" as const,
+    properties: {
+      currency: {
+        type: "string",
+        description: "Currency code (e.g. 'BTC', 'CLP', 'USDC').",
+      },
+    },
+    required: ["currency"],
+  },
+};
+
+type GetBalanceArgs = { currency: string };
+
+export async function handleGetBalance(
+  args: GetBalanceArgs,
+  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<SingleBalanceResponse>(`/balances/${currency.toUpperCase()}`);
+    const b = data.balance;
+    const amount = flattenAmount(b.amount);
+    const available = flattenAmount(b.available_amount);
+    const frozen = flattenAmount(b.frozen_amount);
+    const pending = flattenAmount(b.pending_withdraw_amount);
+
+    return {
+      content: [
+        {
+          type: "text",
+          text: JSON.stringify(
+            {
+              id: b.id,
+              amount: amount.value,
+              amount_currency: amount.currency,
+              available_amount: available.value,
+              available_amount_currency: available.currency,
+              frozen_amount: frozen.value,
+              frozen_amount_currency: frozen.currency,
+              pending_withdraw_amount: pending.value,
+              pending_withdraw_amount_currency: pending.currency,
+            },
+            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', 'CLP', 'USDC')."),
+    },
+    (args) => handleGetBalance(args, client),
+  );
+}

package/src/tools/banks.ts

@@ -0,0 +1,94 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+import { BudaClient, BudaApiError } from "../client.js";
+import { MemoryCache, CACHE_TTL } from "../cache.js";
+import { validateCurrency } from "../validation.js";
+import type { BanksResponse } from "../types.js";
+
+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"],
+  },
+};
+
+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 =
+      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, 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),
+  );
+}

package/src/tools/batch_orders.ts

@@ -0,0 +1,199 @@
+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 { OrderResponse } from "../types.js";
+
+export const toolSchema = {
+  name: "place_batch_orders",
+  description:
+    "Place multiple orders sequentially on Buda.com (up to 20). " +
+    "All orders are pre-validated before any API call — a validation failure stops execution with zero orders placed. " +
+    "Partial API failures do NOT roll back already-placed orders. " +
+    "IMPORTANT: Pass confirmation_token='CONFIRM' to execute. " +
+    "Requires BUDA_API_KEY and BUDA_API_SECRET.",
+  inputSchema: {
+    type: "object" as const,
+    properties: {
+      orders: {
+        type: "array",
+        description: "Array of 1–20 orders to place.",
+        items: {
+          type: "object",
+          properties: {
+            market_id: { type: "string", description: "Market ID (e.g. 'BTC-CLP')." },
+            type: { type: "string", enum: ["Bid", "Ask"], description: "Order side." },
+            price_type: { type: "string", enum: ["limit", "market"], description: "Order type." },
+            amount: { type: "number", description: "Order size in base currency." },
+            limit_price: { type: "number", description: "Required when price_type is 'limit'." },
+          },
+          required: ["market_id", "type", "price_type", "amount"],
+        },
+      },
+      confirmation_token: {
+        type: "string",
+        description:
+          "Safety confirmation. Must equal exactly 'CONFIRM' (case-sensitive) to execute.",
+      },
+    },
+    required: ["orders", "confirmation_token"],
+  },
+};
+
+const orderShape = z.object({
+  market_id: z.string(),
+  type: z.enum(["Bid", "Ask"]),
+  price_type: z.enum(["limit", "market"]),
+  amount: z.number().positive(),
+  limit_price: z.number().positive().optional(),
+});
+
+type SingleOrderInput = z.infer<typeof orderShape>;
+
+type BatchResult = {
+  index: number;
+  market_id: string;
+  success: boolean;
+  order?: unknown;
+  error?: string;
+  code?: number | string;
+};
+
+type BatchOrdersArgs = {
+  orders: SingleOrderInput[];
+  confirmation_token: string;
+};
+
+export async function handlePlaceBatchOrders(
+  args: BatchOrdersArgs,
+  client: BudaClient,
+): Promise<{ content: Array<{ type: "text"; text: string }>; isError?: boolean }> {
+  const { orders, confirmation_token } = args;
+
+  if (confirmation_token !== "CONFIRM") {
+    return {
+      content: [
+        {
+          type: "text",
+          text: JSON.stringify({
+            error:
+              "Orders not placed. confirmation_token must equal 'CONFIRM' to execute. " +
+              "Review all orders and set confirmation_token='CONFIRM' to proceed.",
+            code: "CONFIRMATION_REQUIRED",
+            preview: { order_count: orders.length },
+          }),
+        },
+      ],
+      isError: true,
+    };
+  }
+
+  // Pre-validate ALL orders before any API call
+  for (let i = 0; i < orders.length; i++) {
+    const order = orders[i];
+    const marketError = validateMarketId(order.market_id);
+    if (marketError) {
+      return {
+        content: [
+          {
+            type: "text",
+            text: JSON.stringify({
+              error: `Order at index ${i}: ${marketError}`,
+              code: "INVALID_MARKET_ID",
+              index: i,
+            }),
+          },
+        ],
+        isError: true,
+      };
+    }
+    if (order.price_type === "limit" && order.limit_price === undefined) {
+      return {
+        content: [
+          {
+            type: "text",
+            text: JSON.stringify({
+              error: `Order at index ${i}: limit_price is required when price_type is 'limit'.`,
+              code: "VALIDATION_ERROR",
+              index: i,
+            }),
+          },
+        ],
+        isError: true,
+      };
+    }
+  }
+
+  // Execute sequentially
+  const results: BatchResult[] = [];
+  for (let i = 0; i < orders.length; i++) {
+    const order = orders[i];
+    try {
+      const payload: Record<string, unknown> = {
+        type: order.type,
+        price_type: order.price_type,
+        amount: order.amount,
+      };
+      if (order.price_type === "limit") {
+        payload.limit = { price: order.limit_price, type: "gtc" };
+      }
+
+      const data = await client.post<OrderResponse>(
+        `/markets/${order.market_id.toLowerCase()}/orders`,
+        payload,
+      );
+      results.push({ index: i, market_id: order.market_id, success: true, order: data.order });
+    } catch (err) {
+      const errInfo =
+        err instanceof BudaApiError
+          ? { error: err.message, code: err.status as number | string }
+          : { error: String(err), code: "UNKNOWN" as const };
+      results.push({
+        index: i,
+        market_id: order.market_id,
+        success: false,
+        error: errInfo.error,
+        code: errInfo.code,
+      });
+    }
+  }
+
+  const succeeded = results.filter((r) => r.success).length;
+  const failed = results.filter((r) => !r.success).length;
+
+  const response: Record<string, unknown> = {
+    results,
+    total: orders.length,
+    succeeded,
+    failed,
+  };
+
+  if (failed > 0 && succeeded > 0) {
+    response.warning = "Some orders failed. Already-placed orders were NOT rolled back.";
+  }
+
+  return {
+    content: [{ type: "text", text: JSON.stringify(response, null, 2) }],
+    isError: failed > 0 && succeeded === 0 ? true : undefined,
+  };
+}
+
+export function register(server: McpServer, client: BudaClient): void {
+  server.tool(
+    toolSchema.name,
+    toolSchema.description,
+    {
+      orders: z
+        .array(orderShape)
+        .min(1)
+        .max(20)
+        .describe("Array of 1–20 orders to place."),
+      confirmation_token: z
+        .string()
+        .describe(
+          "Safety confirmation. Must equal exactly 'CONFIRM' (case-sensitive) to execute.",
+        ),
+    },
+    (args) => handlePlaceBatchOrders(args, client),
+  );
+}