Deposit from Lightning

Receive Bitcoin via Lightning invoices with instant settlement into Spark.

Understanding Lightning Invoices

To send and receive Lightning payments, you can generate and pay Lightning invoices. A Lightning invoice (also called a payment request) is a specially formatted string that contains all the information needed to make a Lightning Network payment:

Amount: How many satoshis to send (can be omitted for zero-amount invoices)
Destination: The recipient’s node public key
Payment Hash: A unique identifier for the payment
Description: Optional memo describing the payment
Expiry: How long the invoice is valid for (use the returned invoice.expiresAt)

Lightning invoices start with “ln” followed by the network identifier (bc for mainnet) and typically look like this: lnbc1...

Lightning Deposit Flow

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

Create Invoice

Generate a Lightning invoice with the desired amount and description.

const invoice = await wallet.createLightningInvoice({
amountSats: 50000,
memo: "Deposit to Spark wallet"
});

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.encodedInvoice);
// Save invoice.id in your application; it is a lookup ID, not a payable invoice.

Monitor Payment

Track the payment status until completion.

// Poll for payment status
const checkPayment = async (invoiceId: string) => {
  const request = await wallet.getLightningReceiveRequest(invoiceId);
  
  if (!request) {
    console.log("Request unavailable: check the ID and querying wallet");
    return false;
  }
  console.log("Receive status:", request.status);
  // This is the Lightning receive request status; check the receiver's balance for spendability.
  return request.status === "TRANSFER_COMPLETED";
};

Create Lightning Invoice

Generate Lightning invoices to receive Bitcoin payments that will be deposited into your Spark wallet. 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.encodedInvoice);
console.log("Invoice ID:", invoice.id);

Show Parameters

number

required

The amount in satoshis to request

string

Optional memo/description for the invoice (max 120 bytes). Cannot be used with descriptionHash.

boolean

Whether to embed Spark address in the invoice fallback field. Mutually exclusive with includeSparkInvoice.

boolean

Whether to include a Spark invoice in the invoice routing hints. Mutually exclusive with includeSparkAddress.

string

Optional: 33-byte compressed identity pubkey for other Spark users

string

Optional: Hash of a longer description (h tag). Used in LNURL/UMA. Cannot be used with memo.

Show Returns

string

required

Unique identifier for the invoice (e.g., SparkLightningReceiveRequest:...)

LightningInvoice

required

Lightning invoice object containing:

encodedInvoice: The BOLT11-encoded string (e.g., lnbc1...)
bitcoinNetwork: Network identifier (MAINNET or REGTEST)
paymentHash: Unique payment identifier
amount: Object with originalValue (millisatoshis) and originalUnit
createdAt: Invoice creation timestamp
expiresAt: Invoice expiration timestamp
memo: Base64-encoded memo string

string

required

Invoice status (e.g., INVOICE_CREATED, TRANSFER_COMPLETED)

Spark Payment Integration

Spark provides two ways to enable Spark-based payments alongside Lightning invoices:

Option 1: Spark Invoice in Routing Hints

By setting includeSparkInvoice: true, a Spark invoice is embedded in the routing hints section of the BOLT11 invoice. This allows Spark-compatible wallets to automatically detect and pay over Spark instead of Lightning, providing a seamless user experience:

const invoice = await wallet.createLightningInvoice({
  amountSats: 100,
  memo: "Invoice with Spark support",
  includeSparkInvoice: true,
});
console.log("Invoice with Spark routing:", invoice);

When a payer uses this invoice:

Spark-compatible wallets can pay directly over Spark (faster, potentially lower fees)
Non-Spark wallets will pay via Lightning as normal
The payment is correlated to the original invoice

Option 2: Spark Address in Fallback Field

By passing in true for includeSparkAddress, a 36-byte string consisting of a recognizable header and a receiver’s compressed identity public key SPK:identitypubkey will get embedded in the fallback address (f) field of a BOLT11 invoice:

const invoice = await wallet.createLightningInvoice({
  amountSats: 100,
  memo: "Invoice with Spark address",
  includeSparkAddress: true,
});
console.log("Invoice with Spark address:", invoice);

Fallback Address Format

The embedded Spark address in the fallback field will look something like this:

{
  version: 31,
  address_hash: "53504b0250949ec35b022e3895fd37750102f94fe813523fa220108328a81790bf67ade5"
}

Important: These two options are mutually exclusive. You cannot use both includeSparkAddress and includeSparkInvoice in the same invoice.

Creating Invoices for Other Spark Users

To generate an invoice for another Spark user, pass in the 33-byte compressed identity pubkey as a string to receiverIdentityPubkey:

const invoice = await wallet.createLightningInvoice({
  amountSats: 100,
  memo: "Invoice for another user",
  receiverIdentityPubkey: "023e33e2920326f64ea31058d44777442d97d7d5cbfcf54e3060bc1695e5261c93",
});
console.log("Invoice for another user:", invoice);

If a wallet is generating an invoice for itself and wants to embed its own Spark identity in the invoice, it will not need to pass in a receiverIdentityPubkey to embed a Spark address. That will get taken care of on the backend. Passing it in shouldn’t change anything though.

The requesting wallet receives the SPARK_LIGHTNING_RECEIVE_FINISHED webhook for an invoice it creates on behalf of someone else. Register the webhook on that wallet; do not assume the receiver alone will receive the notification. The receive-request lookup is restricted to the requester or receiver. Preserve the requesting wallet’s identity across process restarts, or query as the receiver. In the SDK, invoice creation uses SparkWallet, which also runs background claims and maintenance. See wallet lifecycle.

Zero-Amount Invoices

Spark supports creating zero-amount Lightning invoices. Zero-amount invoices don’t have a fixed amount and allow the sender 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.

Creating Zero-Amount Invoices

To create a zero-amount invoice, pass 0 for the amountSats parameter:

// Create a zero-amount invoice
const zeroAmountInvoice = await wallet.createLightningInvoice({
  amountSats: 0, // Creates a zero-amount invoice
  memo: "Pay any amount you want",
});
console.log("Zero-amount Invoice:", zeroAmountInvoice);

Monitor Lightning Payments

Track incoming Lightning payments and their status using receive request monitoring. Gets the status of a Lightning receive request by ID.

// Monitor a specific invoice
const receiveRequest = await wallet.getLightningReceiveRequest(invoiceId);
if (!receiveRequest) {
  throw new Error("Receive request not found or not accessible to this wallet");
}
console.log("Payment status:", receiveRequest.status);
console.log("Transfer amount:", receiveRequest.transfer?.totalAmount);

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

Show Parameters

string

required

The ID of the Lightning receive request

Show Returns

LightningReceiveRequest | null

required

The receive request details, or null if not found or not accessible to the querying wallet

Match the invoice, request, and transfer

Save the receive request’s id and invoice.paymentHash when creating the invoice. The BOLT11 payment hash identifies the Lightning payment; the Spark transfer ID identifies the movement of funds on Spark. They are different identifiers. Once the receive request has a transfer, request.transfer.sparkId links it to operator transfer history:

const request = await wallet.getLightningReceiveRequest(receiveRequestId);
if (request?.transfer) {
  console.log("Lightning payment hash:", request.invoice.paymentHash);
  console.log("Spark transfer ID:", request.transfer.sparkId);
}

The operator’s Transfer does not carry the Lightning payment hash. If you start with a Spark transfer ID, use getTransferFromSsp() to retrieve its associated payment request. A plain Lightning receive can have no sparkInvoice; that optional field is not the correlation key, and includeSparkAddress: false does not populate it. Only the requester or receiver can look up the receive request. An unrelated wallet gets null, which does not establish that the invoice does not exist. A viewer grant for Bitcoin history does not grant access to Lightning receive requests.

Amounts and units

Field	Unit
`createLightningInvoice({ amountSats })`	Satoshis
`request.invoice.amount`	Read `originalValue` together with `originalUnit`; Lightning invoices use millisatoshis
`request.transfer.totalAmount`	Currency amount object; Spark transfer amounts use satoshis
Webhook `htlc_amount`	`{ value, unit }` or `null`; inspect `unit` instead of assuming millisatoshis
Webhook `invoice_amount`	`{ value, unit }`; normally `SATOSHI`

For example, a 1,000-sat invoice has originalValue: 1000000 with originalUnit: "MILLISATOSHI". Do not compare bare amount values across these surfaces. The request has no amountReceived field.

Completion and event order

A Lightning receive request status such as PAYMENT_PREIMAGE_RECOVERED or TRANSFER_COMPLETED, an operator transfer status, and the wallet’s transfer:claimed event describe different steps. A completed Lightning receive request does not establish that the receiver has claimed the funds. See received versus spendable. The incoming Spark transfer can appear before the receive request is finalized and its webhook is delivered. These describe successive parts of the receive flow. Your application may observe events and lookup responses at different times, so do not require a particular notification arrival order. Persist the identifiers, handle repeated notifications, and re-query the request if its transfer is not yet available. Stream heartbeats are connection activity, not payments; do not depend on a fixed heartbeat interval. For server notifications, see Webhooks, including the difference between webhook IDs and SDK request IDs.

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`);
});

Introduction

Installation

Wallet

Transfers

Deposits

Withdrawals

Fees

Spark Signer Interface

Tools

Deposit from Lightning

Understanding Lightning Invoices

Lightning Deposit Flow

Create Lightning Invoice

Spark Payment Integration

Option 1: Spark Invoice in Routing Hints

Option 2: Spark Address in Fallback Field

Fallback Address Format

Creating Invoices for Other Spark Users

Zero-Amount Invoices

Creating Zero-Amount Invoices

Monitor Lightning Payments

Match the invoice, request, and transfer

Amounts and units

Completion and event order

Real-time Payment Monitoring

​Understanding Lightning Invoices

​Lightning Deposit Flow

​Create Lightning Invoice

​Spark Payment Integration

​Option 1: Spark Invoice in Routing Hints

​Option 2: Spark Address in Fallback Field

​Fallback Address Format

​Creating Invoices for Other Spark Users

​Zero-Amount Invoices

​Creating Zero-Amount Invoices

​Monitor Lightning Payments

​Match the invoice, request, and transfer

​Amounts and units

​Completion and event order

​Real-time Payment Monitoring

Understanding Lightning Invoices

Lightning Deposit Flow

Create Lightning Invoice

Spark Payment Integration

Option 1: Spark Invoice in Routing Hints

Option 2: Spark Address in Fallback Field

Fallback Address Format

Creating Invoices for Other Spark Users

Zero-Amount Invoices

Creating Zero-Amount Invoices

Monitor Lightning Payments

Match the invoice, request, and transfer

Amounts and units

Completion and event order

Real-time Payment Monitoring