createLightningHodlInvoice

Create a BOLT11 Lightning hold invoice with a custom payment hash.

Creates a Lightning hold invoice (HODL invoice) with a custom payment hash. Hold invoices allow you to accept payments that are held in a pending state until you explicitly settle or cancel them.

Method Signature

type CreateLightningHodlInvoiceParams = {
  amountSats: number;
  paymentHash: string;
  memo?: string;
  expirySeconds?: number;
  includeSparkAddress?: boolean;
  includeSparkInvoice?: boolean;
  receiverIdentityPubkey?: string;
  descriptionHash?: string;
};

async createLightningHodlInvoice(params: CreateLightningHodlInvoiceParams): Promise<LightningReceiveRequest>;

Parameters

amountSats · number · required

Amount in satoshis to receive. Must be a safe integer (less than 2^53).

paymentHash · string · required

64-character hex string representing the payment hash. You must know the preimage for this hash to settle the payment.

memo · string

Optional memo/description for the invoice (max 639 characters). Cannot be used together with descriptionHash.

expirySeconds · number

Invoice expiry time in seconds (default: 2,592,000 = 30 days)

includeSparkAddress · boolean

Whether to embed Spark address in the invoice fallback field. Mutually exclusive with includeSparkInvoice. Note: If the payer uses the fallback address instead of Lightning, the payment cannot be correlated to this invoice—it appears as a separate Spark transfer.

includeSparkInvoice · boolean

Whether to include a Spark invoice in the invoice routing hints. Mutually exclusive with includeSparkAddress. When enabled, allows payers to seamlessly pay over Spark if they support it.

receiverIdentityPubkey · string

33-byte compressed identity pubkey for generating invoices for other Spark users

descriptionHash · string

SHA256 hash of the description for BOLT11 description_hash field. Cannot be used together with memo.

Returns

request · LightningReceiveRequest · required

The Lightning receive request object containing:

• id: Unique identifier for the request
• invoice: Invoice object with encodedInvoice, paymentHash, amount, etc.
• status: Request status
• createdAt, updatedAt: Timestamps

Access the BOLT11 invoice string via request.invoice.encodedInvoice.

Hold Invoice Requirements: You must know the preimage that corresponds to the paymentHash parameter. When a payer pays this invoice, the payment will be held until you provide the preimage to settle it. If you don’t know the preimage, you won’t be able to claim the funds.

Examples

import { createHash, randomBytes } from 'crypto';

// Generate preimage and payment hash
const preimage = randomBytes(32);
const paymentHash = createHash('sha256').update(preimage).digest('hex');

// Create hold invoice with custom payment hash
const hodlInvoice = await wallet.createLightningHodlInvoice({
  amountSats: 1000,
  paymentHash: paymentHash,
  memo: "Hold invoice for conditional payment",
  expirySeconds: 3600 // 1 hour
});

console.log("Hold invoice:", hodlInvoice.invoice.encodedInvoice);
console.log("Request ID:", hodlInvoice.id);
console.log("Payment hash:", hodlInvoice.invoice.paymentHash);

// Store preimage securely - you'll need it to settle the payment
console.log("Preimage (keep secret):", preimage.toString('hex'));

// Hold invoice with embedded Spark invoice
const sparkHodlInvoice = await wallet.createLightningHodlInvoice({
  amountSats: 1000,
  paymentHash: paymentHash,
  memo: "Hold invoice with Spark support",
  includeSparkInvoice: true
});

Use Cases

Hold invoices are useful for:

• Conditional payments: Accept payment but don’t settle until certain conditions are met
• Atomic swaps: Coordinate payments across different systems using the same preimage
• Escrow services: Hold funds until both parties confirm the transaction
• Cross-chain operations: Lock funds that depend on events in other blockchains