LIGHTNING-WAITANYINVOICE(7)

📦

version 26.06.9 · 2 versions

26.06.9 · nixpkgs unstable (latest)
26.04.1 · nixos 26.05

💸 waitanyinvoice — LIGHTNING-WAITANYINVOICE(7) 💸

okay bestie so this is the manual page for lightning-waitanyinvoice, section 7 of the Lightning manual. yes the header says LIGHTNING-WAITANYINVOICE(7) twice, that's just how manpages roll, we don't question it. sit down, grab a strawberry 🍓, this one's actually so useful.

🌸 NAME 🌸

waitanyinvoice — the command for waiting for payments, and honestly it does exactly what it says on the tin. no notes. 👑

✨ SYNOPSIS ✨

waitanyinvoice [lastpay_index] [timeout]

💅 DESCRIPTION 💅

so the waitanyinvoice RPC command just... waits. it sits there patiently until an invoice gets paid, then returns a single entry exactly like listinvoices would. 🫶

the important bit: it will not return for any invoices paid prior to or including the lastpay_index. that's your whole safety rail, bestie.

the way you normally use this is iteratively — iconic behavior honestly: you call it once with no arguments, then you call it again and again, each time passing in the pay_index from the entry it handed you back. this is how you make sure no paid invoice ever slips through the cracks. and pay_index? it's a monotonically-increasing number that gets assigned to an invoice the moment 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 it at all, and a negative value is invalid (don't do it 🙈).
timeout (u64, optional) — if you specify it, the command waits at most that number of seconds, and it must be an integer. if the specified timeout is reached, this command returns with an error. you can even set it to 0 so that waitanyinvoice returns immediately with an error if no pending invoice is available yet. if you leave it unspecified, this command will wait indefinitely — literally forever, no cap. 😭

🎀 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 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)

and if status is "paid", you also get this whole extra little family of fields 🔥:

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 — generous of them 💖).
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)

💀 ERRORS 💀

the following error codes may occur:

904 — the timeout was reached without an invoice being paid.

lowkey the saddest error code. you waited, and nobody paid. it's giving ghosted. 👻

🌈 AUTHOR 🌈

Rusty Russell rusty@rustcorp.com.au is mainly responsible. absolute main character energy, we stan. 👑

⭐ 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