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

FreeBSD Manual Pages


home | help
LIGHTNING-PAY(7)		 lightning-pay		      LIGHTNING-PAY(7)

       lightning-pay - Command for sending a payment to	a BOLT11 invoice

       pay  bolt11 [msatoshi] [label] [riskfactor] [maxfeepercent] [retry_for]
       [maxdelay] [exemptfee]

       The pay RPC command attempts to find a route to the given  destination,
       and  send  the  funds  it  asks	for. If	the bolt11 does	not contain an
       amount, msatoshi	is required, otherwise if it is	specified it  must  be
       null.  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 number suffixed by

       (Note: if experimental-offers is	enabled,  bolt11  can  actually	 be  a
       bolt12 invoice, such as one received from lightningd-fetchinvoice(7)).

       The  label field	is used	to attach a label to payments, and is returned
       in lightning-listpays(7)	and lightning-listsendpays(7). The  riskfactor
       is  described  in  detail in lightning-getroute(7), and defaults	to 10.
       The maxfeepercent limits	the money paid in fees,	and defaults  to  0.5.
       The maxfeepercent is a percentage of the	amount that is to be paid. The
       exemptfee option	can be used for	tiny payments which would be dominated
       by  the fee leveraged by	forwarding nodes. Setting exemptfee allows the
       maxfeepercent check to be skipped on fees that are smaller than exempt-
       fee (default: 5000 millisatoshi).

       The response will occur when the	payment	fails or succeeds. Once	a pay-
       ment has	succeeded, calls to pay	with the same bolt11 will succeed  im-

       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, this returns the payment_preimage which hashes to the pay-
       ment_hash to prove that the payment was successful. It  will  also  re-
       turn, a getroute_tries and a sendpay_tries statistics for the number of
       times it	internally called getroute and sendpay.

       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	     201:  Already  paid with this hash	using different	amount
		     or	destination.

	      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	     207:  Invoice expired. Payment took too long before expi-
		     ration, or	already	expired	at the time you	initiated pay-
		     ment. The data field of the error indicates now (the cur-
		     rent time)	and expiry (the	invoice	 expiration)  as  UNIX
		     epoch time	in seconds.

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

       Error  codes  202  and 204 will only get	reported at sendpay; in	pay we
       will keep retrying if we	would have gotten those	errors.

       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.

       The data	field of errors	will  include  statistics  getroute_tries  and
       sendpay_tries. It will also contain a failures field with detailed data
       about routing errors.

       Rusty Russell> 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