> ## Documentation Index
> Fetch the complete documentation index at: https://docs.spark.money/llms.txt
> Use this file to discover all available pages before exploring further.

# 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

```typescript theme={null}
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

<ResponseField name="amountSats" type="number" required>
  Amount in satoshis to receive. Must be a safe integer (less than 2^53).
</ResponseField>

<ResponseField name="paymentHash" type="string" required>
  64-character hex string representing the payment hash. You must know the preimage for this hash to settle the payment.
</ResponseField>

<ResponseField name="memo" type="string">
  Optional memo/description for the invoice (max 639 characters). Cannot be used together with `descriptionHash`.
</ResponseField>

<ResponseField name="expirySeconds" type="number">
  Invoice expiry time in seconds (default: 2,592,000 = 30 days)
</ResponseField>

<ResponseField name="includeSparkAddress" type="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.
</ResponseField>

<ResponseField name="includeSparkInvoice" type="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.
</ResponseField>

<ResponseField name="receiverIdentityPubkey" type="string">
  33-byte compressed identity pubkey for generating invoices for other Spark users
</ResponseField>

<ResponseField name="descriptionHash" type="string">
  SHA256 hash of the description for BOLT11 description\_hash field. Cannot be used together with `memo`.
</ResponseField>

## Returns

<ResponseField name="request" type="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
</ResponseField>

<Note>
  Access the BOLT11 invoice string via `request.invoice.encodedInvoice`.
</Note>

<Warning>
  **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.
</Warning>

## Examples

```typescript theme={null}
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