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

NAME
     xpay -- Command for sending a payment

SYNOPSIS
     xpay  invstring  [amount_msat] [maxfee] [layers] [retry_for] [partial_msat]
     [maxdelay] [payer_note] [label] [localinvreqid]

DESCRIPTION
     Command added in v24.11.

     The xpay RPC command attempts to make the specified payment: it can look up
     BIP353 names (such as a?rusty@blockstream.com), it can resolve  simple  of-
     fers (lno1...), and pay bolt11 (lnbc...) and bolt12 invoices (lni1...).

     This  plugin  is  both  simpler and more sophisticated than the older 'pay'
     plugin.

     *	invstring (string): bolt11 or bolt12 invoice, a  bolt12  (non-recursive)
	offer or a BIP353 name.  If it's a bip353 name, an offer is fetched with
	fetchbip353  if available.  If it's an offer, the invoice is fetched us-
	ing fetchinvoice automatically.
     *	amount_msat (msat, optional): Only possible for a bolt11  invoice  which
	does  not  have an amount (in which case, it's compulsory).  amount_msat
	is in millisatoshi precision; it can be a whole number, or a whole  num-
	ber with suffix msat or sat, or a three decimal point number with suffix
	sat, or an 1 to 11 decimal point number suffixed by btc.
     *	maxfee (msat, optional): maxfee creates an absolute limit on what fee we
	will pay. The default is 5000msat, or 1% (whatever is greater).
     *	layers	(array	of strings, optional): These are askrene layers to apply
	in addition to xpay's own: these can alter the topology or provide addi-
	tional information on the lightning network.  This lets you exclude par-
	ticular nodes or channels, or bias  against  them:  see  askrene-create-
	layer.:
	*  (string, optional): name of an existing layer
     *	retry_for  (u32,  optional): Until retry_for seconds passes, the command
	will keep finding routes and retrying the payment.  The  default  is  60
	seconds.
     *	partial_msat (msat, optional): Explicitly state that you are only paying
	some  part  of	the invoice.  Presumably someone else is paying the rest
	(otherwise the payment will time out at the recipient).
     *	maxdelay (u32, optional): A payment may be delayed for	up  to	maxdelay
	blocks	by another node; clients should be prepared for this worst case.
	The default is 2016. (added v25.02)
     *	payer_note (string, optional): A message that a payer is willing to send
	to a payee within an invoice request. (added v26.04)
     *	label (string, optional): Attach a label to payments for  which  is  re-
	turned	in  listpays  and listsendpays.  This is for your own use: it is
	not visible to the recipient. (added v26.06)
     *	localinvreqid (hex, optional): localinvreqid is used by offers to link a
	payment attempt to a local invoice_request offer created by  lightningd-
	invoicerequest(7).  This  ensures that we only make a single payment for
	an offer, and that the offer is marked used once paid. (added v26.06)

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

     *	payment_preimage (secret): The proof of payment:  SHA256  of  this  pay-
	ment_hash.
     *	failed_parts (u64): How many separate payment parts failed.
     *	successful_parts  (u64):  How  many separate payment parts succeeded (or
	are anticipated to succeed).  This will be at least one.
     *	amount_msat (msat): Amount the recipient received.
     *	amount_sent_msat (msat): Total amount we sent (including fees).

ERRORS
     The following error codes may occur:

     *	-1: Catchall nonspecific error.
     *	203: Permanent failure from destination (e.g. it said it  didn't  recog-
	nize invoice)
     *	205: Couldn't find, or find a way to, the destination.
     *	207: Invoice has expired.
     *	219: Invoice has already been paid.
     *	209: Other payment error.

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

SEE ALSO
     lightning-listpays(7), lightning-decode(7)

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

EXAMPLES
     Example 1:

     Request:

     $ lightning-cli xpay "lnbcrt100n1pnt2bolt11invl040100000000bolt11invl040100000000bolt11invl040100000000bolt11invl040100000000bolt11invl040100000000bolt11invl040100000000bolt11invl040100000000bolt11invl040100000000bolt11invl040100000000bolt11invl040100000000"

     {
       "id": "example:xpay#1",
       "method": "xpay",
       "params": [
	 "lnbcrt100n1pnt2bolt11invl040100000000bolt11invl040100000000bolt11invl040100000000bolt11invl040100000000bolt11invl040100000000bolt11invl040100000000bolt11invl040100000000bolt11invl040100000000bolt11invl040100000000bolt11invl040100000000"
       ]
     }

     Response:

     {
       "payment_preimage": "paymentpreimgxp1010101010101010101010101010101010101010101010101",
       "amount_msat": 10000,
       "amount_sent_msat": 10002,
       "failed_parts": 0,
       "successful_parts": 1
     }

     Example 2:

     Request:

     $ lightning-cli xpay -k "invstring"="lni1qqg0qe03030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303" "payer_note"="Coffee payment"

     {
       "id": "example:xpay#2",
       "method": "xpay",
       "params": {
	 "invstring": "lni1qqg0qe03030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303",
	 "payer_note": "Coffee payment"
       }
     }

     Response:

     {
       "payment_preimage": "paymentpreimgxp2020202020202020202020202020202020202020202020202",
       "amount_msat": 1000,
       "amount_sent_msat": 1000,
       "failed_parts": 0,
       "successful_parts": 1
     }

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