home | help 
LIGHTNING-LISTSENDPAYS(7)			       LIGHTNING-LISTSENDPAYS(7)

NAME
     listsendpays -- Low-level command for querying sendpay status

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 re-
     sults  to that specific payment. You cannot specify both. It is possible to
     filter the payments also by status.

     Note that there may be more than one concurrent sendpay command per pay, so
     this command should be used with caution.

     *	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 spec-
	ify 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  ini-
	tiated.
     *	amount_sent_msat (msat): The amount sent.
     *	partid (u64, optional): Part number (for multiple parts to a single pay-
	ment).
     *	updated_index  (u64, optional): 1-based index indicating order this pay-
	ment 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 de-
	scription 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 re-
     turned.

AUTHOR
     Christian Decker decker.christian@gmail.com is mainly responsible.

SEE ALSO
     lightning-listpays(7), lightning-sendpay(7), lightning-listinvoices(7)

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:

     Request:

     $ lightning-cli listsendpays

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

     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"
	 },
	 {
	   "created_index": 3,
	   "id": 3,
	   "payment_hash": "paymenthashkey01k101k101k101k101k101k101k101k101k101k101k101k101",
	   "groupid": 0,
	   "updated_index": 3,
	   "destination": "nodeid030303030303030303030303030303030303030303030303030303030303",
	   "amount_msat": 10000,
	   "amount_sent_msat": 10001,
	   "created_at": 1738010000,
	   "completed_at": 1739010000,
	   "status": "complete",
	   "payment_preimage": "paymentpreimage1010101010101010101010101010101010101010101010101"
	 },
	 {
	   "created_index": 4,
	   "id": 4,
	   "payment_hash": "paymenthashkey02k201k201k201k201k201k201k201k201k201k201k201k201",
	   "groupid": 0,
	   "updated_index": 4,
	   "destination": "nodeid040404040404040404040404040404040404040404040404040404040404",
	   "amount_msat": 10000000,
	   "amount_sent_msat": 10000202,
	   "created_at": 1738020000,
	   "completed_at": 1739020000,
	   "status": "complete",
	   "payment_preimage": "paymentpreimage2020202020202020202020202020202020202020202020202"
	 },
	 {
	   "created_index": 5,
	   "id": 5,
	   "payment_hash": "paymenthashkey03k301k301k301k301k301k301k301k301k301k301k301k301",
	   "groupid": 0,
	   "updated_index": 5,
	   "destination": "nodeid030303030303030303030303030303030303030303030303030303030303",
	   "amount_msat": 10000,
	   "amount_sent_msat": 10001,
	   "created_at": 1738030000,
	   "completed_at": 1739030000,
	   "status": "failed"
	 },
	 {
	   "created_index": 6,
	   "id": 6,
	   "payment_hash": "paymenthashkey03k301k301k301k301k301k301k301k301k301k301k301k301",
	   "groupid": 0,
	   "updated_index": 6,
	   "partid": 1,
	   "destination": "nodeid030303030303030303030303030303030303030303030303030303030303",
	   "amount_msat": 10000,
	   "amount_sent_msat": 10001,
	   "created_at": 1738040000,
	   "completed_at": 1739040000,
	   "status": "complete",
	   "payment_preimage": "paymentpreimage3030303030303030303030303030303030303030303030303"
	 }
       ]
     }

Core Lightning v26.06.1 			       LIGHTNING-LISTSENDPAYS(7)
home | help