EstimateRouteFee

EstimateRouteFee allows callers to obtain a lower bound w.r.t how much it may cost to send an HTLC to the target end destination.

Source: routerrpc/router.proto

gRPC

rpc EstimateRouteFee (RouteFeeRequest) returns (RouteFeeResponse);

REST

HTTP Method	Path
POST	/v2/router/route/estimatefee

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', 'routerrpc/router.proto'], loaderOptions);
const routerrpc = grpc.loadPackageDefinition(packageDefinition).routerrpc;
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 routerrpc.Router(GRPC_HOST, creds);
let request = {
  dest: <bytes>,
  amt_sat: <int64>,
  payment_request: <string>,
  timeout: <uint32>,
};
client.estimateRouteFee(request, function(err, response) {
  console.log(response);
});
// Console output:
//  {
//    "routing_fee_msat": <int64>,
//    "time_lock_delay": <int64>,
//    "failure_reason": <PaymentFailureReason>,
//  }

Python

import codecs, grpc, os
# Generate the following 2 modules by compiling the routerrpc/router.proto with the grpcio-tools.
# See https://github.com/lightningnetwork/lnd/blob/master/docs/grpc/python.md for instructions.
import router_pb2 as routerrpc, router_pb2_grpc as routerstub

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 = routerstub.RouterStub(channel)
request = routerrpc.RouteFeeRequest(
  dest=<bytes>,
  amt_sat=<int64>,
  payment_request=<string>,
  timeout=<uint32>,
)
response = stub.EstimateRouteFee(request)
print(response)
# {
#    "routing_fee_msat": <int64>,
#    "time_lock_delay": <int64>,
#    "failure_reason": <PaymentFailureReason>,
# }

grpcurl

# grpcurl docs: https://github.com/fullstorydev/grpcurl
# Proto source: https://github.com/lightningnetwork/lnd
GRPC_HOST=localhost:10009
LND_DIR=~/.lnd
LND_SOURCE=path/to/lnd
NETWORK=mainnet
MACAROON_PATH="$LND_DIR/data/chain/bitcoin/$NETWORK/admin.macaroon"
TLS_PATH="$LND_DIR/tls.cert"

grpcurl \
    -import-path $LND_SOURCE/lnrpc/ \
    -proto routerrpc/router.proto \
    -cacert $TLS_PATH \
    -H "macaroon: $(xxd -ps -u -c 1000 $MACAROON_PATH)" \
    -d '{ "dest": BASE64_ENCODED_VALUE, "amt_sat": <int64>, "payment_request": <string>, "timeout": <uint32> }' \
    $GRPC_HOST \
    routerrpc.Router/EstimateRouteFee

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 requestBody = {
  dest: <string>, // <bytes> (base64 encoded)
  amt_sat: <string>, // <int64> 
  payment_request: <string>, // <string> 
  timeout: <integer>, // <uint32> 
};
let options = {
  url: `https://${REST_HOST}/v2/router/route/estimatefee`,
  // Work-around for self-signed certificates.
  rejectUnauthorized: false,
  json: true,
  headers: {
    'Grpc-Metadata-macaroon': fs.readFileSync(MACAROON_PATH).toString('hex'),
  },
  form: JSON.stringify(requestBody),
}
request.post(options, function(error, response, body) {
  console.log(body);
});
// Console output:
//  {
//    "routing_fee_msat": <string>, // <int64> 
//    "time_lock_delay": <string>, // <int64> 
//    "failure_reason": <string>, // <PaymentFailureReason> 
//  }

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}/v2/router/route/estimatefee'
macaroon = codecs.encode(open(MACAROON_PATH, 'rb').read(), 'hex')
headers = {'Grpc-Metadata-macaroon': macaroon}
data = {
  'dest': base64.b64encode(<bytes>),
  'amt_sat': <int64>,
  'payment_request': <string>,
  'timeout': <uint32>,
}
r = requests.post(url, headers=headers, data=json.dumps(data), verify=TLS_PATH)
print(r.json())
# {
#    "routing_fee_msat": <int64>,
#    "time_lock_delay": <int64>,
#    "failure_reason": <PaymentFailureReason>,
# }

curl

REST_HOST=localhost:8080
LND_DIR=~/.lnd
NETWORK=mainnet
MACAROON_PATH="$LND_DIR/data/chain/bitcoin/$NETWORK/admin.macaroon"
TLS_PATH="$LND_DIR/tls.cert"

curl -X POST \
    --cacert $TLS_PATH \
    -H "Grpc-Metadata-macaroon: $(xxd -ps -u -c 1000 $MACAROON_PATH)" \
    -d '{ "dest": BASE64_ENCODED_VALUE, "amt_sat": <int64>, "payment_request": <string>, "timeout": <uint32> }' \
    https://$REST_HOST/v2/router/route/estimatefee

lncli

$ lncli estimateroutefee --help

NAME:
   lncli estimateroutefee - Estimate routing fees based on a destination or an invoice.

USAGE:
   lncli estimateroutefee [command options] [arguments...]

CATEGORY:
   Payments

OPTIONS:
   --dest value     the 33-byte hex-encoded public key for the probe destination. If it is specified then the amt flag is required. If it isn't specified then the pay_req field has to.
   --amt value      the payment amount expressed in satoshis that should be probed for. This field is mandatory if dest is specified. (default: 0)
   --pay_req value  a zpay32 encoded payment request which is used to probe. If the destination is not public then route hints are scanned for a public node.
   --timeout value  a deadline for the probe attempt. Only applicable if pay_req is specified. (default: 1m0s)
   

Messages

routerrpc.RouteFeeRequest

Source: routerrpc/router.proto

Field	gRPC Type	REST Type	REST Placement
dest The destination one wishes to obtain a routing fee quote to. If set, this parameter requires the amt_sat parameter also to be set. This parameter combination triggers a graph based routing fee estimation as opposed to a payment probe based estimate in case a payment request is provided. The graph based estimation is an algorithm that is executed on the in memory graph. Hence its runtime is significantly shorter than a payment probe estimation that sends out actual payments to the network.	bytes	string	body
amt_sat The amount one wishes to send to the target destination. It is only to be used in combination with the dest parameter.	int64	string	body
payment_request A payment request of the target node that the route fee request is intended for. Its parameters are input to probe payments that estimate routing fees. The timeout parameter can be specified to set a maximum time on the probing attempt. Cannot be used in combination with dest and amt_sat.	string	string	body
timeout A user preference of how long a probe payment should maximally be allowed to take, denoted in seconds. The probing payment loop is aborted if this timeout is reached. Note that the probing process itself can take longer than the timeout if the HTLC becomes delayed or stuck. Canceling the context of this call will not cancel the payment loop, the duration is only controlled by the timeout parameter.	uint32	integer	body

routerrpc.RouteFeeResponse

Source: routerrpc/router.proto

Field	gRPC Type	REST Type
routing_fee_msat A lower bound of the estimated fee to the target destination within the network, expressed in milli-satoshis.	int64	string
time_lock_delay An estimate of the worst case time delay that can occur. Note that callers will still need to factor in the final CLTV delta of the last hop into this value.	int64	string
failure_reason An indication whether a probing payment succeeded or whether and why it failed. FAILURE_REASON_NONE indicates success.	PaymentFailureReason	string

Enums

lnrpc.PaymentFailureReason

Name	Number
FAILURE_REASON_NONE Payment isn't failed (yet).	0
FAILURE_REASON_TIMEOUT There are more routes to try, but the payment timeout was exceeded.	1
FAILURE_REASON_NO_ROUTE All possible routes were tried and failed permanently. Or were no routes to the destination at all.	2
FAILURE_REASON_ERROR A non-recoverable error has occured.	3
FAILURE_REASON_INCORRECT_PAYMENT_DETAILS Payment details incorrect (unknown hash, invalid amt or invalid final cltv delta)	4
FAILURE_REASON_INSUFFICIENT_BALANCE Insufficient local balance.	5
FAILURE_REASON_CANCELED The payment was canceled.	6