@guiie/buda-mcp 1.4.2 → 1.5.1

package/src/tools/place_order.ts

@@ -8,6 +8,7 @@ export const toolSchema = {
   name: "place_order",
   description:
     "Place a limit or market order on Buda.com. " +
+    "Supports optional time-in-force flags (ioc, fok, post_only, gtd_timestamp) and stop orders. " +
     "IMPORTANT: To prevent accidental execution from ambiguous prompts, you must pass " +
     "confirmation_token='CONFIRM' to execute the order. " +
     "Requires BUDA_API_KEY and BUDA_API_SECRET environment variables. " +
@@ -37,6 +38,30 @@ export const toolSchema = {
           "Limit price in quote currency. Required when price_type is 'limit'. " +
           "For Bid orders: highest price you will pay. For Ask orders: lowest price you will accept.",
       },
+      ioc: {
+        type: "boolean",
+        description: "Immediate-or-cancel: fill as much as possible, cancel the rest. Mutually exclusive with fok, post_only, gtd_timestamp.",
+      },
+      fok: {
+        type: "boolean",
+        description: "Fill-or-kill: fill the entire order or cancel it entirely. Mutually exclusive with ioc, post_only, gtd_timestamp.",
+      },
+      post_only: {
+        type: "boolean",
+        description: "Post-only: rejected if it would execute immediately as a taker. Mutually exclusive with ioc, fok, gtd_timestamp.",
+      },
+      gtd_timestamp: {
+        type: "string",
+        description: "Good-till-date: ISO 8601 datetime after which the order is canceled. Mutually exclusive with ioc, fok, post_only.",
+      },
+      stop_price: {
+        type: "number",
+        description: "Stop trigger price. Must be paired with stop_type.",
+      },
+      stop_type: {
+        type: "string",
+        description: "Stop trigger direction: '>=' triggers when price rises to stop_price, '<=' when it falls. Must be paired with stop_price.",
+      },
       confirmation_token: {
         type: "string",
         description:
@@ -54,6 +79,12 @@ type PlaceOrderArgs = {
   price_type: "limit" | "market";
   amount: number;
   limit_price?: number;
+  ioc?: boolean;
+  fok?: boolean;
+  post_only?: boolean;
+  gtd_timestamp?: string;
+  stop_price?: number;
+  stop_type?: ">=" | "<=";
   confirmation_token: string;
 };
 
@@ -61,7 +92,20 @@ export async function handlePlaceOrder(
   args: PlaceOrderArgs,
   client: BudaClient,
 ): Promise<{ content: Array<{ type: "text"; text: string }>; isError?: boolean }> {
-  const { market_id, type, price_type, amount, limit_price, confirmation_token } = args;
+  const {
+    market_id,
+    type,
+    price_type,
+    amount,
+    limit_price,
+    ioc,
+    fok,
+    post_only,
+    gtd_timestamp,
+    stop_price,
+    stop_type,
+    confirmation_token,
+  } = args;
 
   if (confirmation_token !== "CONFIRM") {
     return {
@@ -89,6 +133,41 @@ export async function handlePlaceOrder(
     };
   }
 
+  // Validate TIF mutual exclusivity
+  const tifFlags = [ioc, fok, post_only, gtd_timestamp !== undefined].filter(Boolean);
+  if (tifFlags.length > 1) {
+    return {
+      content: [
+        {
+          type: "text",
+          text: JSON.stringify({
+            error: "ioc, fok, post_only, and gtd_timestamp are mutually exclusive. Specify at most one.",
+            code: "VALIDATION_ERROR",
+          }),
+        },
+      ],
+      isError: true,
+    };
+  }
+
+  // Validate stop_price / stop_type must both be present or both absent
+  const hasStopPrice = stop_price !== undefined;
+  const hasStopType = stop_type !== undefined;
+  if (hasStopPrice !== hasStopType) {
+    return {
+      content: [
+        {
+          type: "text",
+          text: JSON.stringify({
+            error: "stop_price and stop_type must both be provided together.",
+            code: "VALIDATION_ERROR",
+          }),
+        },
+      ],
+      isError: true,
+    };
+  }
+
   try {
     const payload: Record<string, unknown> = {
       type,
@@ -111,7 +190,52 @@ export async function handlePlaceOrder(
           isError: true,
         };
       }
-      payload.limit = { price: limit_price, type: "gtc" };
+
+      if (gtd_timestamp !== undefined) {
+        const ts = new Date(gtd_timestamp).getTime();
+        if (isNaN(ts)) {
+          return {
+            content: [
+              {
+                type: "text",
+                text: JSON.stringify({
+                  error: "gtd_timestamp must be a valid ISO 8601 datetime string.",
+                  code: "VALIDATION_ERROR",
+                }),
+              },
+            ],
+            isError: true,
+          };
+        }
+        if (ts <= Date.now()) {
+          return {
+            content: [
+              {
+                type: "text",
+                text: JSON.stringify({
+                  error: "gtd_timestamp must be a future datetime.",
+                  code: "VALIDATION_ERROR",
+                }),
+              },
+            ],
+            isError: true,
+          };
+        }
+      }
+
+      let limitType = "gtc";
+      if (ioc) limitType = "ioc";
+      else if (fok) limitType = "fok";
+      else if (post_only) limitType = "post_only";
+      else if (gtd_timestamp !== undefined) limitType = "gtd";
+
+      const limitObj: Record<string, unknown> = { price: limit_price, type: limitType };
+      if (gtd_timestamp !== undefined) limitObj.expiration = gtd_timestamp;
+      payload.limit = limitObj;
+    }
+
+    if (hasStopPrice && hasStopType) {
+      payload.stop = { price: stop_price, type: stop_type };
     }
 
     const data = await client.post<OrderResponse>(
@@ -160,6 +284,31 @@ export function register(server: McpServer, client: BudaClient): void {
           "Limit price in quote currency. Required when price_type is 'limit'. " +
             "For Bid orders: highest price you will pay. For Ask orders: lowest price you will accept.",
         ),
+      ioc: z
+        .boolean()
+        .optional()
+        .describe("Immediate-or-cancel: fill as much as possible, cancel the rest. Mutually exclusive with fok, post_only, gtd_timestamp."),
+      fok: z
+        .boolean()
+        .optional()
+        .describe("Fill-or-kill: fill the entire order or cancel it entirely. Mutually exclusive with ioc, post_only, gtd_timestamp."),
+      post_only: z
+        .boolean()
+        .optional()
+        .describe("Post-only: rejected if it would execute immediately as a taker. Mutually exclusive with ioc, fok, gtd_timestamp."),
+      gtd_timestamp: z
+        .string()
+        .optional()
+        .describe("Good-till-date: ISO 8601 datetime after which the order is canceled. Mutually exclusive with ioc, fok, post_only."),
+      stop_price: z
+        .number()
+        .positive()
+        .optional()
+        .describe("Stop trigger price. Must be paired with stop_type."),
+      stop_type: z
+        .enum([">=", "<="])
+        .optional()
+        .describe("Stop trigger direction: '>=' triggers when price rises to stop_price, '<=' when it falls. Must be paired with stop_price."),
       confirmation_token: z
         .string()
         .describe(

package/src/tools/quotation.ts

@@ -0,0 +1,124 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+import { BudaClient, BudaApiError } from "../client.js";
+import { validateMarketId } from "../validation.js";
+import { flattenAmount } from "../utils.js";
+import type { QuotationResponse } from "../types.js";
+
+export const toolSchema = {
+  name: "get_real_quotation",
+  description:
+    "Gets a server-side price quotation for a buy or sell on Buda.com. " +
+    "Calls the Buda quotation API to compute an accurate fill estimate including fees, " +
+    "based on live order book state. Prefer this over simulate_order for accurate fee-tier-aware quotes. " +
+    "This is a POST (not idempotent) but does not place an order. Public endpoint — no API key required. " +
+    "Parameters: market_id, type ('Bid'|'Ask'), amount, optional limit price. " +
+    "Example: 'Get an accurate quote to sell 0.05 BTC on BTC-CLP.'",
+  inputSchema: {
+    type: "object" as const,
+    properties: {
+      market_id: {
+        type: "string",
+        description: "Market ID (e.g. 'BTC-CLP', 'ETH-BTC').",
+      },
+      type: {
+        type: "string",
+        description: "'Bid' to buy base currency, 'Ask' to sell base currency.",
+      },
+      amount: {
+        type: "number",
+        description: "Order size (positive number).",
+      },
+      limit: {
+        type: "number",
+        description: "Optional limit price in quote currency.",
+      },
+    },
+    required: ["market_id", "type", "amount"],
+  },
+};
+
+type GetRealQuotationArgs = {
+  market_id: string;
+  type: "Bid" | "Ask";
+  amount: number;
+  limit?: number;
+};
+
+export async function handleGetRealQuotation(
+  args: GetRealQuotationArgs,
+  client: BudaClient,
+): Promise<{ content: Array<{ type: "text"; text: string }>; isError?: boolean }> {
+  const { market_id, type, amount, limit } = args;
+
+  const validationError = validateMarketId(market_id);
+  if (validationError) {
+    return {
+      content: [{ type: "text", text: JSON.stringify({ error: validationError, code: "INVALID_MARKET_ID" }) }],
+      isError: true,
+    };
+  }
+
+  const id = market_id.toLowerCase();
+  const payload: Record<string, unknown> = { type, amount: String(amount) };
+  if (limit !== undefined) payload.limit = String(limit);
+
+  try {
+    const data = await client.post<QuotationResponse>(`/markets/${id}/quotations`, {
+      quotation: payload,
+    });
+
+    const q = data.quotation;
+    const flatAmount = flattenAmount(q.amount);
+    const flatLimit = q.limit ? flattenAmount(q.limit) : null;
+    const flatBase = flattenAmount(q.base_balance_change);
+    const flatQuote = flattenAmount(q.quote_balance_change);
+    const flatFee = flattenAmount(q.fee_amount);
+    const flatOrder = flattenAmount(q.order_amount);
+
+    const result = {
+      id: q.id ?? null,
+      type: q.type,
+      market_id: q.market_id,
+      amount: flatAmount.value,
+      amount_currency: flatAmount.currency,
+      limit: flatLimit ? flatLimit.value : null,
+      limit_currency: flatLimit ? flatLimit.currency : null,
+      base_balance_change: flatBase.value,
+      base_balance_change_currency: flatBase.currency,
+      quote_balance_change: flatQuote.value,
+      quote_balance_change_currency: flatQuote.currency,
+      fee_amount: flatFee.value,
+      fee_currency: flatFee.currency,
+      order_amount: flatOrder.value,
+      order_amount_currency: flatOrder.currency,
+    };
+
+    return {
+      content: [{ type: "text", text: JSON.stringify(result, 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,
+    {
+      market_id: z.string().describe("Market ID (e.g. 'BTC-CLP', 'ETH-BTC')."),
+      type: z.enum(["Bid", "Ask"]).describe("'Bid' to buy base currency, 'Ask' to sell base currency."),
+      amount: z.number().positive().describe("Order size (positive number)."),
+      limit: z.number().positive().optional().describe("Optional limit price in quote currency."),
+    },
+    (args) => handleGetRealQuotation(args, client),
+  );
+}

package/src/tools/receive_addresses.ts

@@ -0,0 +1,242 @@
+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. " +
+    "IMPORTANT: Pass confirmation_token='CONFIRM' to execute. " +
+    "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').",
+      },
+      confirmation_token: {
+        type: "string",
+        description: "Safety confirmation. Must equal exactly 'CONFIRM' (case-sensitive) to generate a new address.",
+      },
+    },
+    required: ["currency", "confirmation_token"],
+  },
+};
+
+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; confirmation_token: string },
+  client: BudaClient,
+): Promise<{ content: Array<{ type: "text"; text: string }>; isError?: boolean }> {
+  const { currency, confirmation_token } = args;
+
+  if (confirmation_token !== "CONFIRM") {
+    return {
+      content: [
+        {
+          type: "text",
+          text: JSON.stringify({
+            error:
+              "Address not generated. confirmation_token must equal 'CONFIRM' to execute. " +
+              "Each call creates a distinct address — review and set confirmation_token='CONFIRM' to proceed.",
+            code: "CONFIRMATION_REQUIRED",
+            preview: { currency },
+          }),
+        },
+      ],
+      isError: true,
+    };
+  }
+
+  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')."),
+      confirmation_token: z
+        .string()
+        .describe("Safety confirmation. Must equal exactly 'CONFIRM' (case-sensitive) to generate a new address."),
+    },
+    (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),
+  );
+}