Skip to main content

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 MethodPath
GET /v1/graph/routes/{pub_key}/{amt}

Code Samples

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>,
// }

Messages

lnrpc.QueryRoutesRequest

Source: lightning.proto

FieldgRPC TypeREST TypeREST Placement
pub_key
stringstringpath
amt
int64stringpath
amt_msat
int64stringquery
final_cltv_delta
int32integerquery
fee_limit
FeeLimitobjectquery
ignored_nodes
bytes[]arrayquery
ignored_edges
EdgeLocator[]objectunknown
source_pub_key
stringstringquery
use_mission_control
boolbooleanquery
ignored_pairs
NodePair[]objectunknown
cltv_limit
uint32integerquery
dest_custom_records
DestCustomRecordsEntry[]objectunknown
outgoing_chan_id
uint64stringquery
last_hop_pubkey
bytesstringquery
route_hints
RouteHint[]objectunknown
dest_features
FeatureBit[]objectquery
time_pref
doublenumberquery

lnrpc.QueryRoutesResponse

Source: lightning.proto

FieldgRPC TypeREST Type
routes
Route[]array
success_prob
doublenumber

Nested Messages

lnrpc.FeeLimit

FieldgRPC TypeREST Type
fixed
int64string
fixed_msat
int64string
percent
int64string

lnrpc.EdgeLocator

FieldgRPC TypeREST Type
channel_id
uint64string
direction_reverse
boolboolean

lnrpc.NodePair

FieldgRPC TypeREST Type
from
bytesstring
to
bytesstring

lnrpc.QueryRoutesRequest.DestCustomRecordsEntry

FieldgRPC TypeREST Type
key
uint64unknown
value
bytesunknown

lnrpc.RouteHint

FieldgRPC TypeREST Type
hop_hints
HopHint[]array

lnrpc.HopHint

FieldgRPC TypeREST Type
node_id
stringstring
chan_id
uint64string
fee_base_msat
uint32integer
fee_proportional_millionths
uint32integer
cltv_expiry_delta
uint32integer

lnrpc.Route

FieldgRPC TypeREST Type
total_time_lock
uint32integer
total_fees
int64string
total_amt
int64string
hops
Hop[]array
total_fees_msat
int64string
total_amt_msat
int64string

lnrpc.Hop

FieldgRPC TypeREST Type
chan_id
uint64string
chan_capacity
int64string
amt_to_forward
int64string
fee
int64string
expiry
uint32integer
amt_to_forward_msat
int64string
fee_msat
int64string
pub_key
stringstring
tlv_payload
boolboolean
mpp_record
MPPRecordobject
amp_record
AMPRecordobject
custom_records
CustomRecordsEntry[]object
metadata
bytesstring

lnrpc.MPPRecord

FieldgRPC TypeREST Type
payment_addr
bytesstring
total_amt_msat
int64string

lnrpc.AMPRecord

FieldgRPC TypeREST Type
root_share
bytesstring
set_id
bytesstring
child_index
uint32integer

lnrpc.Hop.CustomRecordsEntry

FieldgRPC TypeREST Type
key
uint64unknown
value
bytesunknown

Enums

lnrpc.FeatureBit

NameNumber
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