home | help 
LIGHTNING-WAITANYINVOICE(7)			     LIGHTNING-WAITANYINVOICE(7)

NAME
     waitanyinvoice -- Command for waiting for payments

SYNOPSIS
     waitanyinvoice [lastpay_index] [timeout]

DESCRIPTION
     The waitanyinvoice RPC command waits until an invoice is paid, then returns
     a	single	entry  as  per listinvoices. It will not return for any invoices
     paid prior to or including the lastpay_index.

     This is usually called iteratively: once with no arguments, then repeatedly
     with the returned pay_index entry. This ensures that  no  paid  invoice  is
     missed.  The  pay_index is a monotonically-increasing number assigned to an
     invoice when it gets paid. The first valid pay_index is 1.

     *	lastpay_index (u64, optional): Ignores any invoices paid prior to or in-
	cluding this index. 0 is equivalent to not specifying and negative value
	is invalid.
     *	timeout (u64, optional): If specified, wait at most that number of  sec-
	onds,  which  must  be	an integer. If the specified timeout is reached,
	this command will return with an error. You can specify  this  to  0  so
	that  waitanyinvoice will return immediately with an error if no pending
	invoice is available yet. If unspecified, this command will wait indefi-
	nitely.

RETURN VALUE
     On success, an object is returned, containing:

     *	label (string): Unique label supplied at invoice creation.
     *	payment_hash (hash): The hash of the payment_preimage which  will  prove
	payment.
     *	status	(string)  (one	of  "paid", "expired"): Whether it's paid or ex-
	pired.
     *	expires_at (u64): UNIX timestamp of when it will  become  /  became  un-
	payable.
     *	created_index  (u64):  1-based	index  indicating order this invoice was
	created in. (added v23.08)
     *	description (string, optional): Description used in the invoice.
     *	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  in-
	voice  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 (se-
     cret): 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)

ERRORS
     The following error codes may occur:

     *	904: The timeout was reached without an invoice being paid.

AUTHOR
     Rusty Russell rusty@rustcorp.com.au is mainly responsible.

SEE ALSO
     lightning-waitinvoice(7),	  lightning-listinvoices(7),	lightning-delin-
     voice(7), lightning-invoice(7)

RESOURCES
     Main web site: https://github.com/ElementsProject/lightning

EXAMPLES
     Example 1:

     Request:

     $ lightning-cli waitanyinvoice

     {
       "id": "example:waitanyinvoice#1",
       "method": "waitanyinvoice",
       "params": {}
     }

     Response:

     {
       "label": "lbl balance l1 to l2",
       "bolt11": "lnbcrt222n1pnt3005720bolt114000101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101",
       "payment_hash": "paymenthashdelpay10101010101010101010101010101010101010101010101",
       "amount_msat": 500000000,
       "status": "paid",
       "pay_index": 1,
       "amount_received_msat": 500000000,
       "paid_at": 1738500000,
       "payment_preimage": "paymentpreimgdp1010101010101010101010101010101010101010101010101",
       "description": "description send some sats l1 to l2",
       "expires_at": 1739000000,
       "created_index": 1,
       "updated_index": 1
     }

     Example 2:

     Request:

     $ lightning-cli waitanyinvoice -k "lastpay_index"=1 "timeout"=0

     {
       "id": "example:waitanyinvoice#2",
       "method": "waitanyinvoice",
       "params": {
	 "lastpay_index": 1,
	 "timeout": 0
       }
     }

     Response:

     {
       "label": "test_injectpaymentonion1",
       "bolt11": "lnbcrt100n1pnt2bolt11invl020700000000bolt11invl020700000000bolt11invl020700000000bolt11invl020700000000bolt11invl020700000000bolt11invl020700000000bolt11invl020700000000bolt11invl020700000000bolt11invl020700000000bolt11invl020700000000",
       "payment_hash": "paymenthashinvl0270027002700270027002700270027002700270027002700",
       "amount_msat": 1000,
       "status": "paid",
       "pay_index": 2,
       "amount_received_msat": 1000,
       "paid_at": 1738500000,
       "payment_preimage": "paymentpreimgio1030303030303030303030303030303030303030303030303",
       "description": "test injectpaymentonion1 description",
       "expires_at": 1739000000,
       "created_index": 8,
       "updated_index": 2
     }

Core Lightning v26.06.1 			     LIGHTNING-WAITANYINVOICE(7)
home | help