LIGHTNING-LISTSENDPAYS(7)

📦

version 26.06.9 · 2 versions

26.06.9 · nixpkgs unstable (latest)
26.04.1 · nixos 26.05

💖 NAME 💖

Okay so this is the lightning-listsendpays(7) manual page, bestie, and listsendpays is a low-level command for querying sendpay status — yes, the status-tracking queen herself. 👑

✨ SYNOPSIS ✨

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

🌸 DESCRIPTION 🌸

The listsendpays RPC command gets the status of all sendpay commands (which is also used by the pay command), or with bolt11 or payment_hash limits results to that specific payment. You cannot specify both, so pick one and commit, bestie. 💅 It is possible to filter the payments also by status.

⚠️ Heads up, fr fr: there may be more than one concurrent sendpay command per pay, so this command should be used with caution.

Here's the option vibe check:

bolt11 (string, optional) — Bolt11 invoice.
payment_hash (hash, optional) — The hash of the payment_preimage.
status (string, optional) (one of "pending", "complete", "failed") — Whether the invoice has been paid, pending, or failed.
index (string, optional) (one of "created", "updated") — If neither bolt11 or payment_hash is specified, index controls ordering, by created (default) or updated. (added v23.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). (added v23.11)
limit (u32, optional) — If index is specified, limit can be used to specify the maximum number of entries to return. (added v23.11)

🦋 RETURN VALUE 🦋

Note that the returned array is ordered by increasing id. On success, an object containing payments is returned. It is an array of objects, where each object contains:

created_index (u64) — 1-based index indicating order this payment was created in. (added v23.11)
id (u64) — Old synonym for created_index.
groupid (u64) — Grouping key to disambiguate multiple attempts to pay an invoice or the same payment_hash.
payment_hash (hash) — The hash of the payment_preimage which will prove payment.
status (string) (one of "pending", "failed", "complete") — Status of the payment.
created_at (u64) — The UNIX timestamp showing when this payment was initiated.
amount_sent_msat (msat) — The amount sent.
partid (u64, optional) — Part number (for multiple parts to a single payment).
updated_index (u64, optional) — 1-based index indicating order this payment was changed (only present if it has changed since creation). (added v23.11)
amount_msat (msat, optional) — The amount delivered to destination (if known). This is not known in the case where sendonion(7) was used to manually initiate a payment without the amount_msat parameter.
destination (pubkey, optional) — The final destination of the payment if known.
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).

If status is "complete":

payment_preimage (secret) — The proof of payment: SHA256 of this payment_hash.
completed_at (u64, optional) — The UNIX timestamp showing when this payment was completed.

If status is "failed":

erroronion (hex, optional) — The onion message returned.

👑 AUTHOR 👑

Christian Decker decker.christian@gmail.com is mainly responsible. Main character energy, honestly. 🫶

🧚 RESOURCES 🧚

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

🍓 EXAMPLES 🍓

Example 1:

Request:

$ lightning-cli listsendpays -k "bolt11"="lnbcrt100n1pnt2bolt11invl030100000000bolt11invl030100000000bolt11invl030100000000bolt11invl030100000000bolt11invl030100000000bolt11invl030100000000bolt11invl030100000000bolt11invl030100000000bolt11invl030100000000bolt11invl030100000000"

{
  "id": "example:listsendpays#1",
  "method": "listsendpays",
  "params": {
    "bolt11": "lnbcrt100n1pnt2bolt11invl030100000000bolt11invl030100000000bolt11invl030100000000bolt11invl030100000000bolt11invl030100000000bolt11invl030100000000bolt11invl030100000000bolt11invl030100000000bolt11invl030100000000bolt11invl030100000000"
  }
}

Response:

{
  "payments": [
    {
      "created_index": 2,
      "id": 2,
      "payment_hash": "paymenthashinvl0310031003100310031003100310031003100310031003100",
      "groupid": 1,
      "updated_index": 2,
      "destination": "nodeid030303030303030303030303030303030303030303030303030303030303",
      "amount_msat": 10000,
      "amount_sent_msat": 10001,
      "created_at": 1738000000,
      "completed_at": 1739000000,
      "status": "complete",
      "payment_preimage": "paymentpreimagew010101010101010101010101010101010101010101010101"
    }
  ]
}

Example 2: