Lightning Payments

This guide explains how to create a Lightning invoice, pay a Lightning invoice, estimate Lightning fees, and fetch a Lightning send request.

Create a Lightning Invoice

1. Choose an amount in satoshis and an optional memo.
2. Call account.createLightningInvoice().

You can create a BOLT11 invoice using account.createLightningInvoice():

const invoice = await account.createLightningInvoice({
  amountSats: 50000,
  memo: 'Payment for services'
})
console.log('Lightning invoice:', invoice.invoice)

Pay a Lightning Invoice

1. Obtain a BOLT11 encodedInvoice string.
2. Set maxFeeSats to cap routing fees.
3. Call account.payLightningInvoice().

If you enable syncAndRetry, the wallet syncs state after a payment failure and retries account.payLightningInvoice() once only for a stale-leaf error. Both attempts reuse the same transferId. The wallet generates an ID when you omit it.

You can enable the stale-leaf retry when constructing the wallet:

const wallet = new WalletManagerSpark(seedPhrase, {
  network: 'MAINNET',
  syncAndRetry: true,
})

const account = await wallet.getAccount(0)
const payment = await account.payLightningInvoice({
  invoice: 'lnbc500u1p...',
  maxFeeSats: 1000,
})

If a payment attempt fails with LightningPaymentError, keep its transferId with the original invoice and payment options. If you later choose to retry that payment, pass the same ID rather than starting another payment. The error ID is a Spark transfer ID; it is not the Lightning request id accepted by getLightningSendRequest(). See typed error handling.

Estimate Lightning Fees

You can estimate the routing fee before paying using account.quotePayLightningInvoice():

const feeEstimate = await account.quotePayLightningInvoice({
  encodedInvoice: 'lnbc500u1p...'
})
console.log('Fee estimate:', Number(feeEstimate), 'satoshis')

Fetch a Lightning Send Request

You can load a prior send request by id using account.getLightningSendRequest():

const sendRequest = await account.getLightningSendRequest(payment.id)
if (sendRequest) {
  console.log('Payment status:', sendRequest.status)
}

Next Steps

Learn how to handle Bitcoin layer 1 deposits and withdrawals.