Spark Invoices

Spark Invoices are native payment requests for the Spark network. Unlike Lightning invoices, Spark invoices support both Bitcoin (sats) and tokens, with optional amounts, expiry times, and signature verification.

Overview

Spark Invoices provide:

Sats & Token Support - Request payment in Bitcoin or any Spark token
Optional Amounts - Create invoices with or without a preset amount
Expiration - Set custom expiry times for invoices
Signature Verification - Cryptographically signed by the receiver
Batch Payments - Fulfill multiple invoices in a single call

Spark invoices are receiver-generated and receiver-signed. The receiver must create the invoice for signature validation.

Create a Sats Invoice

Request a Bitcoin payment using a Spark invoice. createSatsInvoice(params) Creates a Spark invoice for receiving Bitcoin.

const invoice = await wallet.createSatsInvoice({
  amount: 10000,              // Optional: amount in sats
  memo: "Payment for coffee", // Optional: description
  expiryTime: new Date(Date.now() + 3600 * 1000) // Optional: 1 hour from now
});

console.log("Spark Invoice:", invoice);

Show Parameters

amount

number

Amount in satoshis to request. If omitted, payer specifies the amount.

memo

string

Optional memo/description for the invoice (max 120 bytes)

senderSparkAddress

string

Optional: restrict payment to a specific sender’s Spark address

expiryTime

Date

Optional expiration time as a Date object (default: 30 days from now)

Create a Token Invoice

Request a token payment using a Spark invoice. createTokensInvoice(params) Creates a Spark invoice for receiving tokens.

const invoice = await wallet.createTokensInvoice({
  tokenIdentifier: "btkn1...",  // Token identifier
  amount: 1000n,                // Optional: token amount
  memo: "Token payment",        // Optional: description
  expiryTime: new Date(Date.now() + 3600 * 1000) // Optional: 1 hour expiry
});

console.log("Token Invoice:", invoice);

Show Parameters

tokenIdentifier

string

required

The Bech32m token identifier (e.g., btkn1...)

amount

bigint

Token amount to request. If omitted, payer specifies the amount.

memo

string

Optional memo/description for the invoice (max 120 bytes)

senderSparkAddress

string

Optional: restrict payment to a specific sender’s Spark address

expiryTime

Date

Optional expiration time as a Date object (default: 30 days from now)

Fulfill Spark Invoices

Pay one or more Spark invoices. fulfillSparkInvoice(params) Fulfills Spark invoices. Supports batch payments with a mix of sats and token invoices.

// Pay a single invoice
const result = await wallet.fulfillSparkInvoice([
  { invoice: "spark1..." }
]);

// Pay multiple invoices (batch)
const batchResult = await wallet.fulfillSparkInvoice([
  { invoice: "spark1..." }, // Sats invoice
  { invoice: "spark1..." }, // Token invoice
]);

// Pay invoice with no preset amount
const customAmount = await wallet.fulfillSparkInvoice([
  { invoice: "spark1...", amount: 5000n } // Specify amount for zero-amount invoice
]);

Show Parameters

sparkInvoices

array

required

Array of objects with invoice: SparkAddressFormat and optional amount: bigint for zero-amount invoices

fulfillSparkInvoice can process multiple invoices in a single call, including a mix of sats and token invoices for different assets.

Query Spark Invoices

Check the status of Spark invoices. querySparkInvoices(invoices) Query the status of one or more Spark invoices.

const invoiceStatus = await wallet.querySparkInvoices([
  "spark1...",
  "spark1..."
]);

for (const status of invoiceStatus) {
  console.log("Invoice status:", status);
}

Show Parameters

invoices

string[]

required

Array of raw Spark invoice strings to query

Invoice Format

Spark invoices are Bech32m-encoded strings that contain:

Network identifier - Derived from the HRP (human-readable prefix)
Receiver’s identity public key - Who will receive the payment
Payment type - Sats or tokens (with token identifier)
Amount - Optional preset amount
Memo - Optional description
Expiry - Optional expiration time
Signature - BIP340 Schnorr signature from the receiver

Use Cases

Point of Sale

// Merchant creates invoice for specific amount
const invoice = await merchantWallet.createSatsInvoice({
  amount: 25000,
  memo: "Order #1234"
});

// Display QR code to customer
displayQR(invoice);

// Customer pays
await customerWallet.fulfillSparkInvoice([
  { invoice }
]);

Donations (Variable Amount)

// Create invoice without preset amount
const donationInvoice = await wallet.createSatsInvoice({
  memo: "Donation to Project X"
});

// Donor chooses amount when paying
await donorWallet.fulfillSparkInvoice([
  { invoice: donationInvoice, amount: 100000n }
]);

Batch Payouts

// Pay multiple recipients in one call
await wallet.fulfillSparkInvoice([
  { invoice: employeeInvoice1 },
  { invoice: employeeInvoice2 },
  { invoice: employeeInvoice3 }
]);

Introduction

Installation

Wallet

Transfers

Deposits

Withdrawals

Fees

Spark Signer Interface

Tools

Spark Invoices

Overview

Create a Sats Invoice

Create a Token Invoice

Fulfill Spark Invoices

Query Spark Invoices

Invoice Format

Use Cases

Point of Sale

Donations (Variable Amount)

Batch Payouts

​Overview

​Create a Sats Invoice

​Create a Token Invoice

​Fulfill Spark Invoices

​Query Spark Invoices

​Invoice Format

​Use Cases

​Point of Sale

​Donations (Variable Amount)

​Batch Payouts

Overview

Create a Sats Invoice

Create a Token Invoice

Fulfill Spark Invoices

Query Spark Invoices

Invoice Format

Use Cases

Point of Sale

Donations (Variable Amount)

Batch Payouts