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 (including 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 ending 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 attempting 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 ending 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 direction 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. deprecated 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 exceeded.

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
        }
      ]
    }
  ]
}