LIGHTNING-WAITINVOICE(7)

📦

version 26.06.9 · 2 versions

26.06.9 · nixpkgs unstable (latest)
26.04.1 · nixos 26.05

💅 LIGHTNING-WAITINVOICE(7) — the `lightning-waitinvoice` girlies' guide ✨

okay bestie so you found the lightning-waitinvoice manual page, and honestly? it's lowkey iconic. it's a page from the Core Lightning docs (that's the LIGHTNING part, iykyk) and it's section 7, which is the ~misc/commands~ section. anyway, let's get into it 🫶

🌸 NAME 🌸

waitinvoice — the command for waiting for one specific payment to show up. like, you pick the invoice, and you just... sit there. patiently. main character energy fr 💅

✨ SYNOPSIS ✨

waitinvoice label

that's it. that's the whole vibe. one label, one command, one wait 👑

🦋 DESCRIPTION 🦋

the waitinvoice RPC command waits until a specific invoice gets paid, and then it hands you back that single entry, formatted exactly like it would come out of listinvoices. one entry, no scrolling, no drama. we love a focused queen 💖

label — one of the following. this is the unique label of the invoice you're waiting to see paid 💸
- (string)
- (integer)

so yeah, it takes a string or an integer, and that's the whole parameter list. not me expecting more, but honestly? simplicity ate. periodt 🌈

🎀 RETURN VALUE 🎀

on success you get an object back, and it's giving full inventory. here's everything that can show up in it:

label (string) — the unique label you supplied at invoice creation. the name tag of your invoice 🏷️
payment_hash (hash) — the hash of the payment_preimage that will prove payment. it's the receipt-to-be, basically 🔐
status (string, one of "paid" or "expired") — whether the invoice is paid or expired. the ultimate vibe check 💀
expires_at (u64) — UNIX timestamp of when it will become / became unpayable. the deadline, bestie ⏰
created_index (u64) — 1-based index indicating the order this invoice was created in. (added v23.08)
description (string, optional) — the description used in the invoice 📝
amount_msat (msat, optional) — the amount required to pay this invoice. the price tag 💰
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 the order this invoice was changed. only present if it actually has changed since creation, so if it's missing, nothing's happened, no cap. (added v23.08)

and if status is "paid", you ALSO get this whole extra glow-up of fields:

pay_index (u64) — unique incrementing index for this payment 🔢
amount_received_msat (msat) — the amount actually received. note that this could be slightly greater than amount_msat, because clients may overpay (generous of them honestly, we stan an overpayer 🫶)
paid_at (u64) — UNIX timestamp of when it was paid 📅
payment_preimage (secret) — proof of payment. the crown jewel of this whole response 👑
paid_outpoint (object, optional) — the 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 😭

when things go wrong, the returned object contains code and message properties, and code is gonna be one of these bad boys:

-32602 — if the given parameters are wrong. typo era, we've all been there 🙈
-1 — if the invoice is deleted while unpaid, or if the invoice simply does not exist. it's gone, bestie, it's not coming back 💀
903 — if the invoice expires before being paid, or if it's already expired. the deadline passed while you were waiting, tragic ⏳

🧚 AUTHOR 🧚

Christian Decker decker.christian@gmail.com is mainly responsible. thank you for your service king 🫡

⭐ SEE ALSO ⭐

(the whole invoice cinematic universe, honestly 💜)

🌈 RESOURCES 🌈

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

go poke around, it's a good time ✨

💅 EXAMPLES 💅

Example 1: the `-k` era 🔥

Request:

$ lightning-cli waitinvoice -k "label"="inv2"

{
  "id": "example:waitinvoice#1",
  "method": "waitinvoice",
  "params": {
    "label": "inv2"
  }
}

Response:

{
  "label": "inv2",
  "bolt11": "lnbcrt222n1pnt3005720bolt11wtinv01010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101",
  "payment_hash": "paymenthashwaitinv0101010101010101010101010101010101010101010101",
  "amount_msat": 2000,
  "status": "paid",
  "pay_index": 5,
  "amount_received_msat": 2000,
  "paid_at": 1738500000,
  "payment_preimage": "paymentpreimagewaitinv0010101010101010101010101010101010101010101",
  "description": "inv2",
  "expires_at": 1739000000,
  "created_index": 13,
  "updated_index": 5
}

like look at that updated_index: 5. it changed, and it told us. we love transparency ✨

Example 2: the positional-argument serve 🍓