Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
LIGHTNING-KEYSEND(7)	       lightning-keysend	  LIGHTNING-KEYSEND(7)

       lightning-keysend - Send	funds to a node	without	an invoice

       keysend	 destination   msatoshi	 [label]  [maxfeepercent]  [retry_for]
       [maxdelay] [exemptfee]

       The keysend RPC command attempts	to find	a route	to the given  destina-
       tion,  and  send	the specified amount to	it. Unlike the pay RPC command
       the keysend command does	not require an invoice,	instead	 it  uses  the
       destination node	ID, and	amount to find a route to the specified	node.

       In  order for the destination to	be able	to claim the payment, the pay-
       ment_key	is randomly generated by the sender and	included  in  the  en-
       crypted	payload	 for  the  destination.	 As a consequence there	is not
       proof-of-payment, like there is with an invoice where  the  payment_key
       is  generated on	the destination, and the only way sender could have it
       is by sending a payment.	Please ensure that this	matches	your  use-case
       when using keysend.

       destination  is	the 33 byte, hex-encoded, node ID of the node that the
       payment should go to.  msatoshi is in millisatoshi precision; it	can be
       a  whole	 number, or a whole number with	suffix msat or sat, or a three
       decimal point number with suffix	sat, or	an 1 to	11 decimal point  num-
       ber suffixed by btc.

       The  label field	is used	to attach a label to payments, and is returned
       in lightning-listpays(7)	and lightning-listsendpays(7).	The maxfeeper-
       cent  limits  the  money	paid in	fees as	percentage of the total	amount
       that is to be transferred, and defaults to 0.5.	The  exemptfee	option
       can  be	used  for  tiny	 payments  which would be dominated by the fee
       leveraged by forwarding nodes.  Setting exemptfee allows	the maxfeeper-
       cent  check  to be skipped on fees that are smaller than	exemptfee (de-
       fault: 5000 millisatoshi).

       The response will occur when the	payment	 fails	or  succeeds.	Unlike
       lightning-pay(7), issuing the same keysend commands multiple times will
       result in multiple payments being sent.

       Until retry_for seconds passes (default:	60),  the  command  will  keep
       finding routes and retrying the payment.	 However, a payment may	be de-
       layed for up to maxdelay	blocks by another node;	clients	should be pre-
       pared for this worst case.

       When  using  lightning-cli,  you	 may skip optional parameters by using
       null. Alternatively, use	-k option to provide parameters	by name.

       To protect user privacy,	the payment algorithm performs some randomiza-

       1: Route	Randomization

       Route randomization means the payment algorithm does not	always use the
       lowest-fee or shortest route. This prevents some	highly-connected  node
       from learning all of the	user payments by reducing their	fees below the
       network average.

       2: Shadow Route

       Shadow route means the payment  algorithm  will	virtually  extend  the
       route  by adding	delays and fees	along it, making it appear to interme-
       diate nodes that	the route is longer than it actually is. This prevents
       intermediate  nodes  from  reliably  guessing  their  distance from the

       Route randomization will	never exceed  maxfeepercent  of	 the  payment.
       Route  randomization and	shadow routing will not	take routes that would
       exceed maxdelay.

       On success, keysend will	return a number	of internal statistics and de-
       tails of	the attempts to	reach the destination.

       You  can	monitor	the progress and retries of a payment using the	light-
       ning-paystatus(7) command.

       The following error codes may occur:

	      o	     -1: Catchall nonspecific error.

	      o	     203: Permanent failure at destination. The	data field  of
		     the error will be routing failure object.

	      o	     205: Unable to find a route.

	      o	     206:  Route  too  expensive. Either the fee or the	needed
		     total locktime for	the route exceeds  your	 maxfeepercent
		     or	maxdelay settings, respectively. The data field	of the
		     error will	indicate the actual fee	as well	as the feeper-
		     cent  percentage that the fee has of the destination pay-
		     ment amount. It will also indicate	the actual delay along
		     the route.

	      o	     210: Payment timed	out without a payment in progress.

       A routing failure object	has the	fields below:

	      o	     erring_index:  The	index of the node along	the route that
		     reported the error. 0 for the local node, 1 for the first
		     hop, and so on.

	      o	     erring_node:  The hex string of the pubkey	id of the node
		     that reported the error.

	      o	     erring_channel: The short channel ID of the channel  that
		     has  the  error,  or 0:0:0	if the destination node	raised
		     the error.

	      o	     failcode: The failure code, as per	BOLT #4.

	      o	     channel_update. The hex string of the channel_update mes-
		     sage 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.

       Christian Decker> is mainly responsible.

       lightning-listpays(7),	  lightning-decodepay(7),    lightning-listin-
       voice(7), lightning-delinvoice(7), lightning-getroute(7), lightning-in-

       Main web	site:



Want to link to this manual page? Use this URL:

home | help