"title":"Command for routing a payment (low-level)",
"description":[
"The **getroute** RPC command attempts to find the best route for the payment of *amount_msat* to lightning node *id*, such that the payment will arrive at *id* with *cltv*.",
"",
"There are two considerations for how good a route is: how low the fees are, and how long your payment will get stuck in a delayed output if a node goes down during the process. ."
"Node pubkey to find the best route for the payment."
]
},
"amount_msat":{
"type":"msat",
"description":[
"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*. The 0 value is special: it ignores any *htlc_minimum_msat* setting on channels, and simply returns a possible route (if any) which is useful for simple probing."
]
},
"riskfactor":{
"type":"u64",
"description":[
"A non-negative floating-point field controls this tradeoff; it is the annual cost of your funds being stuck (as a percentage). For example, if you thought the convenience of keeping your funds liquid (not stuck) was worth 20% per annum interest, *riskfactor* would be 20. If you didn't care about risk, *riskfactor* would be zero."
]
},
"cltv":{
"type":"u32",
"description":[
"Cltv-blocks to spare."
],
"default":"9"
},
"fromid":{
"type":"pubkey",
"description":[
"The node to start the route from."
],
"default":"this node"
},
"fuzzpercent":{
"type":"u32",
"description":[
"Used to distort fees to provide some randomization to the route generated, but it was not properly implemented and is ignored."
]
},
"exclude":{
"type":"array",
"description":[
"A JSON array of short-channel-id/direction (e.g. ['564334x877x1/0', '564195x1292x0/1' ]) or node-id which should be excluded from consideration for routing. Note if the source or destination is excluded, the command result is undefined."
],
"default":"not to exclude any channels or nodes",
"items":{
"type":"string"
}
},
"maxhops":{
"type":"u32",
"description":[
"The maximum number of channels to return."
],
"default":"20"
}
}
},
"response":{
"required":[
"route"
],
"properties":{
"route":{
"type":"array",
"items":{
"type":"object",
"required":[
"id",
"direction",
"channel",
"amount_msat",
"delay",
"style"
],
"additionalProperties":false,
"properties":{
"id":{
"type":"pubkey",
"description":[
"The node at the end of this hop."
]
},
"channel":{
"type":"short_channel_id",
"description":[
"The channel joining these nodes."
]
},
"direction":{
"type":"u32",
"description":[
"0 if this channel is traversed from lesser to greater **id**, otherwise 1."
]
},
"amount_msat":{
"type":"msat",
"description":[
"The amount expected by the node at the end of this hop."
]
},
"delay":{
"type":"u32",
"description":[
"The total CLTV expected by the node at the end of this hop."
]
},
"style":{
"type":"string",
"description":[
"The features understood by the destination node."
],
"enum":[
"tlv"
]
}
}
}
}
},
"post_return_value_notes":[
"The final *id* will be the destination *id* given in the input. The difference between the first *amount_msat* minus the *amount_msat* given in the input is the fee (assuming the first hop is free). The first *delay* is the very worst case timeout for the payment failure, in blocks."
]
},
"riskfactor_effect_on_routing":[
"The risk factor is treated as if it were an additional fee on the route, for the purposes of comparing routes.",
"",
"The formula used is the following approximation:",
"",
" risk-fee = amount x blocks-timeout x per-block-cost",
"",
"We are given a *riskfactor* expressed as a percentage. There are 52596 blocks per year, thus *per-block-cost* is *riskfactor* divided by 5,259,600.",
"",
"The final result is:",
"",
" risk-fee = amount x blocks-timeout x riskfactor / 5259600",
"",
"Here are the risk fees in millisatoshis, using various parameters. I assume a channel charges the default of 1000 millisatoshis plus 1 part-per-million. Common to_self_delay values on the network at 14 and 144 blocks.",
