Lightning Wallet MCP

Instructions

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'],
    },
  },