​
Prerequisites

  • A funded Spark wallet
  • Basic understanding of Lightning Network invoices
  • A counterparty with a Lightning-enabled wallet

​
Understanding 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 optional)
  • 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 (default 24 hours)

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

Mainnet invoice Example: lnbc2500n1pj0ytfcpp5qqqsyqcyq5rqwzqfqypqhp58yjmdan79s6qqdhdzgynm4zwqdx40shp5jqp3qymd6qgpy99ppk0jqjzylqg5t7fhqhpl6s4kxmqgmrn59w5k0z0cqqqqqqzqqqqq9qsqqqqqq9qqqqqqgq9qsqxl9l55y5cwa9s2h8nvdh4h7h43tcwjdcysf7v0fprz5uh6vshs4n0tvhgzz2xgcqpg8yqv7

Regtest invoice Example: lnbcrt2500n1pj0ytfcpp5qqqsyqcyq5rqwzqfqypqhp58yjmdan79s6qqdhdzgynm4zwqdx40shp5jqp3qymd6qgpy99ppk0jqjzylqg5t7fhqhpl6s4kxmqgmrn59w5k0z0cqqqqqqzqqqqq9qsqqqqqq9qqqqqqgq9qsqxl9l55y5cwa9s2h8nvdh4h7h43tcwjdcysf7v0fprz5uh6vshs4n0tvhgzz2xgcqpg8yqv7

​
Receiving Lightning Payments

We do not support Zero amount invoices. But those are coming soon! To receive a payment, generate a lightning invoice:

// Generate invoice with amount
const invoice = await wallet.createLightningInvoice({
  amountSats: 100, // amount in satoshis
  memo: "test invoice", // optional description
});
console.log("Invoice:", invoice);

​
Sending Lightning Payments

To send a payment, you’ll need a Lightning invoice from the recipient:

const invoice_response = await wallet.payLightningInvoice({
  invoice:
    "lnbcrt1u1pnm7ammpp4v84f05tl0kzt6g95g056athdpp8f8azvg6d7epz74z562ymer9jqsp5nc50gazvp0e98u42jlu653rw0eutcl067nqq924hf89q4la4kd9sxq9z0rgqnp4qdnmwu8v22cvq9xsv2l05cn9rre7xlcgdtntxawf8m0zxq3qemgzqrzjqtr2vd60g57hu63rdqk87u3clac6jlfhej4kldrrjvfcw3mphcw8sqqqqrj0q7ew45qqqqqqqqqqqqqq9qcqzpgdq5w3jhxapqd9h8vmmfvdjs9qyyssqj7lf2w4m587g04n4t0ferdv0vnwftzca0xuc9yxycng78cnhrvmyw2mzaa8t76jskpypqnwqhp9xh0vnwxz90jytd34vrmhcngsnl8qplz7ylk",
});
console.log("Invoice Response:", invoice_response);

​
Claiming Received Payments:

Once payment is done, Run getBalance() with the forceRefetch option to claim the payment and view the balance.

const balance = await wallet.getBalance(true /* forceRefetch */);
console.log(`Balance:`, balance);

The getBalance() method returns a Promise resolving to an object containing:

  • balance: A bigint representing the total amount in satoshis
  • tokenBalances: A Map of token balances, where each entry contains:
    • balance: A bigint representing the token amount

​
Paying an invoice directly from regtest

You can do this using the Lightning Command Line tool in the spark repo. Below are the set up instructions:

You can pay invoices using the Lightning Command Line tool in the spark repo. Below are the set up instructions:

Git clone the repo:

git clone https://github.com/buildonspark/spark-sdk.git

Go to the tools folder:

cd spark-sdk/tools/paylightning

Install dependencies:

brew install rust

Verify rust is installed:

rustc --version
cargo --version

Run the Tool:

cargo run -- "your-lightning-invoice"

The first time you run the tool it will download additional dependencies. and then will process the lightning invoice payment. Second time you run it, it will process the payment faster.

​
Best Practices

  • Always verify invoice amounts before paying
  • Keep track of payment hashes for reference
  • Set appropriate expiry times for invoices
  • Monitor payment status for confirmation
  • Claim pending transfers after receiving payments by running getBalance(true)

​
Next Steps

Now that you can send and receive Lightning payments, you might want to:

​
Need Help?

Previous
View all transfers
Next