Lightning Wallet MCP

Instructions

Implementation Reference

• src/index.ts:870-906 (handler)

  Handler for the 'pay_l402_api' tool, which processes the request using the client's l402Pay method and constructs the response.

  case 'pay_l402_api': {
    const parsed = PayL402ApiSchema.parse(args);
    const result = await session.requireClient().l402Pay(
      parsed.url,
      parsed.method,
      parsed.body,
      parsed.max_payment_sats
    );
    // Determine if the target returned a success response
    const targetSuccess = result.statusCode >= 200 && result.statusCode < 300;
    const message = targetSuccess
      ? (result.amountPaid ? `Request completed with payment of ${result.amountPaid} sats` : 'Request completed (no payment required)')
      : `Target returned HTTP ${result.statusCode}`;
    const responseData: Record<string, unknown> = {
      success: targetSuccess,
      message,
      status_code: result.statusCode,
      data: result.data,
      payment_hash: result.paymentHash,
      amount_paid: result.amountPaid,
      fee: result.fee,
    };
    if (result.paymentProtocol) {
      responseData.payment_protocol = result.paymentProtocol;
    }
    if (result.usdcAmount !== undefined) {
      responseData.usdc_amount = result.usdcAmount;
    }
    return {
      content: [
        {
          type: 'text',
          text: JSON.stringify(responseData, null, 2),
        },
      ],
    };
  }

• src/lightning-faucet.ts:205-255 (handler)

  The client-side method l402Pay that executes the API request for the pay_l402_api tool by calling the underlying API.

   * Pay an L402-protected API endpoint
   */
  async l402Pay(
    url: string,
    method: string = 'GET',
    body?: string,
    maxPaymentSats: number = 1000
  ): Promise<{
    data: unknown;
    statusCode: number;
    paymentHash?: string;
    amountPaid?: number;
    fee?: number;
    paymentProtocol?: 'l402' | 'x402';
    usdcAmount?: number;
    rawResponse: L402PayResponse;
  }> {
    const requestData: Record<string, unknown> = {
      url,
      method: method.toUpperCase(),
      max_payment_sats: maxPaymentSats,
    };
  
    if (body) {
      requestData.body = body;
    }
  
    const result = await this.request<L402PayResponse>('l402_pay', requestData);
  
    let responseData: unknown;
    if (result.body) {
      try {
        responseData = JSON.parse(result.body);
      } catch {
        responseData = result.body;
      }
    } else {
      responseData = result.data;
    }
  
    return {
      data: responseData,
      statusCode: result.status_code || 200,
      paymentHash: result.payment_hash,
      amountPaid: result.amount_paid,
      fee: result.fee,
      paymentProtocol: result.payment_protocol,
      usdcAmount: result.usdc_amount,
      rawResponse: result,
    };
  }

• src/index.ts:95-101 (schema)

  Input schema for the pay_l402_api tool.

  const PayL402ApiSchema = z.object({
    url: z.string().describe('The URL to request'),
    method: z.enum(['GET', 'POST', 'PUT', 'DELETE']).default('GET').describe('HTTP method'),
    body: z.string().optional().describe('Request body for POST/PUT requests'),
    max_payment_sats: z.number().min(1).max(100000).default(1000)
      .describe('Maximum amount in satoshis to pay for this request'),
  });

• src/index.ts:314-338 (registration)

  Registration definition for the pay_l402_api tool.

  {
    name: 'pay_l402_api',
    description: 'Make a request to a paid API. Supports L402 (Lightning) and X402 (USDC on Base) protocols. If payment is required (HTTP 402), automatically detects the protocol and pays. L402 is preferred when both are available. REQUIRES AGENT KEY.',
    inputSchema: {
      type: 'object',
      properties: {
        url: { type: 'string', description: 'The URL to request' },
        method: {
          type: 'string',
          enum: ['GET', 'POST', 'PUT', 'DELETE'],
          default: 'GET',
          description: 'HTTP method',
        },
        body: { type: 'string', description: 'Request body for POST/PUT requests' },
        max_payment_sats: {
          type: 'integer',
          minimum: 1,
          maximum: 100000,
          default: 1000,
          description: 'Maximum amount in satoshis to pay for this request',
        },
      },
      required: ['url'],
    },
  },