LIGHTNING-LISTPAYS(7)

📦
version 26.06.9 · 2 versions
, in nixpkgs unstable

💅 LIGHTNING-LISTPAYS(7) 💅

okay bestie so this is the manual page for lightning-listpays — yes the whole thing is literally called LIGHTNING-LISTPAYS(7), we're fancy like that. it's a 7 page, it's a command page, it's iconic, it's here to tell you how to check on your payments. let's go 🫶

✨ NAME ✨

listpays — the command for querying payment status. that's it. that's the vibe check. 💅

🌸 SYNOPSIS 🌸

listpays [bolt11] [payment_hash] [status] [index] [start] [limit]

look at all those optional lil arguments. every single one of them is optional, which is giving "no pressure, bestie". 🦋

💖 DESCRIPTION 💖

so the listpays RPC command gets the status of all pay commands — it does this by combining results from listsendpays, which lists every payment part 🤝 — or it gets just a single one if either bolt11 or payment_hash was specified. one payment. one vibe. your choice. ✨

okay now the args, one by one, no skipping, we don't do that here:

  • bolt11 (string, optional) — a Bolt11 string, and you get the payment details for it. 🎀
  • payment_hash (hash, optional) — a payment hash, and you get the payment details for that. 🎀
  • status (string, optional) (one of "pending", "complete", "failed") — filters the payment by status. pick your fighter. 🔥
  • index (string, optional) (one of "created", "updated") — if neither in_channel nor out_channel is specified, this controls ordering, by created or updated. (added v24.11) ⭐
  • start (u64, optional) — if index is specified, start may be specified to start from that value, which is generally returned from lightning-wait(7). NOTE: if this is used, amount_sent_msat and number_of_parts fields may be lower than expected, as not all payment parts will be considered (added v24.11). ⚠️ read that note, i'm serious, it's giving "numbers might lie a lil" 😭
  • limit (u32, optional) — if index is specified, limit can be used to specify the maximum number of entries to return. NOTE: if this is used, amount_sent_msat and number_of_parts fields may be lower than expected, as not all payment parts will be considered. NOTE: the actual number returned may be less than the limit, as individual payment parts are combined together (added v24.11). 💀 two notes!! double warning!! the limit isn't a promise, it's a ceiling, bestie.

👑 RETURN VALUE 👑

on success, an object containing pays is returned. it's an array of objects, and each object contains:

  • payment_hash (hash) — the hash of the payment_preimage which will prove payment. proof, but make it cryptographic. 🔥
  • status (string) (one of "pending", "failed", "complete") — status of the payment.
  • created_at (u64) — the UNIX timestamp showing when this payment was initiated. ⏰
  • created_index (u64) — 1-based index indicating order this payment was created in. (added v24.11)
  • destination (pubkey, optional) — the final destination of the payment if known. 🎯
  • completed_at (u64, optional) — the UNIX timestamp showing when this payment was completed.
  • label (string, optional) — the label, if given to sendpay. 🏷️
  • bolt11 (string, optional) — the bolt11 string (if pay supplied one).
  • description (string, optional) — the description matching the bolt11 description hash (if pay supplied one).
  • bolt12 (string, optional) — the bolt12 string (if supplied for pay).
  • updated_index (u64, optional) — 1-based index indicating order this payment was changed (only present if it has changed since creation). (added v24.11) ✨

💜 if status is "complete" 💜

  • amount_sent_msat (msat) — the amount of millisatoshi we sent in order to pay (may include fees and not match amount_msat). 💸
  • preimage (secret) — proof of payment. the receipts, the tea, the whole moment. ☕
  • amount_msat (msat, optional) — the amount of millisatoshi we intended to send to the destination. this can only be missing in the case of someone manually calling sendonion without the amount_msat parameter (which no plugin currently does). 🙈
  • number_of_parts (u64, optional) — the number of parts for a successful payment (only if more than one). 🧩

🥀 if status is "failed" 🥀

  • erroronion (hex, optional) — the error onion returned on failure, if any. it's giving sad girl hours but at least you get data. 😭
the returned array is ordered by increasing created_at fields. oldest first, always. chronological queen behavior. 👑

🧚 AUTHOR 🧚

Rusty Russell rusty@rustcorp.com.au is mainly responsible. yes, that Rusty. thank him, he's the main character here. 🌟

🌈 SEE ALSO 🌈

go read those too, iykyk. 📚

🎀 RESOURCES 🎀

main web site: https://github.com/ElementsProject/lightning — that's the whole resource list, short and slay. 💻

⭐ EXAMPLES ⭐

🌸 Example 1: 🌸

request:

$ lightning-cli listpays -k "bolt11"="lnbcrt100n1pnt2bolt11invl032000000000bolt11invl032000000000bolt11invl032000000000bolt11invl032000000000bolt11invl032000000000bolt11invl032000000000bolt11invl032000000000bolt11invl032000000000bolt11invl032000000000bolt11invl032000000000"

{
  "id": "example:listpays#1",
  "method": "listpays",
  "params": {
    "bolt11": "lnbcrt100n1pnt2bolt11invl032000000000bolt11invl032000000000bolt11invl032000000000bolt11invl032000000000bolt11invl032000000000bolt11invl032000000000bolt11invl032000000000bolt11invl032000000000bolt11invl032000000000bolt11invl032000000000"
  }
}

response:

{
  "pays": []
}

empty array. no payments. we love a clean slate. 🫧

🌸 Example 2: 🌸

request:

$ lightning-cli listpays

{
  "id": "example:listpays#2",
  "method": "listpays",
  "params": {}
}

response:

{
  "pays": []
}

again, empty. params is {}, we passed nothing, and honestly? slay. ✨

okay bestie that's the whole page, you're basically a listpays expert now, go check those payments and remember: created_at ordering, notes on start and limit, and every single field accounted for. 💅

— xoxo, this page was brought to you by Core Lightning v26.06.9 and the manual section LIGHTNING-LISTPAYS(7) 🎀🦋💜

📦 where this page comes from