@guiie/buda-mcp 1.4.2 → 1.5.0

package/src/tools/lightning.ts

@@ -0,0 +1,231 @@
+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,
+    };
+  }
+
+  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(1)
+        .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),
+  );
+}

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,20 @@ export async function handlePlaceOrder(
           isError: true,
         };
       }
-      payload.limit = { price: limit_price, type: "gtc" };
+
+      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 +252,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),
+  );
+}