LIGHTNING-GETROUTES(7) LIGHTNING-GETROUTES(7) NAME getroutes -- Command for routing a payment SYNOPSIS getroutes source destination amount_msat layers maxfee_msat final_cltv [maxdelay] [maxparts] DESCRIPTION Command added in v24.08. The getroutes RPC command attempts to find the best set of paths for the payment from source to destination of amount_msat, using the given layers on top of the gossip information. The result is constrained by maxfee, and will arrive at the destination with final_cltv. NOTE: The returned paths are a different format then getroute, being more appropriate for creating intermediary onion layers. Layers are generally maintained by plugins, either to contain persistent information about capacities which have been discovered, or to contain transient information for this particular payment (such as blinded paths or routehints). There are some automatic layers: auto.localchans contains information on local channels from this node (including non-public ones), and their exact current spendable capacities. auto.sourcefree overrides all channels (in- cluding those from previous layers) leading out of the source to be zero fee and zero delay. These are both useful in the case where the source is the current node. auto.include_fees that fixes the send amount and deducts fee from there, ie. the receiver pays for fees instead of the sender. auto.no_mpp_support is deprecated in v26.06: use maxparts=1 instead. * source (pubkey): Node pubkey to start the paths * destination (pubkey): Node pubkey to end the paths * amount_msat (msat): Amount to send. It can be a whole number, or a whole number ending in msat or sat, or a number with three decimal places end- ing in sat, or a number with 1 to 11 decimal places ending in btc. * layers (array of strings): * (string, optional): Layer to apply to the gossip map before attempt- ing to find routes. * maxfee_msat (msat): Maximum fee to spend: we will never return a set of routes more expensive than this. It can be a whole number, or a whole number ending in msat or sat, or a number with three decimal places end- ing in sat, or a number with 1 to 11 decimal places ending in btc. * final_cltv (u32): Number of blocks for the final node. We need to know this because no HTLC is allowed to have a CLTV delay more than 2016 blocks. * maxdelay (u32, optional): Maximum number of blocks of delay for the route. Cannot be bigger than 2016. The default is 2016. (added v25.02) * maxparts (u32, optional): Maximum number of routes in the solution. The default is 100. (added v25.09) RETURN VALUE On success, an object is returned, containing: * probability_ppm (u64): The estimated probability of success using these routes, in millionths. * routes (array of objects): * probability_ppm (u64): The estimated probability of success using this route, in millionths. * amount_msat (msat): The amount delivered to the destination by this path. * final_cltv (u32): Number of blocks required by the final node (set by caller) * path (array of objects): The hops to get from source to destination.: * short_channel_id_dir (short_channel_id_dir): The channel and direc- tion joining these nodes. * amount_in_msat (msat): The amount to send into this hop. (added v26.06) * amount_out_msat (msat): The amount which arrives at the far end of this hop. (added v26.06) * node_id_in (pubkey): The peer id at the start of this hop. (added v26.06) * node_id_out (pubkey): The peer id at the end of this hop. (added v26.06) * cltv_in (u32): The total CLTV expected by the node at the start of this hop. (added v26.06) * cltv_out (u32): The total CLTV expected by the node at the end of this hop. (added v26.06) * amount_msat (msat, optional): The amount to send into this hop. dep- recated in v26.06, removed after v27.06 * next_node_id (pubkey, optional): The peer id at the end of this hop. deprecated in v26.06, removed after v27.06 * delay (u32, optional): The total CLTV expected by the node at the start of this hop. deprecated in v26.06, removed after v27.06 ERRORS The following error codes may occur: * -1: Catchall nonspecific error. * 205: Unable to find a route. * 206: Route too expensive. Either the max_delay or maxfee_msat was ex- ceeded. AUTHOR lagrang3@protonmail.com wrote the minimum-cost-flow solver, Rusty Russell rusty@rustcorp.com.au wrote the API and this documentation. SEE ALSO lightning-askrene-reserve(7), lightning-askrene-unreserve(7), lightning- askrene-disable-node(7), lightning-askrene-create-channel(7), lightning- askrene-inform-channel(7), lightning-askrene-report(7), lightning-askrene- age(7) RESOURCES Main web site: https://github.com/ElementsProject/lightning EXAMPLES Example 1: Request: $ lightning-cli getroutes -k "source"="nodeid010101010101010101010101010101010101010101010101010101010101" "destination"="nodeid030303030303030303030303030303030303030303030303030303030303" "amount_msat"=1250000 "layers"='[]' "maxfee_msat"=125000 "final_cltv"=0 { "id": "example:getroutes#1", "method": "getroutes", "params": { "source": "nodeid010101010101010101010101010101010101010101010101010101010101", "destination": "nodeid030303030303030303030303030303030303030303030303030303030303", "amount_msat": 1250000, "layers": [], "maxfee_msat": 125000, "final_cltv": 0 } } Response: { "probability_ppm": 997501, "routes": [ { "probability_ppm": 997501, "amount_msat": 1250000, "final_cltv": 0, "path": [ { "short_channel_id_dir": "109x1x1/1", "next_node_id": "nodeid020202020202020202020202020202020202020202020202020202020202", "amount_msat": 1250026, "delay": 12 }, { "short_channel_id_dir": "123x1x1/0", "next_node_id": "nodeid030303030303030303030303030303030303030303030303030303030303", "amount_msat": 1250013, "delay": 6 } ] } ] } Core Lightning v26.06.1 LIGHTNING-GETROUTES(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-getroutes&sektion=7&manpath=FreeBSD+Ports+15.1.quarterly>