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 ₿[email protected]), 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
fetchbip353if available. If it's an offer, the invoice is fetched usingfetchinvoiceautomatically. - 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
maxdelayblocks 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
listpaysandlistsendpays. This is for your own use: it is not visible to the recipient. (added v26.06) - localinvreqid (hex, optional):
localinvreqidis used by offers to link a payment attempt to a localinvoice_requestoffer created by lightningd-invoicerequest(7). This ensures that we only make a single payment for an offer, and that the offer is markedusedonce 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 [email protected] 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 "lnbcrt100n1pne035qsp54v5a0x3w0r3mjdnhe8fz2cugz0pqanee8rdep0sszpg3zyxvvwxqpp5ulnc8tpdywe6dh23xh2l83j3qw3ghl2x7rytl5lvza58k42mkeesdp9w3jhxazl0pcxz72lwd5k6urvv5sxymmvwscnzxqyjw5qcqp9rzjq08vhlwxs4zvcktzywmgecr3pj096tyukvt7upuz9k2s0xkvwq7nzqqq0qqqqqgqqqqqqqqpqqqqqzsqqc9qxpqysgqtquasyh7spka4ayjvawr6awq0f47h4zmz9zgm75s6xd22vq5ngsy73gjqszr3leq7j9hr27fserwxh8w4hqfxk3qawhpxexgjhmwt9qpqkmhat"{
"id": "example:xpay#1",
"method": "xpay",
"params": [
"lnbcrt100n1pne035qsp54v5a0x3w0r3mjdnhe8fz2cugz0pqanee8rdep0sszpg3zyxvvwxqpp5ulnc8tpdywe6dh23xh2l83j3qw3ghl2x7rytl5lvza58k42mkeesdp9w3jhxazl0pcxz72lwd5k6urvv5sxymmvwscnzxqyjw5qcqp9rzjq08vhlwxs4zvcktzywmgecr3pj096tyukvt7upuz9k2s0xkvwq7nzqqq0qqqqqgqqqqqqqqpqqqqqzsqqc9qxpqysgqtquasyh7spka4ayjvawr6awq0f47h4zmz9zgm75s6xd22vq5ngsy73gjqszr3leq7j9hr27fserwxh8w4hqfxk3qawhpxexgjhmwt9qpqkmhat"
]
}Response:
{
"payment_preimage": "5dd460dcbf1508705dd460dcbf1508705dd460dcbf1508705dd460dcbf150870",
"amount_msat": 10000,
"amount_sent_msat": 10002,
"failed_parts": 0,
"successful_parts": 1
}Example 2:
Request:
lightning-cli xpay -k "invstring"="lni1qqgvzkzz5jrhmdd0c9vy9fy80k667q3qqc3xu3s3rg94nj40zfsy866mhu5vxne6tcej5878k2mneuvgjy83pmsr8pzcqtf9kns8fn8a0nvtxwdyrhr4h7vh3gp5sqzyfdgag2c80xdq9suvcgw0ak2nh6cfxctfaxlfqv2j6dxypj76nt4jqdxyxaghf60kqgp95yw73zw4mx4y9x5y8rgqklrrawg5wpgts0ds4d3zrer77dujk3cqxwl6p5xkg8gf52vy2krjk3qy0dhemyhaksl7um6twxj6z8jya95pqmw30ryplhasydxkuxk9nr8gf92e2rms9lvtz4xyrufjpf7pfkrscaffkr5pghzsxgqfq8d2vuwxy3ezxujgqqerr0780hu3rttqw9xw86q7cdazyx4lsv8er3kz04phkfnryecqhgg0r2sdsymull88w0dv9tux7a48tk8pvggrsx2ttuetmu92txqjepkyaaad9u55zp86qf734n5mg6dmd7yv7da4qgqxyfhyvyg6pdvu4tcjvpp7kkal9rp57wj7xv4pl3ajku70rzy3pafqyqlg2sq9sggrg4456065qg26pfm5leyrjuxu5afjhw8a22g3csgyml8pvqhh4xt6pxqrsx2ttuetmu92txqjepkyaaad9u55zp86qf734n5mg6dmd7yv7dasxy7wjuavm7474t7690qx5h5kzn5f9ywfvrqu02dg3kycneq8tatzqyptztevlxahrqt54dq0k9qe587yuuka27d5u00226p9xg3ksng5xngqxt68v6474rcnve4qdzd6264qsxspa9jvxrpud6djpz3mdtnm6qj6ske9w02t8ajsxvnya5edtukyxw4gdz3pcqqqqqqqqqqqqqqq2qqqqqqqqqqqqqwjfvkl43fqqqqqqzjqgeuhc6q2sgy6wttfekcsyx7v8ztcqqlzkzvs6qkhjl5suyw0n44tyg8vx9y6y64qyqlg4cpsyqqqkqss8qv5khejhhc25kvp9jrvfmm66tefgyz05qnart8fk35mkmugeumm7pqxu3dsad7ve5j37g30mkpcspnx90z5gq07kpm9ne5t92g9smua8z98j8lyyx4jtmr2q9379708sasd3vf60ue5ezyuka9x29jdxx6m5u"{
"id": "example:xpay#2",
"method": "xpay",
"params": {
"invstring": "lni1qqgvzkzz5jrhmdd0c9vy9fy80k667q3qqc3xu3s3rg94nj40zfsy866mhu5vxne6tcej5878k2mneuvgjy83pmsr8pzcqtf9kns8fn8a0nvtxwdyrhr4h7vh3gp5sqzyfdgag2c80xdq9suvcgw0ak2nh6cfxctfaxlfqv2j6dxypj76nt4jqdxyxaghf60kqgp95yw73zw4mx4y9x5y8rgqklrrawg5wpgts0ds4d3zrer77dujk3cqxwl6p5xkg8gf52vy2krjk3qy0dhemyhaksl7um6twxj6z8jya95pqmw30ryplhasydxkuxk9nr8gf92e2rms9lvtz4xyrufjpf7pfkrscaffkr5pghzsxgqfq8d2vuwxy3ezxujgqqerr0780hu3rttqw9xw86q7cdazyx4lsv8er3kz04phkfnryecqhgg0r2sdsymull88w0dv9tux7a48tk8pvggrsx2ttuetmu92txqjepkyaaad9u55zp86qf734n5mg6dmd7yv7da4qgqxyfhyvyg6pdvu4tcjvpp7kkal9rp57wj7xv4pl3ajku70rzy3pafqyqlg2sq9sggrg4456065qg26pfm5leyrjuxu5afjhw8a22g3csgyml8pvqhh4xt6pxqrsx2ttuetmu92txqjepkyaaad9u55zp86qf734n5mg6dmd7yv7dasxy7wjuavm7474t7690qx5h5kzn5f9ywfvrqu02dg3kycneq8tatzqyptztevlxahrqt54dq0k9qe587yuuka27d5u00226p9xg3ksng5xngqxt68v6474rcnve4qdzd6264qsxspa9jvxrpud6djpz3mdtnm6qj6ske9w02t8ajsxvnya5edtukyxw4gdz3pcqqqqqqqqqqqqqqq2qqqqqqqqqqqqqwjfvkl43fqqqqqqzjqgeuhc6q2sgy6wttfekcsyx7v8ztcqqlzkzvs6qkhjl5suyw0n44tyg8vx9y6y64qyqlg4cpsyqqqkqss8qv5khejhhc25kvp9jrvfmm66tefgyz05qnart8fk35mkmugeumm7pqxu3dsad7ve5j37g30mkpcspnx90z5gq07kpm9ne5t92g9smua8z98j8lyyx4jtmr2q9379708sasd3vf60ue5ezyuka9x29jdxx6m5u"
}
}Response:
{
"payment_preimage": "c15842a4877dc166c15842a4877dc166c15842a4877dc166c15842a4877dc166",
"amount_msat": 1000,
"amount_sent_msat": 1000,
"failed_parts": 0,
"successful_parts": 1
}