NAME

lightning-xpay -- Command for sending a payment for an invoice

SYNOPSIS

xpay invstring [amount_msat] [maxfee] [layers] [retry_for] [partial_msat] [maxdelay]

DESCRIPTION

The xpay RPC command attempts to find routes to the given destination, and send the funds it asks for.

This plugin is simpler and more sophisticated than the older 'pay' plugin, but does not have all the same features.

• invstring (string): bolt11 or bolt12 invoice

• 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 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 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 additional information on the lightning network. See askrene-create-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)

RETURN VALUE

On success, an object is returned, containing:

• payment_preimage (secret): The proof of payment: SHA256 of this payment_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 recognize 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-pay(7), lightning-decodepay(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"

{


  "id": "example:xpay#2",


  "method": "xpay",


  "params": {


    "invstring": "lni1qqg0qe03030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303"


  }
}

Response:

{


  "payment_preimage": "paymentpreimgxp2020202020202020202020202020202020202020202020202",


  "amount_msat": 1000,


  "amount_sent_msat": 1000,


  "failed_parts": 0,


  "successful_parts": 1
}