pay_invoice
Process BOLT11 Lightning invoices from agent balance and return payment proof. Requires agent authorization and supports fee limits.
Instructions
Pay a BOLT11 Lightning invoice from the agent balance. Returns preimage as proof of payment. REQUIRES AGENT KEY.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| bolt11 | Yes | BOLT11 invoice string to pay (starts with lnbc...) | |
| max_fee_sats | No | Maximum routing fee in satoshis |
Implementation Reference
- src/index.ts:908-929 (handler)Handler for 'pay_invoice' tool in MCP server, which parses input and calls the client method.
case 'pay_invoice': { const parsed = PayInvoiceSchema.parse(args); const result = await session.requireClient().payInvoice(parsed.bolt11, parsed.max_fee_sats); return { content: [ { type: 'text', text: JSON.stringify({ success: true, message: 'Invoice paid successfully', preimage: result.preimage, amount_sats: result.amountSats, routing_fee_sats: result.routingFeeSats, platform_fee_sats: result.platformFeeSats, total_cost: result.totalCost, payment_hash: result.paymentHash, new_balance: result.newBalance, }, null, 2), }, ], }; } - src/lightning-faucet.ts:260-297 (handler)The implementation method 'payInvoice' in LightningFaucetClient that performs the actual API request.
async payInvoice( bolt11: string, maxFeeSats?: number ): Promise<{ preimage: string; amountSats: number; routingFeeSats: number; platformFeeSats: number; totalCost: number; paymentHash: string; newBalance: number; rawResponse: PayInvoiceResponse; }> { const data: Record<string, unknown> = { invoice: bolt11, }; if (maxFeeSats !== undefined) { data.max_fee_sats = maxFeeSats; } const result = await this.request<PayInvoiceResponse>('pay_invoice', data); const amountSats = result.amount_sats || result.amount_paid || 0; const routingFeeSats = (result as any).routing_fee_sats || 0; const platformFeeSats = (result as any).platform_fee_sats || 0; return { preimage: result.preimage || result.payment_preimage || '', amountSats, routingFeeSats, platformFeeSats, totalCost: (result as any).total_cost || (amountSats + routingFeeSats + platformFeeSats), paymentHash: result.payment_hash || '', newBalance: result.new_balance || 0, rawResponse: result, }; } - src/index.ts:103-108 (schema)Validation schema for the 'pay_invoice' tool inputs.
const PayInvoiceSchema = z.object({ bolt11: z.string().regex(/^ln(bc|tb|bcrt)1[a-z0-9]+$/i, 'Invalid BOLT11 invoice format') .describe('BOLT11 invoice string to pay (starts with lnbc...)'), max_fee_sats: z.number().min(0).optional() .describe('Maximum routing fee in satoshis (default: 10% of invoice amount)'), }); - src/index.ts:340-354 (registration)Registration definition of the 'pay_invoice' tool.
name: 'pay_invoice', description: 'Pay a BOLT11 Lightning invoice from the agent balance. Returns preimage as proof of payment. REQUIRES AGENT KEY.', inputSchema: { type: 'object', properties: { bolt11: { type: 'string', description: 'BOLT11 invoice string to pay (starts with lnbc...)' }, max_fee_sats: { type: 'integer', minimum: 0, description: 'Maximum routing fee in satoshis', }, }, required: ['bolt11'], }, },