lightning-waitinvoice -- Command for waiting for specific payment


waitinvoice label


The waitinvoice RPC command waits until a specific invoice is paid,
then returns that single entry as per listinvoice.


On success, an object is returned, containing:

  • label (string): unique label supplied at invoice creation
  • description (string): description used in the invoice
  • payment_hash (hash): the hash of the payment_preimage which will prove payment
  • status (string): Whether it's paid or expired (one of "paid", "expired")
  • expires_at (u64): UNIX timestamp of when it will become / became unpayable
  • created_index (u64): 1-based index indicating order this invoice was created in (added v23.08)
  • amount_msat (msat, optional): the amount required to pay this invoice
  • bolt11 (string, optional): the BOLT11 string (always present unless bolt12 is)
  • bolt12 (string, optional): the BOLT12 string (always present unless bolt11 is)
  • updated_index (u64, optional): 1-based index indicating order this invoice was changed (only present if it has changed since creation) (added v23.08)

If status is "paid":

  • pay_index (u64): Unique incrementing index for this payment
  • amount_received_msat (msat): the amount actually received (could be slightly greater than amount_msat, since clients may overpay)
  • paid_at (u64): UNIX timestamp of when it was paid
  • payment_preimage (secret): proof of payment
  • paid_outpoint (object, optional): Outpoint this invoice was paid with (added v23.11):
    • txid (txid): ID of the transaction that paid the invoice (added v23.11)
    • outnum (u32): The 0-based output number of the transaction that paid the invoice (added v23.11)

On error the returned object will contain code and message properties,
with code being one of the following:

  • -32602: If the given parameters are wrong.
  • -1: If the invoice is deleted while unpaid, or the invoice does not exist.
  • 903: If the invoice expires before being paid, or is already expired.


Christian Decker <[email protected]> is mainly


lightning-waitanyinvoice(7), lightning-listinvoice(7),
lightning-delinvoice(7), lightning-invoice(7)


Main web site: