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() + 3600000) // Optional: 1 hour expiry
});

console.log("Spark Invoice:", 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)

senderPublicKey · string

Optional: restrict payment to a specific sender

expiryTime · Date

Optional expiration time for the invoice

---

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() + 3600000)
});

console.log("Token Invoice:", 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)

senderPublicKey · string

Optional: restrict payment to a specific sender

expiryTime · Date

Optional expiration time for the invoice

---

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({
  invoices: ["spark1..."] // Invoice string
});

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

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

Show Parameters

invoices · array · required

Array of invoice strings, or objects with invoice and amount 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.invoice);

// Customer pays
await customerWallet.fulfillSparkInvoice({
  invoices: [invoice.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({
  invoices: [{ invoice: donationInvoice.invoice, amount: 100000 }]
});

Batch Payouts

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

---

Best Practices

• Set expiry times - Use reasonable expiry times to prevent stale invoices
• Validate before paying - Query invoice status before fulfilling
• Handle zero-amount invoices - Always specify amount when paying invoices without preset amounts
• Use memos - Include descriptive memos for record-keeping
• Batch when possible - Use batch payments for multiple invoices to reduce overhead