lightning-xpay

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

SYNOPSIS

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

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).

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",
  "failed_parts": 0,
  "successful_parts": 1,
  "amount_msat": 10000,
  "amount_sent_msat": 10002
}

Example 2:

Request:

lightning-cli xpay -k "invstring"="lni1qqg0qe03030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303"
{
  "id": "example:xpay#2",
  "method": "xpay",
  "params": {
    "invstring": "lni1qqg0qe03030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303"
  }
}

Response:

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

Core Lightning (previously c-lightning) is a lightweight, highly customizable and standard compliant implementation of the Lightning Network protocol.

© 2023 Core Lightning
All rights reserved.

Discussion Forum

The official Core Lightning forum is hosted at discuss.corelightning.org

BuildonL2 Community

The official BuildOnL2 community lives at community.corelightning.org. Join us and build the future of bitcoin on lightning.

Mailing List

For general discussions about CLN implementation, use [email protected]. For the Lightning Network, use [email protected]

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/w27fMFESMN to join.

Internet Relay Chat

Don't hesitate to reach out to us on IRC at #lightning-dev @ libera.chat, #c-lightning @ libera.chat.