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 ₿rusty@blockstream.com), it can resolve simple offers (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 using 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 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. This lets you exclude particular 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 returned 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 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-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
}