Withdraw to Lightning

Pay any Lightning invoice directly from your Spark wallet.

Lightning Withdrawal Flow

The complete process for withdrawing Bitcoin from Spark to the Lightning Network:

Get Lightning Invoice

Obtain a fresh Lightning invoice from the recipient or Lightning service, and check its expiry before paying.

// A fresh BOLT11 invoice supplied by the recipient
const invoice = encodedInvoice;
console.log("Lightning invoice:", invoice);

Estimate Fees

Get a fee estimate for the Lightning payment to understand costs.

const feeEstimate = await wallet.getLightningSendFeeEstimate({
  encodedInvoice: invoice
});
console.log("Fee estimate:", feeEstimate);

Pay Invoice

Send the Lightning payment with appropriate fee limits.

const payment = await wallet.payLightningInvoice({
  invoice: invoice,
  maxFeeSats: 5, // Maximum fee to pay
  preferSpark: false // Keep this example on Lightning for payment-status polling
});
console.log("Payment initiated:", payment);

Monitor Payment

Track the payment status until completion.

const paymentStatus = await wallet.getLightningSendRequest(payment.id);
console.log("Payment status:", paymentStatus?.status ?? "Request unavailable");

Check expiry before paying

Decode the BOLT11 invoice and reject it if its timestamp plus expiry is at or before the current time. Use the BOLT11 default expiry of 3,600 seconds when the x tag is absent. Check again immediately before calling payLightningInvoice() if the invoice has been sitting on a confirmation screen; request a fresh invoice when it expires.

SDK 0.12.1 does not check BOLT11 expiry locally before starting the Lightning swap. The swap can lock funds before the payment request is rejected because the invoice has expired. A thrown error does not necessarily mean the funds are available to retry. The swap’s 16-day expiry is not a guaranteed refund time.

For retryable integrations, generate and persist a transferId before the first attempt; see payLightningInvoice(). If a send fails after starting, retain the payment hash and any request or transfer IDs. Check the Lightning send request and the wallet’s available balance before retrying. Funds locked in an outgoing transfer can remain in owned while being excluded from available. Do not create a second payment just because the first call threw, or rely on a low-level CancelTransferRequest: the SDK has no public client cancellation method for this flow.

Pay Lightning Invoice

Send Bitcoin from your Spark wallet to any Lightning Network invoice. Pays a Lightning invoice using your Spark wallet balance.

const payment = await wallet.payLightningInvoice({
  invoice: encodedInvoice,
  maxFeeSats: 5,
  preferSpark: true,
});

console.log("Payment Response:", payment);

Show Parameters

string

required

The BOLT11-encoded Lightning invoice to pay

number

required

Maximum fee in satoshis to pay for the invoice

boolean

default:"false"

When true, Spark wallets will initiate a Spark transfer instead of a Lightning transfer if a valid Spark address is found in the invoice

number

Amount in satoshis to send (only used for zero-amount invoices)

Show Returns

LightningSendRequest | WalletTransfer

required

A LightningSendRequest for a Lightning payment, or a WalletTransfer if preferSpark routes the payment over Spark. Poll the Lightning send request only for the Lightning result.

Get Fee Estimate

Estimate the fees for a Lightning payment before sending. Gets an estimated fee for sending a Lightning payment.

const feeEstimate = await wallet.getLightningSendFeeEstimate({
  encodedInvoice: encodedInvoice
});

console.log("Estimated fee:", feeEstimate);

Show Parameters

string

required

The BOLT11-encoded Lightning invoice

Show Returns

LightningSendFeeEstimate

required

The estimated fee for the Lightning payment

Monitor Payment Status

Track the status of your Lightning payment. Gets a Lightning send request by ID to check payment status.

const paymentStatus = await wallet.getLightningSendRequest(paymentId);
if (!paymentStatus) {
  throw new Error("Lightning send request not found or not accessible");
}
console.log("Payment status:", paymentStatus.status);
console.log("Payment fee:", paymentStatus.fee);

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

Show Parameters

string

required

The ID of the Lightning send request

Show Returns

LightningSendRequest

required

The Lightning send request details including status and amount

Zero-Amount Invoices

Spark supports paying zero-amount Lightning invoices, which allow you to specify the amount when making the payment.

Zero-amount invoices are not widely supported across the Lightning Network. Some exchanges, such as Binance, currently do not support them.

Paying Zero-Amount Invoices

When paying a zero-amount invoice, you need to specify the amount using the amountSatsToSend parameter:

// Pay a zero-amount invoice with a specific amount
const payment = await wallet.payLightningInvoice({
  invoice: "lnbc...", // Zero-amount Lightning invoice
  maxFeeSats: 5,
  amountSatsToSend: 1000, // Specify the amount to send (in satoshis)
});

console.log("Zero-amount Payment Response:", payment);

Use amountSatsToSend only for zero-amount invoices. The SDK rejects it when the invoice already specifies an amount.

Spark Transfer Preference

When paying Lightning invoices, you can enable Spark transfer preference to automatically use Spark transfers when possible.

// Pay with Spark preference enabled
const payment = await wallet.payLightningInvoice({
  invoice: "lnbc...", // Lightning invoice (potentially with embedded Spark address)
  maxFeeSats: 5,
  preferSpark: true, // Defaults to false
});

console.log("Payment Response:", payment);

When preferSpark is set to true, Spark wallets will:

Initiate a Spark transfer instead of a Lightning transfer if a valid Spark address is found in the invoice
Fall back to regular Lightning payment if no Spark address is found

Real-time Payment Monitoring

Monitor Lightning payment status by polling.

The transfer:claimed event does not fire for outgoing Lightning payments. Use getLightningSendRequest() to poll payment status.

// Query the current state; schedule further checks in your application.
const checkPaymentStatus = async (paymentId: string) => {
  const request = await wallet.getLightningSendRequest(paymentId);
  if (!request) {
    console.log("Request unavailable: check the ID and querying wallet");
    return;
  }
  console.log("Lightning send status:", request.status);
  if (request.status === "TRANSFER_COMPLETED") {
    console.log("Lightning send completed");
  }
  // An unsuccessful request does not establish that locked funds are available.
};

// For INCOMING transfers/deposits, use events:
wallet.on("transfer:claimed", (transferId, updatedBalance) => {
  console.log(`Incoming transfer ${transferId} claimed. New balance: ${updatedBalance} sats`);
});

Fee Recommendations

We recommend setting the maximum routing fee to whichever is greater:

5 sats (minimum fee)
17 bps × transaction amount (0.17% of the transaction)

// Calculate recommended fee
const amountSats = 10000; // Your payment amount
const recommendedFee = Math.max(5, Math.ceil(amountSats * 0.0017)); // 17 bps = 0.17%

const payment = await wallet.payLightningInvoice({
  invoice: "lnbc...",
  maxFeeSats: recommendedFee
});

Introduction

Installation

Wallet

Transfers

Deposits

Withdrawals

Fees

Spark Signer Interface

Tools

Withdraw to Lightning

Lightning Withdrawal Flow

Check expiry before paying

Pay Lightning Invoice

Get Fee Estimate

Monitor Payment Status

Zero-Amount Invoices

Paying Zero-Amount Invoices

Spark Transfer Preference

Real-time Payment Monitoring

Fee Recommendations

​Lightning Withdrawal Flow

​Check expiry before paying

​Pay Lightning Invoice

​Get Fee Estimate

​Monitor Payment Status

​Zero-Amount Invoices

​Paying Zero-Amount Invoices

​Spark Transfer Preference

​Real-time Payment Monitoring

​Fee Recommendations

Lightning Withdrawal Flow

Check expiry before paying

Pay Lightning Invoice

Get Fee Estimate

Monitor Payment Status

Zero-Amount Invoices

Paying Zero-Amount Invoices

Spark Transfer Preference

Real-time Payment Monitoring

Fee Recommendations