decode_invoice
Decode BOLT11 Lightning invoices to extract payment details and verify transaction information for Bitcoin network interactions.
Instructions
Decode a Lightning invoice
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| invoice | Yes | BOLT11 Lightning invoice |
Implementation Reference
- src/server/tools.ts:199-231 (handler)The primary MCP tool handler for 'decode_invoice'. Validates the input args for a required 'invoice' string, delegates decoding to BitcoinService.decodeInvoice, formats the result into MCP TextContent response, and handles errors appropriately.export async function handleDecodeInvoice( bitcoinService: BitcoinService, args: unknown ) { if ( !args || typeof args !== "object" || !("invoice" in args) || typeof args.invoice !== "string" ) { throw new McpError( ErrorCode.InvalidParams, "Invalid parameters: invoice is required" ); } try { const invoice = bitcoinService.decodeInvoice(args.invoice); return { content: [ { type: "text", text: `Decoded Lightning invoice:\nNetwork: ${invoice.network}\nAmount: ${invoice.amount} satoshis\nDescription: ${invoice.description}\nExpiry: ${invoice.expiryDate}\nStatus: ${invoice.status}`, }, ] as TextContent[], }; } catch (error: any) { throw new McpError( ErrorCode.InternalError, error.message || "Failed to decode invoice" ); } }
- src/server/base.ts:163-175 (registration)Registration of the 'decode_invoice' tool in the ListToolsRequestHandler. Defines the tool name, description, and input schema requiring a 'invoice' string parameter.name: "decode_invoice", description: "Decode a Lightning invoice", inputSchema: { type: "object", properties: { invoice: { type: "string", description: "BOLT11 Lightning invoice", }, }, required: ["invoice"], }, } as Tool,
- src/server/base.ts:215-217 (registration)Dispatching logic in the CallToolRequestHandler switch statement that routes 'decode_invoice' calls to the handleDecodeInvoice function with BitcoinService instance.case "decode_invoice": { return handleDecodeInvoice(this.bitcoinService, args); }
- src/services/bitcoin.ts:278-295 (helper)BitcoinService.decodeInvoice method: Checks if LNBitsClient is configured, then delegates the actual BOLT11 decoding to LNBitsClient.toHumanFriendlyInvoice, with error handling and logging.decodeInvoice(bolt11: string): HumanFriendlyInvoice { if (!this.lnbitsClient) { throw new LightningError( "LNBits not configured. Please add lnbitsUrl, lnbitsAdminKey, and lnbitsReadKey to configuration.", LightningErrorCode.NOT_CONNECTED ); } try { return this.lnbitsClient.toHumanFriendlyInvoice(bolt11); } catch (error) { logger.error({ error, bolt11 }, "Failed to decode invoice"); throw new LightningError( "Failed to decode Lightning invoice", LightningErrorCode.PAYMENT_ERROR ); } }
- src/clients/lnbits_clients.ts:58-78 (helper)LNBitsClient helper methods for decoding BOLT11 invoices. 'toHumanFriendlyInvoice' uses the 'bolt11-decoder' library to parse the invoice string, then 'humanFriendlyInvoice' extracts and formats key fields like network, amount, description, expiry, and status into HumanFriendlyInvoice.humanFriendlyInvoice(decoded: DecodedInvoice): HumanFriendlyInvoice { const network = decoded.prefix.startsWith("lnbc") ? "mainnet" : "testnet"; const descriptionTag = decoded.tags.find( (t) => t.tagName === "description" ); const description = descriptionTag ? String(descriptionTag.data) : "No description provided"; return { network: network, amount: decoded.satoshis, description: description, expiryDate: new Date(decoded.timestamp * 1000).toLocaleString(), status: "VALID", }; } toHumanFriendlyInvoice(bolt11Invoice: string): HumanFriendlyInvoice { const decoded = bolt11.decode(bolt11Invoice) as DecodedInvoice; return this.humanFriendlyInvoice(decoded); }