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

NAME
     sendpay -- Low-level command for sending a payment via a route

SYNOPSIS
     sendpay  route payment_hash [label] [amount_msat] [bolt11] [payment_secret]
     [partid] [localinvreqid] [groupid] [payment_metadata] [description]

DESCRIPTION
     The sendpay RPC command attempts to send funds associated	with  the  given
     payment_hash, along a route to the final destination in the route.

     Generally,   a   client  would  call  lightning-getroute(7)  or  lightning-
     getroutes(7) to resolve a route, then use sendpay to send it.  This is  why
     sendpay's	route ignores unknown members: it uses the fields from either of
     those commands and ignored others. If it fails, it  would	call  lightning-
     getroutes(7)  again  to  retry. If the route is empty, a payment-to-self is
     attempted.

     The response will occur when the payment is on its way to the  destination.
     The  sendpay  RPC	command  does  not wait for definite success or definite
     failure of the payment (except for already-succeeded payments,  or  to-self
     payments).  Instead,  use	the  waitsendpay RPC command to poll or wait for
     definite success or definite failure.

     Once a payment has succeeded, calls to sendpay with the  same  payment_hash
     but  a  different amount_msat or destination will fail; this prevents acci-
     dental multiple payments. Calls to  sendpay  with	the  same  payment_hash,
     amount_msat,  and	destination  as a previous successful payment (even if a
     different route or partid) will return immediately with success.

     *	route (array of objects):
	*  short_channel_id_dir (short_channel_id_dir,	optional):  The  channel
	   joining these nodes. (added v26.06)
	*  node_id_out	(pubkey,  optional):  The  node  at the end of this hop.
	   (added v26.06)
	*  amount_out_msat (msat, optional): The amount expected at the far  end
	   of this hop. (added v26.06)
	*  cltv_out  (u32, optional): The total CLTV expected by the node at the
	   end of this hop. (added v26.06)
	*  id (pubkey, optional): The node at the end of this  hop  (older  name
	   for node_id_out).
	*  channel (short_channel_id, optional): The channel joining these nodes
	   (older name for short_channel_id_dir)
	*  delay (u32, optional): The total CLTV expected by the node at the end
	   of this hop (older name for cltv_out).
	*  amount_msat	(msat, optional): The amount expected by the node at the
	   end of this hop (older name for amount_out_msat).
     *	payment_hash (hash): The hash of the payment_preimage.
     *	label (string, optional): The  label  provided	when  creating	the  in-
	voice_request.
     *	amount_msat  (msat, optional): Amount must be provided if partid is non-
	zero, or the payment is to-self, otherwise it must be equal to the final
	amount to the destination. it can be a whole number, or a  whole  number
	ending	in  msat or sat, or a number with three decimal places ending in
	sat, or a number with 1 to 11 decimal places ending in btc. The  default
	is in millisatoshi precision.
     *	bolt11	(string,  optional): Bolt11 invoice to pay. If provided, will be
	returned in waitsendpay and listsendpays results.
     *	payment_secret (secret, optional): Value that the  final  recipient  re-
	quires	to  accept  the payment, as defined by the payment_data field in
	BOLT 4 and the s field in the BOLT 11 invoice format. It is required  if
	partid is non-zero.
     *	partid	(u64, optional): Must not be provided for self-payments. If pro-
	vided and non-zero, allows for multiple parallel partial  payments  with
	the  same  payment_hash. The amount_msat amount (which must be provided)
	for each sendpay with matching payment_hash must be equal,  and  sendpay
	will fail if there are differing values given.
     *	localinvreqid (hex, optional): Indicates that this payment is being made
	for  a	local  invoice_request. This ensures that we only send a payment
	for a single-use invoice_request once.
     *	groupid (u64, optional): Allows you to attach a number which appears  in
	listsendpays  so  payments can be identified as part of a logical group.
	The pay plugin uses this to identify one attempt at a MPP  payment,  for
	example.
     *	payment_metadata  (hex,  optional):  Placed  in the final onion hop TLV.
	(added v0.11.0)
     *	description (string, optional): Description used in the invoice.  (added
	v0.11.0)

RETURN VALUE
     On success, an object is returned, containing:

     *	created_index  (u64):  1-based	index  indicating order this payment was
	created in. (added v23.11)
     *	id (u64): Old synonym for created_index.
     *	payment_hash (hash): The hash of the payment_preimage which  will  prove
	payment.
     *	status	(string)  (one	of "pending", "complete"): Status of the payment
	(could be complete if already sent previously).
     *	created_at (u64): The UNIX timestamp showing when this payment was  ini-
	tiated.
     *	amount_sent_msat (msat): The amount sent.
     *	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)
     *	groupid (u64, optional): Grouping key to disambiguate multiple	attempts
	to pay an invoice or the same payment_hash.
     *	amount_msat  (msat,  optional):  The amount delivered to destination (if
	known).
     *	destination (pubkey, optional): The final destination of the payment  if
	known.
     *	completed_at  (u64, optional): The UNIX timestamp showing when this pay-
	ment was completed.
     *	label (string, optional): The label, if given to sendpay.
     *	partid (u64, optional): The partid, if given to sendpay.
     *	bolt11 (string, optional): The bolt11 string (if supplied).
     *	bolt12 (string, optional): The bolt12 string (if supplied).

     If status is "complete": - payment_preimage (secret): The proof of payment:
     SHA256 of this payment_hash.

     If status is "pending": - message (string): Monitor status with listpays or
     waitsendpay.

ERRORS
     On error, if the error occurred from a node other than the  final	destina-
     tion,  the route table will be updated so that lightning-getroute(7) should
     return an alternate route (if any). An error from the final destination im-
     plies the payment should not be retried.

     *	-1: Catchall nonspecific error.
     *	201: Already paid with this hash using different amount or destination.
     *	202: Unparseable onion reply. The data field of the error will	have  an
	onionreply field, a hex string representation of the raw onion reply.
     *	203:  Permanent failure at destination. The data field of the error will
	be routing failure object.
     *	204: Failure along route; retry a different route. The data field of the
	error will be routing failure object.
     *	212: localinvreqid refers to an invalid, or used, local invoice_request.

     A routing failure object has the fields below:

     erring_index: The index of the node along the route that reported	the  er-
     ror.  0  for  the local node, 1 for the first hop, and so on.  erring_node:
     The hex string of the pubkey id  of  the  node  that  reported  the  error.
     erring_channel:  The short channel ID of the channel that has the error, or
     0:0:0 if the destination node raised the error. In  addition  erring_direc-
     tion  will  indicate  which  direction  of  the channel caused the failure.
     failcode: The failure code, as per BOLT #4.  channel_update: The hex string
     of the channel_update message received from the remote node.  Only  present
     if  error	is from the remote node and the failcode has the UPDATE bit set,
     as per BOLT #4.

AUTHOR
     Rusty Russell rusty@rustcorp.com.au is mainly responsible.

SEE ALSO
     lightning-listinvoices(7), lightning-delinvoice(7),  lightning-getroute(7),
     lightning-invoice(7), lightning-xpay(7), lightning-waitsendpay(7)

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

EXAMPLES
     Example 1:

     Request:

     $ lightning-cli sendpay -k "route"='[{"id": "nodeid020202020202020202020202020202020202020202020202020202020202", "channel": "109x1x1", "direction": 1, "amount_msat": 10001, "delay": 15, "style": "tlv"}, {"id": "nodeid030303030303030303030303030303030303030303030303030303030303", "channel": "111x1x1", "direction": 0, "amount_msat": 10000, "delay": 9, "style": "tlv"}]' "payment_hash"="paymenthashinvl0310031003100310031003100310031003100310031003100" "payment_secret"="paymentsecretinvl00310003100031000310003100031000310003100031000"

     {
       "id": "example:sendpay#1",
       "method": "sendpay",
       "params": {
	 "route": [
	   {
	     "id": "nodeid020202020202020202020202020202020202020202020202020202020202",
	     "channel": "109x1x1",
	     "direction": 1,
	     "amount_msat": 10001,
	     "delay": 15,
	     "style": "tlv"
	   },
	   {
	     "id": "nodeid030303030303030303030303030303030303030303030303030303030303",
	     "channel": "111x1x1",
	     "direction": 0,
	     "amount_msat": 10000,
	     "delay": 9,
	     "style": "tlv"
	   }
	 ],
	 "payment_hash": "paymenthashinvl0310031003100310031003100310031003100310031003100",
	 "payment_secret": "paymentsecretinvl00310003100031000310003100031000310003100031000"
       }
     }

     Response:

     {
       "message": "Monitor status with listpays or waitsendpay",
       "created_index": 2,
       "id": 2,
       "payment_hash": "paymenthashinvl0310031003100310031003100310031003100310031003100",
       "groupid": 1,
       "destination": "nodeid030303030303030303030303030303030303030303030303030303030303",
       "amount_msat": 10000,
       "amount_sent_msat": 10001,
       "created_at": 1738000000,
       "status": "pending"
     }

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