lookup_invoice
Retrieve details of Bitcoin Lightning invoices using BOLT-11 strings or payment hashes to verify payment status and transaction information.
Instructions
Look up lightning invoice details from a BOLT-11 invoice or payment hash
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| payment_hash | No | ||
| invoice | No |
Implementation Reference
- src/tools/nwc/lookup_invoice.ts:28-53 (handler)The core handler function that executes the lookup_invoice tool: calls NWC client.lookupInvoice, converts amounts from millisats to sats with appropriate rounding, and returns both text and structured content.async (params) => { const { amount, fees_paid, ...result } = await client.lookupInvoice({ invoice: params.invoice || undefined, payment_hash: params.payment_hash || undefined, }); // Convert millisats to sats in the response const convertedResult = { ...result, amount_in_sats: Math.floor(amount / 1000), // Round down when converting millisats to sats fees_paid_in_sats: typeof fees_paid === "number" ? Math.ceil(fees_paid / 1000) // Round up fees when converting millisats to sats : undefined, }; return { content: [ { type: "text", text: JSON.stringify(convertedResult, null, 2), }, ], structuredContent: convertedResult, }; }
- Zod-based output schema for transaction details, referenced as outputSchema in the lookup_invoice tool registration.export const transactionSchema = { type: z.enum(["incoming", "outgoing"]).describe("Transaction type"), state: z .enum(["settled", "pending", "failed"]) .nullish() .describe("Transaction state"), invoice: z.string().describe("BOLT-11 invoice"), description: z.string().nullish().describe("Invoice description"), description_hash: z.string().nullish().describe("Description hash"), preimage: z.string().nullish().describe("Preimage of settled payment"), payment_hash: z.string().describe("Payment hash"), amount_in_sats: z.number().describe("Amount in sats"), fees_paid_in_sats: z.number().nullish().describe("Fees paid in sats"), settled_at: z.number().nullish().describe("Timestamp, of settled payment"), created_at: z.number().describe("Creation unix timestamp"), expires_at: z.number().nullish().describe("Expiry unix timestamp"), // TODO: remove nullish once Primal supports it settle_deadline: z .number() .nullish() .describe("HOLD invoice settle deadline"), metadata: z .unknown() .nullish() .describe("Additional metadata about the transaction"), };
- src/tools/nwc/lookup_invoice.ts:10-54 (registration)The server.registerTool call that defines and registers the lookup_invoice tool, including input schema (payment_hash or invoice), output schema, title, description, and handler.server.registerTool( "lookup_invoice", { title: "Lookup Invoice", description: "Look up lightning invoice details from a BOLT-11 invoice or payment hash", inputSchema: { payment_hash: z .string() .describe("The payment hash of the invoice to look up") .nullish(), invoice: z .string() .describe("The BOLT 11 invoice to look up") .nullish(), }, outputSchema: transactionSchema, }, async (params) => { const { amount, fees_paid, ...result } = await client.lookupInvoice({ invoice: params.invoice || undefined, payment_hash: params.payment_hash || undefined, }); // Convert millisats to sats in the response const convertedResult = { ...result, amount_in_sats: Math.floor(amount / 1000), // Round down when converting millisats to sats fees_paid_in_sats: typeof fees_paid === "number" ? Math.ceil(fees_paid / 1000) // Round up fees when converting millisats to sats : undefined, }; return { content: [ { type: "text", text: JSON.stringify(convertedResult, null, 2), }, ], structuredContent: convertedResult, }; } );
- src/mcp_server.ts:28-28 (registration)Invocation of the registerLookupInvoiceTool function during MCP server initialization to enable the lookup_invoice tool.registerLookupInvoiceTool(server, client);