LIGHTNING-XPAY(7)

📦
version 26.06.9 · 2 versions
, in nixpkgs unstable

okay so you just opened lightning-xpay(7) and honestly? bestie, you picked a good one. this is the xpay command from Core Lightning, and it's about to send a payment for you. buckle up. 🎀

🌸 NAME 🌸

xpay — Command for sending a payment. that's it. that's the whole gig. it sends money. iconic behavior. 💸

✨ SYNOPSIS ✨

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

💅 DESCRIPTION 💅

Command added in v24.11. yes, she's new-ish, and yes, she's already that girl. 👑

The xpay RPC command attempts to make the specified payment. it's flexible like that — it can look up BIP353 names (such as ₿rusty@blockstream.com, which is genuinely adorable), it can resolve simple offers (lno1...), and it can pay bolt11 (lnbc...) and bolt12 invoices (lni1...). one command, all the invoice flavors. we love a multitasker. 🌈

This plugin is both simpler and more sophisticated than the older pay plugin. both things can be true at once, that's called range. 🦋

  • 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. she does the legwork so you don't have to. 🫶
  • 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. numbers, but make it fashion. 🔥
  • maxfee (msat, optional) — maxfee creates an absolute limit on what fee we will pay. The default is 5000msat, or 1% (whatever is greater). no getting fleeced on your watch. 🚫
  • 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. she's persistent, not clingy. 😭
  • 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). squad mode activated. 🤝
  • 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) say something nice!! 💌
  • 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. your little secret, no cap. 🙈 (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. iykyk. 🔑
  • 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. periodt. 💅
  • amount_msat (msat) — Amount the recipient received. 🍓
  • amount_sent_msat (msat) — Total amount we sent (including fees). the fees are part of the vibe, unfortunately. 😮‍💨

💀 ERRORS 💀

The following error codes may occur:

  • -1 — Catchall nonspecific error. the "something happened" of errors. 🌫️
  • 203 — Permanent failure from destination (e.g. it said it didn't recognize invoice). they literally don't know her. 😤
  • 205 — Couldn't find, or find a way to, the destination. she's lost in the graph. 🗺️
  • 207 — Invoice has expired. too late bestie, should've paid sooner. ⌛
  • 219 — Invoice has already been paid. someone ate already. 🍽️
  • 209 — Other payment error. the miscellaneous queen. 👑

🌟 AUTHOR 🌟

Rusty Russell rusty@rustcorp.com.au is mainly responsible. main character energy, honestly. 🫡

🦋 SEE ALSO 🦋

🌈 RESOURCES 🌈

Main web site: https://github.com/ElementsProject/lightning — go look, she's gorgeous. ⭐

🧚 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"="lni1qqg0qe03030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303" "payer_note"="Coffee payment"

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

Response:

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

and that's the whole page, bestie. this gorgeous thing is from Core Lightning v26.06.9 and it lives at LIGHTNING-XPAY(7). go pay someone. slay. 💅✨🫶

📦 where this page comes from