xpay

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.:
    • (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)

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 <[email protected]> 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
}

Core Lightning is Blockstream's open-source implementation of the Lightning Network optimised for performance. It is highly customizable through modular expandability.

© 2023 Core Lightning
All rights reserved.

X Twitter Logo Streamline Icon: https://streamlinehq.com

X

The official Core Lightning X(Twitter) handle to follow project updates and announcements.

Github Logo 2 Streamline Icon: https://streamlinehq.com

Github

Github repository for source code, issues, and contributions. Visit our project here to explore or contibute.

Telegram

Community-driven telegram group where most of the node operators hang out. Go to https://t.me/lightningd to join.

Discord

Community-driven discord server where the devs flock together. Go to https://discord.gg/V6ay9yNhBQ to join.