Skip to main content
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