zcash_create_invoice

Instructions

Implementation Reference

• src/tools/invoice.ts:16-46 (handler)

  The handler function for the zcash_create_invoice tool. It POSTs to ZAP1 API /invoice with amount_zat, memo, and wallet_hash, then returns the invoice data (payment address, amount, memo, zcash: URI, expiry). On error, returns an error response.

  async ({ amount_zat, memo, wallet_hash }) => {
    try {
      const res = await fetch(`${ZAP1_API}/invoice`, {
        method: "POST",
        headers: { "Content-Type": "application/json" },
        body: JSON.stringify({ amount_zat, memo, wallet_hash }),
        signal: AbortSignal.timeout(API_TIMEOUT_MS),
      });
  
      if (!res.ok) {
        const text = await res.text();
        throw new Error(`${res.status}: ${text}`);
      }
  
      const data = await res.json();
      return {
        content: [
          {
            type: "text" as const,
            text: JSON.stringify(data, null, 2),
          },
        ],
      };
    } catch (err) {
      const msg = err instanceof Error ? err.message : String(err);
      return {
        content: [{ type: "text" as const, text: `Error: ${msg}` }],
        isError: true,
      };
    }
  }

• src/tools/invoice.ts:11-15 (schema)

  Zod schema defining the input parameters: amount_zat (positive integer in zatoshis), memo (string max 512 bytes), and wallet_hash (string max 128 chars).

  {
    amount_zat: z.number().int().positive().describe("Payment amount in zatoshis (1 ZEC = 100_000_000 zatoshis)"),
    memo: z.string().max(512).describe("Memo text attached to the invoice (max 512 bytes)"),
    wallet_hash: z.string().max(128).describe("Wallet identifier or hash for routing the payment"),
  },

• src/tools/invoice.ts:8-47 (registration)

  Registration of the tool via server.tool() with the name 'zcash_create_invoice', description, input schema, and handler function.

  server.tool(
    "zcash_create_invoice",
    "Create a ZAP1 payment invoice. Posts to the ZAP1 API and returns a payment address, amount, memo, zcash: URI, and expiry timestamp.",
    {
      amount_zat: z.number().int().positive().describe("Payment amount in zatoshis (1 ZEC = 100_000_000 zatoshis)"),
      memo: z.string().max(512).describe("Memo text attached to the invoice (max 512 bytes)"),
      wallet_hash: z.string().max(128).describe("Wallet identifier or hash for routing the payment"),
    },
    async ({ amount_zat, memo, wallet_hash }) => {
      try {
        const res = await fetch(`${ZAP1_API}/invoice`, {
          method: "POST",
          headers: { "Content-Type": "application/json" },
          body: JSON.stringify({ amount_zat, memo, wallet_hash }),
          signal: AbortSignal.timeout(API_TIMEOUT_MS),
        });
  
        if (!res.ok) {
          const text = await res.text();
          throw new Error(`${res.status}: ${text}`);
        }
  
        const data = await res.json();
        return {
          content: [
            {
              type: "text" as const,
              text: JSON.stringify(data, null, 2),
            },
          ],
        };
      } catch (err) {
        const msg = err instanceof Error ? err.message : String(err);
        return {
          content: [{ type: "text" as const, text: `Error: ${msg}` }],
          isError: true,
        };
      }
    }
  );

• src/index.ts:42-42 (registration)

  Call to registerInvoiceTool from the main entry point, wiring the invoice tool into the MCP server.

  registerInvoiceTool(server);

• src/tools/invoice.ts:4-5 (helper)

  Helper constants: ZAP1_API base URL (configurable via env var) and API_TIMEOUT_MS set to 15 seconds.

  const ZAP1_API = process.env.ZAP1_API_URL ?? "https://pay.frontiercompute.io";
  const API_TIMEOUT_MS = 15_000;