QueryRoutes

QueryRoutes attempts to query the daemon's Channel Router for a possible route to a target destination capable of carrying a specific amount of satoshis. The returned route contains the full details required to craft and send an HTLC, also including the necessary information that should be present within the Sphinx packet encapsulated within the HTLC.

When using REST, the dest_custom_records map type can be set by appending &dest_custom_records[<record_number>]=<record_data_base64_url_encoded> to the URL. Unfortunately this map type doesn't appear in the REST API documentation because of a bug in the grpc-gateway library.

Source: lightning.proto

gRPC

rpc QueryRoutes (QueryRoutesRequest) returns (QueryRoutesResponse);

REST

HTTP Method	Path
GET	/v1/graph/routes/{pub_key}/{amt}

Code Samples

gRPC

Javascript

const fs = require('fs');
const grpc = require('@grpc/grpc-js');
const protoLoader = require('@grpc/proto-loader');

const GRPC_HOST = 'localhost:10009'
const MACAROON_PATH = 'LND_DIR/data/chain/bitcoin/regtest/admin.macaroon'
const TLS_PATH = 'LND_DIR/tls.cert'

const loaderOptions = {
  keepCase: true,
  longs: String,
  enums: String,
  defaults: true,
  oneofs: true,
};
const packageDefinition = protoLoader.loadSync('lightning.proto', loaderOptions);
const lnrpc = grpc.loadPackageDefinition(packageDefinition).lnrpc;
process.env.GRPC_SSL_CIPHER_SUITES = 'HIGH+ECDSA';
const tlsCert = fs.readFileSync(TLS_PATH);
const sslCreds = grpc.credentials.createSsl(tlsCert);
const macaroon = fs.readFileSync(MACAROON_PATH).toString('hex');
const macaroonCreds = grpc.credentials.createFromMetadataGenerator(function(args, callback) {
  let metadata = new grpc.Metadata();
  metadata.add('macaroon', macaroon);
  callback(null, metadata);
});
let creds = grpc.credentials.combineChannelCredentials(sslCreds, macaroonCreds);
let client = new lnrpc.Lightning(GRPC_HOST, creds);
let request = {
  pub_key: <string>,
  amt: <int64>,
  amt_msat: <int64>,
  final_cltv_delta: <int32>,
  fee_limit: <FeeLimit>,
  ignored_nodes: <bytes>,
  ignored_edges: <EdgeLocator>,
  source_pub_key: <string>,
  use_mission_control: <bool>,
  ignored_pairs: <NodePair>,
  cltv_limit: <uint32>,
  dest_custom_records: <DestCustomRecordsEntry>,
  outgoing_chan_id: <uint64>,
  last_hop_pubkey: <bytes>,
  route_hints: <RouteHint>,
  dest_features: <FeatureBit>,
  time_pref: <double>,
};
client.queryRoutes(request, function(err, response) {
  console.log(response);
});
// Console output:
//  {
//    "routes": <Route>,
//    "success_prob": <double>,
//  }

Python

import codecs, grpc, os
# Generate the following 2 modules by compiling the lightning.proto with the grpcio-tools.
# See https://github.com/lightningnetwork/lnd/blob/master/docs/grpc/python.md for instructions.
import lightning_pb2 as lnrpc, lightning_pb2_grpc as lightningstub

GRPC_HOST = 'localhost:10009'
MACAROON_PATH = 'LND_DIR/data/chain/bitcoin/regtest/admin.macaroon'
TLS_PATH = 'LND_DIR/tls.cert'

# create macaroon credentials
macaroon = codecs.encode(open(MACAROON_PATH, 'rb').read(), 'hex')
def metadata_callback(context, callback):
  callback([('macaroon', macaroon)], None)
auth_creds = grpc.metadata_call_credentials(metadata_callback)
# create SSL credentials
os.environ['GRPC_SSL_CIPHER_SUITES'] = 'HIGH+ECDSA'
cert = open(TLS_PATH, 'rb').read()
ssl_creds = grpc.ssl_channel_credentials(cert)
# combine macaroon and SSL credentials
combined_creds = grpc.composite_channel_credentials(ssl_creds, auth_creds)
# make the request
channel = grpc.secure_channel(GRPC_HOST, combined_creds)
stub = lightningstub.LightningStub(channel)
request = lnrpc.QueryRoutesRequest(
  pub_key=<string>,
  amt=<int64>,
  amt_msat=<int64>,
  final_cltv_delta=<int32>,
  fee_limit=<FeeLimit>,
  ignored_nodes=<bytes>,
  ignored_edges=<EdgeLocator>,
  source_pub_key=<string>,
  use_mission_control=<bool>,
  ignored_pairs=<NodePair>,
  cltv_limit=<uint32>,
  dest_custom_records=<DestCustomRecordsEntry>,
  outgoing_chan_id=<uint64>,
  last_hop_pubkey=<bytes>,
  route_hints=<RouteHint>,
  dest_features=<FeatureBit>,
  time_pref=<double>,
)
response = stub.QueryRoutes(request)
print(response)
# {
#    "routes": <Route>,
#    "success_prob": <double>,
# }

REST

Javascript

const fs = require('fs');
const request = require('request');

const REST_HOST = 'localhost:8080'
const MACAROON_PATH = 'LND_DIR/data/chain/bitcoin/regtest/admin.macaroon'

let options = {
  url: `https://${REST_HOST}/v1/graph/routes/{pub_key}/{amt}`,
  // Work-around for self-signed certificates.
  rejectUnauthorized: false,
  json: true,
  headers: {
    'Grpc-Metadata-macaroon': fs.readFileSync(MACAROON_PATH).toString('hex'),
  },
}
request.get(options, function(error, response, body) {
  console.log(body);
});
// Console output:
//  {
//    "routes": <array>, // <Route> 
//    "success_prob": <number>, // <double> 
//  }

Python

import base64, codecs, json, requests

REST_HOST = 'localhost:8080'
MACAROON_PATH = 'LND_DIR/data/chain/bitcoin/regtest/admin.macaroon'
TLS_PATH = 'LND_DIR/tls.cert'

url = f'https://{REST_HOST}/v1/graph/routes/{pub_key}/{amt}'
macaroon = codecs.encode(open(MACAROON_PATH, 'rb').read(), 'hex')
headers = {'Grpc-Metadata-macaroon': macaroon}
r = requests.get(url, headers=headers, verify=TLS_PATH)
print(r.json())
# {
#    "routes": <Route>,
#    "success_prob": <double>,
# }

Shell

$ lncli queryroutes --help

NAME:
   lncli queryroutes - Query a route to a destination.

USAGE:
   lncli queryroutes [command options] dest amt

CATEGORY:
   Payments

DESCRIPTION:
   Queries the channel router for a potential path to the destination that has sufficient flow for the amount including fees

OPTIONS:
   --dest value               the 33-byte hex-encoded public key for the payment destination
   --amt value                the amount to send expressed in satoshis (default: 0)
   --fee_limit value          maximum fee allowed in satoshis when sending the payment (default: 0)
   --fee_limit_percent value  percentage of the payment's amount used as the maximum fee allowed when sending the payment (default: 0)
   --final_cltv_delta value   (optional) number of blocks the last hop has to reveal the preimage (default: 0)
   --use_mc                   use mission control probabilities
   --outgoing_chanid value    (optional) the channel id of the channel that must be taken to the first hop (default: 0)
   --ignore_pair value        ignore directional node pair <node1>:<node2>. This flag can be specified multiple times if multiple node pairs are to be ignored
   --time_pref value          (optional) expresses time preference (range -1 to 1) (default: 0)
   --cltv_limit value         the maximum time lock that may be used for this payment (default: 0)
   

Messages

lnrpc.QueryRoutesRequest

Source: lightning.proto

Field	gRPC Type	REST Type	REST Placement
pub_key The 33-byte hex-encoded public key for the payment destination	string	string	path
amt The amount to send expressed in satoshis. The fields amt and amt_msat are mutually exclusive.	int64	string	path
amt_msat The amount to send expressed in millisatoshis. The fields amt and amt_msat are mutually exclusive.	int64	string	query
final_cltv_delta An optional CLTV delta from the current height that should be used for the timelock of the final hop. Note that unlike SendPayment, QueryRoutes does not add any additional block padding on top of final_ctlv_delta. This padding of a few blocks needs to be added manually or otherwise failures may happen when a block comes in while the payment is in flight.	int32	integer	query
fee_limit The maximum number of satoshis that will be paid as a fee of the payment. This value can be represented either as a percentage of the amount being sent, or as a fixed amount of the maximum fee the user is willing the pay to send the payment. If not specified, lnd will use a default value of 100% fees for small amounts (<=1k sat) or 5% fees for larger amounts. Nested REST Parameters fee_limit.fixed: string in query fee_limit.fixed_msat: string in query fee_limit.percent: string in query	FeeLimit	object	query
ignored_nodes A list of nodes to ignore during path finding. When using REST, these fields must be encoded as base64.	bytes[]	array	query
ignored_edges Deprecated. A list of edges to ignore during path finding.	EdgeLocator[]	object	unknown
source_pub_key The source node where the request route should originated from. If empty, self is assumed.	string	string	query
use_mission_control If set to true, edge probabilities from mission control will be used to get the optimal route.	bool	boolean	query
ignored_pairs A list of directed node pairs that will be ignored during path finding.	NodePair[]	object	unknown
cltv_limit An optional maximum total time lock for the route. If the source is empty or ourselves, this should not exceed lnd's --max-cltv-expiry setting. If zero, then the value of --max-cltv-expiry is used as the limit.	uint32	integer	query
dest_custom_records An optional field that can be used to pass an arbitrary set of TLV records to a peer which understands the new records. This can be used to pass application specific data during the payment attempt. If the destination does not support the specified records, an error will be returned. Record types are required to be in the custom range >= 65536. When using REST, the values must be encoded as base64.	DestCustomRecordsEntry[]	object	unknown
outgoing_chan_id The channel id of the channel that must be taken to the first hop. If zero, any channel may be used.	uint64	string	query
last_hop_pubkey The pubkey of the last hop of the route. If empty, any hop may be used.	bytes	string	query
route_hints Optional route hints to reach the destination through private channels.	RouteHint[]	object	unknown
dest_features Features assumed to be supported by the final node. All transitive feature dependencies must also be set properly. For a given feature bit pair, either optional or remote may be set, but not both. If this field is nil or empty, the router will try to load destination features from the graph as a fallback. Nested REST Parameters dest_features: array in query	FeatureBit[]	object	query
time_pref The time preference for this payment. Set to -1 to optimize for fees only, to 1 to optimize for reliability only or a value inbetween for a mix.	double	number	query

lnrpc.QueryRoutesResponse

Source: lightning.proto

Field	gRPC Type	REST Type
routes The route that results from the path finding operation. This is still a repeated field to retain backwards compatibility.	Route[]	array
success_prob The success probability of the returned route based on the current mission control state. [EXPERIMENTAL]	double	number

Nested Messages

lnrpc.FeeLimit

Field	gRPC Type	REST Type
fixed The fee limit expressed as a fixed amount of satoshis. The fields fixed and fixed_msat are mutually exclusive.	int64	string
fixed_msat The fee limit expressed as a fixed amount of millisatoshis. The fields fixed and fixed_msat are mutually exclusive.	int64	string
percent The fee limit expressed as a percentage of the payment amount.	int64	string

lnrpc.EdgeLocator

Field	gRPC Type	REST Type
channel_id The short channel id of this edge.	uint64	string
direction_reverse The direction of this edge. If direction_reverse is false, the direction of this edge is from the channel endpoint with the lexicographically smaller pub key to the endpoint with the larger pub key. If direction_reverse is is true, the edge goes the other way.	bool	boolean

lnrpc.NodePair

Field	gRPC Type	REST Type
from The sending node of the pair. When using REST, this field must be encoded as base64.	bytes	string
to The receiving node of the pair. When using REST, this field must be encoded as base64.	bytes	string

lnrpc.QueryRoutesRequest.DestCustomRecordsEntry

Field	gRPC Type	REST Type
key	uint64	unknown
value	bytes	unknown

lnrpc.RouteHint

Field	gRPC Type	REST Type
hop_hints A list of hop hints that when chained together can assist in reaching a specific destination.	HopHint[]	array

lnrpc.HopHint

Field	gRPC Type	REST Type
node_id The public key of the node at the start of the channel.	string	string
chan_id The unique identifier of the channel.	uint64	string
fee_base_msat The base fee of the channel denominated in millisatoshis.	uint32	integer
fee_proportional_millionths The fee rate of the channel for sending one satoshi across it denominated in millionths of a satoshi.	uint32	integer
cltv_expiry_delta The time-lock delta of the channel.	uint32	integer

lnrpc.Route

Field	gRPC Type	REST Type
total_time_lock The cumulative (final) time lock across the entire route. This is the CLTV value that should be extended to the first hop in the route. All other hops will decrement the time-lock as advertised, leaving enough time for all hops to wait for or present the payment preimage to complete the payment.	uint32	integer
total_fees The sum of the fees paid at each hop within the final route. In the case of a one-hop payment, this value will be zero as we don't need to pay a fee to ourselves.	int64	string
total_amt The total amount of funds required to complete a payment over this route. This value includes the cumulative fees at each hop. As a result, the HTLC extended to the first-hop in the route will need to have at least this many satoshis, otherwise the route will fail at an intermediate node due to an insufficient amount of fees.	int64	string
hops Contains details concerning the specific forwarding details at each hop.	Hop[]	array
total_fees_msat The total fees in millisatoshis.	int64	string
total_amt_msat The total amount in millisatoshis.	int64	string

lnrpc.Hop

Field	gRPC Type	REST Type
chan_id The unique channel ID for the channel. The first 3 bytes are the block height, the next 3 the index within the block, and the last 2 bytes are the output index for the channel.	uint64	string
chan_capacity	int64	string
amt_to_forward	int64	string
fee	int64	string
expiry	uint32	integer
amt_to_forward_msat	int64	string
fee_msat	int64	string
pub_key An optional public key of the hop. If the public key is given, the payment can be executed without relying on a copy of the channel graph.	string	string
tlv_payload If set to true, then this hop will be encoded using the new variable length TLV format. Note that if any custom tlv_records below are specified, then this field MUST be set to true for them to be encoded properly.	bool	boolean
mpp_record An optional TLV record that signals the use of an MPP payment. If present, the receiver will enforce that the same mpp_record is included in the final hop payload of all non-zero payments in the HTLC set. If empty, a regular single-shot payment is or was attempted.	MPPRecord	object
amp_record An optional TLV record that signals the use of an AMP payment. If present, the receiver will treat all received payments including the same (payment_addr, set_id) pair as being part of one logical payment. The payment will be settled by XORing the root_share's together and deriving the child hashes and preimages according to BOLT XX. Must be used in conjunction with mpp_record.	AMPRecord	object
custom_records An optional set of key-value TLV records. This is useful within the context of the SendToRoute call as it allows callers to specify arbitrary K-V pairs to drop off at each hop within the onion.	CustomRecordsEntry[]	object
metadata The payment metadata to send along with the payment to the payee.	bytes	string

lnrpc.MPPRecord

Field	gRPC Type	REST Type
payment_addr A unique, random identifier used to authenticate the sender as the intended payer of a multi-path payment. The payment_addr must be the same for all subpayments, and match the payment_addr provided in the receiver's invoice. The same payment_addr must be used on all subpayments.	bytes	string
total_amt_msat The total amount in milli-satoshis being sent as part of a larger multi-path payment. The caller is responsible for ensuring subpayments to the same node and payment_hash sum exactly to total_amt_msat. The same total_amt_msat must be used on all subpayments.	int64	string

lnrpc.AMPRecord

Field	gRPC Type	REST Type
root_share	bytes	string
set_id	bytes	string
child_index	uint32	integer

lnrpc.Hop.CustomRecordsEntry

Field	gRPC Type	REST Type
key	uint64	unknown
value	bytes	unknown

Enums

lnrpc.FeatureBit

Name	Number
DATALOSS_PROTECT_REQ	0
DATALOSS_PROTECT_OPT	1
INITIAL_ROUING_SYNC	3
UPFRONT_SHUTDOWN_SCRIPT_REQ	4
UPFRONT_SHUTDOWN_SCRIPT_OPT	5
GOSSIP_QUERIES_REQ	6
GOSSIP_QUERIES_OPT	7
TLV_ONION_REQ	8
TLV_ONION_OPT	9
EXT_GOSSIP_QUERIES_REQ	10
EXT_GOSSIP_QUERIES_OPT	11
STATIC_REMOTE_KEY_REQ	12
STATIC_REMOTE_KEY_OPT	13
PAYMENT_ADDR_REQ	14
PAYMENT_ADDR_OPT	15
MPP_REQ	16
MPP_OPT	17
WUMBO_CHANNELS_REQ	18
WUMBO_CHANNELS_OPT	19
ANCHORS_REQ	20
ANCHORS_OPT	21
ANCHORS_ZERO_FEE_HTLC_REQ	22
ANCHORS_ZERO_FEE_HTLC_OPT	23
AMP_REQ	30
AMP_OPT	31