FreeBSD Manual Pages
LIGHTNING-SENDPAY(7) LIGHTNING-SENDPAY(7) NAME lightning-sendpay -- Low-level command for sending a payment via a route SYNOPSIS sendpay route payment_hash [label] [amount_msat] [bolt11] [payment_se- cret] [partid] [localinvreqid] [groupid] [payment_metadata] [descrip- tion] DESCRIPTION The sendpay RPC command attempts to send funds associated with the given payment_hash, along a route to the final destination in the route. Generally, a client would call lightning-getroute(7) to resolve a route, then use sendpay to send it. If it fails, it would call light- ning-getroute(7) again to retry. If the route is empty, a payment-to- self is attempted. The response will occur when the payment is on its way to the destina- tion. The sendpay RPC command does not wait for definite success or definite failure of the payment (except for already-succeeded payments, or to-self payments). Instead, use the waitsendpay RPC command to poll or wait for definite success or definite failure. Once a payment has succeeded, calls to sendpay with the same pay- ment_hash but a different amount_msat or destination will fail; this prevents accidental multiple payments. Calls to sendpay with the same payment_hash, amount_msat, and destination as a previous successful payment (even if a different route or partid) will return immediately with success. • route (array of objects): • id (pubkey): The node at the end of this hop. • channel (short_channel_id): The channel joining these nodes. • delay (u32): The total CLTV expected by the node at the end of this hop. • amount_msat (msat): The amount expected by the node at the end of this hop. • payment_hash (hash): The hash of the payment_preimage. • label (string, optional): The label provided when creating the in- voice_request. • amount_msat (msat, optional): Amount must be provided if partid is non-zero, or the payment is to-self, otherwise it must be equal to the final amount to the destination. it can be a whole number, or a whole number ending in msat or sat, or a number with three decimal places ending in sat, or a number with 1 to 11 decimal places ending in btc. The default is in millisatoshi precision. • bolt11 (string, optional): Bolt11 invoice to pay. If provided, will be returned in waitsendpay and listsendpays results. • payment_secret (secret, optional): Value that the final recipient requires to accept the payment, as defined by the payment_data field in BOLT 4 and the s field in the BOLT 11 invoice format. It is re- quired if partid is non-zero. • partid (u64, optional): Must not be provided for self-payments. If provided and non-zero, allows for multiple parallel partial payments with the same payment_hash. The amount_msat amount (which must be provided) for each sendpay with matching payment_hash must be equal, and sendpay will fail if there are differing values given. • localinvreqid (hex, optional): Indicates that this payment is being made for a local invoice_request. This ensures that we only send a payment for a single-use invoice_request once. • groupid (u64, optional): Allows you to attach a number which appears in listsendpays so payments can be identified as part of a logical group. The pay plugin uses this to identify one attempt at a MPP payment, for example. • payment_metadata (hex, optional): Placed in the final onion hop TLV. (added v0.11.0) • description (string, optional): Description used in the invoice. (added v0.11.0) RETURN VALUE On success, an object is returned, containing: • created_index (u64): 1-based index indicating order this payment was created in. (added v23.11) • id (u64): Old synonym for created_index. • payment_hash (hash): The hash of the payment_preimage which will prove payment. • status (string) (one of "pending", "complete"): Status of the pay- ment (could be complete if already sent previously). • created_at (u64): The UNIX timestamp showing when this payment was initiated. • amount_sent_msat (msat): The amount sent. • updated_index (u64, optional): 1-based index indicating order this payment was changed (only present if it has changed since creation). (added v23.11) • groupid (u64, optional): Grouping key to disambiguate multiple at- tempts to pay an invoice or the same payment_hash. • amount_msat (msat, optional): The amount delivered to destination (if known). • destination (pubkey, optional): The final destination of the payment if known. • completed_at (u64, optional): The UNIX timestamp showing when this payment was completed. • label (string, optional): The label, if given to sendpay. • partid (u64, optional): The partid, if given to sendpay. • bolt11 (string, optional): The bolt11 string (if supplied). • bolt12 (string, optional): The bolt12 string (if supplied). If status is "complete": - payment_preimage (secret): The proof of pay- ment: SHA256 of this payment_hash. If status is "pending": - message (string): Monitor status with list- pays or waitsendpay. ERRORS On error, if the error occurred from a node other than the final desti- nation, the route table will be updated so that lightning-getroute(7) should return an alternate route (if any). An error from the final des- tination implies the payment should not be retried. • -1: Catchall nonspecific error. • 201: Already paid with this hash using different amount or destina- tion. • 202: Unparseable onion reply. The data field of the error will have an onionreply field, a hex string representation of the raw onion reply. • 203: Permanent failure at destination. The data field of the error will be routing failure object. • 204: Failure along route; retry a different route. The data field of the error will be routing failure object. • 212: localinvreqid refers to an invalid, or used, local invoice_re- quest. A routing failure object has the fields below: erring_index: The index of the node along the route that reported the error. 0 for the local node, 1 for the first hop, and so on. erring_node: The hex string of the pubkey id of the node that reported the error. erring_channel: The short channel ID of the channel that has the error, or 0:0:0 if the destination node raised the error. In addition erring_direction will indicate which direction of the channel caused the failure. failcode: The failure code, as per BOLT #4. chan- nel_update: The hex string of the channel_update message received from the remote node. Only present if error is from the remote node and the failcode has the UPDATE bit set, as per BOLT #4. AUTHOR Rusty Russell <<rusty@rustcorp.com.au>> is mainly responsible. SEE ALSO lightning-listinvoices(7), lightning-delinvoice(7), lightning- getroute(7), lightning-invoice(7), lightning-pay(7), lightning-wait- sendpay(7) RESOURCES Main web site: <https://github.com/ElementsProject/lightning> EXAMPLES Example 1: Request: $ lightning-cli sendpay -k "route"='[{"id": "nodeid020202020202020202020202020202020202020202020202020202020202", "channel": "109x1x1", "direction": 1, "amount_msat": 10001, "delay": 15, "style": "tlv"}, {"id": "nodeid030303030303030303030303030303030303030303030303030303030303", "channel": "111x1x1", "direction": 0, "amount_msat": 10000, "delay": 9, "style": "tlv"}]' "payment_hash"="paymenthashinvl0310031003100310031003100310031003100310031003100" "payment_secret"="paymentsecretinvl00310003100031000310003100031000310003100031000" { "id": "example:sendpay#1", "method": "sendpay", "params": { "route": [ { "id": "nodeid020202020202020202020202020202020202020202020202020202020202", "channel": "109x1x1", "direction": 1, "amount_msat": 10001, "delay": 15, "style": "tlv" }, { "id": "nodeid030303030303030303030303030303030303030303030303030303030303", "channel": "111x1x1", "direction": 0, "amount_msat": 10000, "delay": 9, "style": "tlv" } ], "payment_hash": "paymenthashinvl0310031003100310031003100310031003100310031003100", "payment_secret": "paymentsecretinvl00310003100031000310003100031000310003100031000" } } Response: { "message": "Monitor status with listpays or waitsendpay", "created_index": 2, "id": 2, "payment_hash": "paymenthashinvl0310031003100310031003100310031003100310031003100", "groupid": 1, "destination": "nodeid030303030303030303030303030303030303030303030303030303030303", "amount_msat": 10000, "amount_sent_msat": 10001, "created_at": 1738000000, "status": "pending" } Core Lightning v25.02 LIGHTNING-SENDPAY(7)
NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | AUTHOR | SEE ALSO | RESOURCES | EXAMPLES
Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=lightning-sendpay&sektion=7&manpath=FreeBSD+Ports+14.3.quarterly>