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

       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