Skip to main content
Learn how to receive Bitcoin deposits through the Lightning Network. This guide covers Lightning invoice creation, receiving payments, and integrating Lightning deposits into your Spark wallet.
Deposit from Lightning

​
Lightning Deposit Flow

The complete process for receiving Lightning payments into your Spark wallet:
1

Create Invoice

Generate a Lightning invoice with the desired amount and description.
const invoice = await wallet.createLightningInvoice({
amountSats: 50000,
memo: "Deposit to Spark wallet"
});
2

Share Invoice

Provide the invoice to the sender (via QR code, link, or text).
// Display invoice for user to share
console.log("Share this invoice:", invoice.invoice);
console.log("Or share this ID:", invoice.id);
3

Monitor Payment

Track the payment status until completion.
// Poll for payment status
const checkPayment = async (invoiceId) => {
  const request = await wallet.getLightningReceiveRequest(invoiceId);
  
  if (request.status === "completed") {
    console.log("Payment received:", request.amountReceived, "sats");
    return true;
  } else if (request.status === "expired") {
    console.log("Invoice expired");
    return false;
  } else {
    console.log("Payment pending...");
    return false;
  }
};

​
Create Lightning Invoice

Generate Lightning invoices to receive Bitcoin payments that will be deposited into your Spark wallet. createLightningInvoice(params) Creates a Lightning invoice for receiving Bitcoin payments. 
const invoice = await wallet.createLightningInvoice({
  amountSats: 10000,        // Amount in satoshis
  memo: "Payment for services", // Optional description
  includeSparkAddress: true // Optional: embed Spark address
});

console.log("Lightning invoice:", invoice.invoice);
console.log("Invoice ID:", invoice.id);

​
Monitor Lightning Payments

Track incoming Lightning payments and their status using receive request monitoring. getLightningReceiveRequest(id) Gets the status of a Lightning receive request by ID. 
// Monitor a specific invoice
const receiveRequest = await wallet.getLightningReceiveRequest(invoiceId);
console.log("Payment status:", receiveRequest.status);
console.log("Amount received:", receiveRequest.amountReceived);

// Check if payment is complete
if (receiveRequest.status === "completed") {
  console.log("Payment received successfully!");
}

​
Real-time Payment Monitoring

Use event listeners to monitor Lightning payments in real-time. 
// Listen for transfer events (Lightning payments trigger transfer events)
wallet.on("transfer:claimed", (transferId, updatedBalance) => {
  console.log(`Transfer ${transferId} claimed. New balance: ${updatedBalance} sats`);
});

​
Error Handling

Implement proper error handling for Lightning invoice operations. 
async function createInvoiceSafely(params) {
  try {
    // Validate amount
    if (params.amountSats <= 0) {
      throw new Error("Amount must be greater than 0");
    }

    // Validate expiry time
    if (params.expiryTime && params.expiryTime < 60) {
      throw new Error("Expiry time must be at least 60 seconds");
    }

    // Create invoice
    const invoice = await wallet.createLightningInvoice(params);
    console.log("Invoice created successfully:", invoice.id);
    return invoice;
    
  } catch (error) {
    console.error("Failed to create invoice:", error.message);
    
    // Handle specific error types
    if (error.message.includes("Amount")) {
      console.log("Please check the amount value");
    } else if (error.message.includes("Expiry")) {
      console.log("Please check the expiry time");
    } else if (error.message.includes("Network")) {
      console.log("Network error. Please try again.");
    }
    
    throw error;
  }
}

​
Best Practices

  • Set appropriate expiry times - Balance between urgency and flexibility
  • Include clear descriptions - Help senders understand the payment purpose
  • Monitor payment status - Use polling or events to track payments
  • Handle expired invoices - Implement retry logic for expired invoices
  • Validate amounts - Ensure amounts are reasonable and valid
  • Use real-time monitoring - Implement event listeners for better UX

​
Example: Complete Lightning Deposit Flow

import { SparkWallet } from "@buildonspark/spark-sdk";

async function completeLightningDeposit() {
  const { wallet } = await SparkWallet.initialize({
    options: { network: "REGTEST" }
  });

  try {
    // 1. Set up event listeners
    wallet.on("transfer:claimed", (transferId, updatedBalance) => {
      console.log(`Transfer ${transferId} claimed. New balance: ${updatedBalance} sats`);
    });

    // 2. Create Lightning invoice
    const invoice = await wallet.createLightningInvoice({
      amountSats: 10000,
      memo: "Lightning deposit to Spark wallet"
    });

    console.log("Invoice created:", invoice.invoice);
    console.log("Invoice ID:", invoice.id);

    // 3. Monitor payment status
    const monitorPayment = async () => {
      const request = await wallet.getLightningReceiveRequest(invoice.id);
      
      switch (request.status) {
        case "completed":
          console.log("Payment completed!");
          return true;
        case "expired":
          console.log("Invoice expired");
          return false;
        default:
          console.log("Payment pending...");
          setTimeout(monitorPayment, 5000); // Check again in 5 seconds
          return false;
      }
    };

    // Start monitoring
    await monitorPayment();

  } catch (error) {
    console.error("Lightning deposit failed:", error);
  }
}