lightning-waitanyinvoice -- Command for waiting for payments
waitanyinvoice [lastpay_index] [timeout]
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 including this index. 0 is equivalent to not specifying and negative
value is invalid.
- timeout (u64, optional): If specified, wait at most that number of
seconds, 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
indefinitely.
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 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)
- 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
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)
The following error codes may occur:
- •
- 904: The timeout was reached without an invoice being paid.
lightning-waitinvoice(7), lightning-listinvoices(7),
lightning-delinvoice(7), lightning-invoice(7)
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
}