SendPayment

danger

This RPC is deprecated and will be removed in a future version.

Deprecated, use SendPaymentV2. SendPayment attempts to route a payment described by the passed PaymentRequest to the final destination. The call returns a stream of payment status updates.

Source: routerrpc/router.proto

gRPC

info

This is a server-streaming RPC

rpc SendPayment (SendPaymentRequest) returns (stream PaymentStatus);

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: <int64>,
  payment_hash: <bytes>,
  final_cltv_delta: <int32>,
  payment_request: <string>,
  timeout_seconds: <int32>,
  fee_limit_sat: <int64>,
  outgoing_chan_id: <uint64>,
  cltv_limit: <int32>,
  route_hints: <RouteHint>,
  dest_custom_records: <DestCustomRecordsEntry>,
  amt_msat: <int64>,
  fee_limit_msat: <int64>,
  last_hop_pubkey: <bytes>,
  allow_self_payment: <bool>,
  dest_features: <FeatureBit>,
  max_parts: <uint32>,
  no_inflight_updates: <bool>,
  outgoing_chan_ids: <uint64>,
  payment_addr: <bytes>,
  max_shard_size_msat: <uint64>,
  amp: <bool>,
  time_pref: <double>,
  cancelable: <bool>,
  first_hop_custom_records: <FirstHopCustomRecordsEntry>,
};
let call = client.sendPayment(request);
call.on('data', function(response) {
  // A response was received from the server.
  console.log(response);
});
call.on('status', function(status) {
  // The current status of the stream.
});
call.on('end', function() {
  // The server has closed the stream.
});
// Console output:
//  {
//    "state": <PaymentState>,
//    "preimage": <bytes>,
//    "htlcs": <HTLCAttempt>,
//  }

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.SendPaymentRequest(
  dest=<bytes>,
  amt=<int64>,
  payment_hash=<bytes>,
  final_cltv_delta=<int32>,
  payment_request=<string>,
  timeout_seconds=<int32>,
  fee_limit_sat=<int64>,
  outgoing_chan_id=<uint64>,
  cltv_limit=<int32>,
  route_hints=<RouteHint>,
  dest_custom_records=<DestCustomRecordsEntry>,
  amt_msat=<int64>,
  fee_limit_msat=<int64>,
  last_hop_pubkey=<bytes>,
  allow_self_payment=<bool>,
  dest_features=<FeatureBit>,
  max_parts=<uint32>,
  no_inflight_updates=<bool>,
  outgoing_chan_ids=<uint64>,
  payment_addr=<bytes>,
  max_shard_size_msat=<uint64>,
  amp=<bool>,
  time_pref=<double>,
  cancelable=<bool>,
  first_hop_custom_records=<FirstHopCustomRecordsEntry>,
)
for response in stub.SendPayment(request):
  print(response)
# {
#    "state": <PaymentState>,
#    "preimage": <bytes>,
#    "htlcs": <HTLCAttempt>,
# }

Shell

# There is no CLI command for this RPC

Messages

routerrpc.SendPaymentRequest

Source: routerrpc/router.proto

Field	gRPC Type	REST Type	REST Placement
dest The identity pubkey of the payment recipient	bytes	string	body
amt Number of satoshis to send. The fields amt and amt_msat are mutually exclusive.	int64	string	body
payment_hash The hash to use within the payment's HTLC	bytes	string	body
final_cltv_delta The CLTV delta from the current height that should be used to set the timelock for the final hop.	int32	integer	body
payment_request A bare-bones invoice for a payment within the Lightning Network. With the details of the invoice, the sender has all the data necessary to send a payment to the recipient. The amount in the payment request may be zero. In that case it is required to set the amt field as well. If no payment request is specified, the following fields are required: dest, amt and payment_hash.	string	string	body
timeout_seconds An upper limit on the amount of time we should spend when attempting to fulfill the payment. This is expressed in seconds. If we cannot make a successful payment within this time frame, an error will be returned. This field must be non-zero.	int32	integer	body
fee_limit_sat The maximum number of satoshis that will be paid as a fee of the payment. If this field is left to the default value of 0, only zero-fee routes will be considered. This usually means single hop routes connecting directly to the destination. To send the payment without a fee limit, use max int here. The fields fee_limit_sat and fee_limit_msat are mutually exclusive.	int64	string	body
outgoing_chan_iddeprecated Deprecated, use outgoing_chan_ids. The channel id of the channel that must be taken to the first hop. If zero, any channel may be used (unless outgoing_chan_ids are set).	uint64	string	body
cltv_limit An optional maximum total time lock for the route. This should not exceed lnd's `--max-cltv-expiry` setting. If zero, then the value of `--max-cltv-expiry` is enforced.	int32	integer	body
route_hints Optional route hints to reach the destination through private channels.	RouteHint[]	array	body
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. Record types are required to be in the custom range >= 65536. When using REST, the values must be encoded as base64.	DestCustomRecordsEntry[]	object	body
amt_msat Number of millisatoshis to send. The fields amt and amt_msat are mutually exclusive.	int64	string	body
fee_limit_msat The maximum number of millisatoshis that will be paid as a fee of the payment. If this field is left to the default value of 0, only zero-fee routes will be considered. This usually means single hop routes connecting directly to the destination. To send the payment without a fee limit, use max int here. The fields fee_limit_sat and fee_limit_msat are mutually exclusive.	int64	string	body
last_hop_pubkey The pubkey of the last hop of the route. If empty, any hop may be used.	bytes	string	body
allow_self_payment If set, circular payments to self are permitted.	bool	boolean	body
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.	FeatureBit[]	array	body
max_parts The maximum number of partial payments that may be use to complete the full amount.	uint32	integer	body
no_inflight_updates If set, only the final payment update is streamed back. Intermediate updates that show which htlcs are still in flight are suppressed.	bool	boolean	body
outgoing_chan_ids The channel ids of the channels are allowed for the first hop. If empty, any channel may be used.	uint64[]	array	body
payment_addr An optional payment addr to be included within the last hop of the route. This is also called payment secret in specifications (e.g. BOLT 11).	bytes	string	body
max_shard_size_msat The largest payment split that should be attempted when making a payment if splitting is necessary. Setting this value will effectively cause lnd to split more aggressively, vs only when it thinks it needs to. Note that this value is in milli-satoshis.	uint64	string	body
amp If set, an AMP-payment will be attempted.	bool	boolean	body
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	body
cancelable If set, the payment loop can be interrupted by manually canceling the payment context, even before the payment timeout is reached. Note that the payment may still succeed after cancellation, as in-flight attempts can still settle afterwards. Canceling will only prevent further attempts from being sent.	bool	boolean	body
first_hop_custom_records An optional field that can be used to pass an arbitrary set of TLV records to the first hop peer of this payment. This can be used to pass application specific data during the payment attempt. Record types are required to be in the custom range >= 65536. When using REST, the values must be encoded as base64.	FirstHopCustomRecordsEntry[]	object	body

routerrpc.PaymentStatus

Source: routerrpc/router.proto

Field	gRPC Type	REST Type
state Current state the payment is in.	PaymentState	string
preimage The pre-image of the payment when state is SUCCEEDED.	bytes	string
htlcs The HTLCs made in attempt to settle the payment [EXPERIMENTAL].	HTLCAttempt[]	array

Nested Messages

lnrpc.AMPRecord

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

lnrpc.ChannelUpdate

Field	gRPC Type	REST Type
signature The signature that validates the announced data and proves the ownership of node id.	bytes	string
chain_hash The target chain that this channel was opened within. This value should be the genesis hash of the target chain. Along with the short channel ID, this uniquely identifies the channel globally in a blockchain.	bytes	string
chan_id The unique description of the funding transaction.	uint64	string
timestamp A timestamp that allows ordering in the case of multiple announcements. We should ignore the message if timestamp is not greater than the last-received.	uint32	integer
message_flags The bitfield that describes whether optional fields are present in this update. Currently, the least-significant bit must be set to 1 if the optional field MaxHtlc is present.	uint32	integer
channel_flags The bitfield that describes additional meta-data concerning how the update is to be interpreted. Currently, the least-significant bit must be set to 0 if the creating node corresponds to the first node in the previously sent channel announcement and 1 otherwise. If the second bit is set, then the channel is set to be disabled.	uint32	integer
time_lock_delta The minimum number of blocks this node requires to be added to the expiry of HTLCs. This is a security parameter determined by the node operator. This value represents the required gap between the time locks of the incoming and outgoing HTLC's set to this node.	uint32	integer
htlc_minimum_msat The minimum HTLC value which will be accepted.	uint64	string
base_fee The base fee that must be used for incoming HTLC's to this particular channel. This value will be tacked onto the required for a payment independent of the size of the payment.	uint32	integer
fee_rate The fee rate that will be charged per millionth of a satoshi.	uint32	integer
htlc_maximum_msat The maximum HTLC value which will be accepted.	uint64	string
extra_opaque_data The set of data that was appended to this message, some of which we may not actually know how to iterate or parse. By holding onto this data, we ensure that we're able to properly validate the set of signatures that cover these new fields, and ensure we're able to make upgrades to the network in a forwards compatible manner.	bytes	string

lnrpc.Failure

Field	gRPC Type	REST Type
code Failure code as defined in the Lightning spec	FailureCode	string
channel_update An optional channel update message.	ChannelUpdate	object
htlc_msat A failure type-dependent htlc value.	uint64	string
onion_sha_256 The sha256 sum of the onion payload.	bytes	string
cltv_expiry A failure type-dependent cltv expiry value.	uint32	integer
flags A failure type-dependent flags value.	uint32	integer
failure_source_index The position in the path of the intermediate or final node that generated the failure message. Position zero is the sender node.	uint32	integer
height A failure type-dependent block height.	uint32	integer

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
blinding_point Blinding point is an optional blinding point included for introduction nodes in blinded paths. This field is mandatory for hops that represents the introduction point in a blinded path.	bytes	string
encrypted_data Encrypted data is a receiver-produced blob of data that provides hops in a blinded route with forwarding data. As this data is encrypted by the recipient, we will not be able to parse it - it is essentially an arbitrary blob of data from our node's perspective. This field is mandatory for all hops in a blinded path, including the introduction node.	bytes	string
total_amt_msat The total amount that is sent to the recipient (possibly across multiple HTLCs), as specified by the sender when making a payment to a blinded path. This value is only set in the final hop payload of a blinded payment. This value is analogous to the MPPRecord that is used for regular (non-blinded) MPP payments.	uint64	string

lnrpc.Hop.CustomRecordsEntry

Field	gRPC Type	REST Type
key	uint64	unknown
value	bytes	unknown

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.HTLCAttempt

Field	gRPC Type	REST Type
attempt_id The unique ID that is used for this attempt.	uint64	string
status The status of the HTLC.	HTLCStatus	string
route The route taken by this HTLC.	Route	object
attempt_time_ns The time in UNIX nanoseconds at which this HTLC was sent.	int64	string
resolve_time_ns The time in UNIX nanoseconds at which this HTLC was settled or failed. This value will not be set if the HTLC is still IN_FLIGHT.	int64	string
failure Detailed htlc failure info.	Failure	object
preimage The preimage that was used to settle the HTLC.	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. This is also called payment secret in specifications (e.g. BOLT 11).	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.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
first_hop_amount_msat The actual on-chain amount that was sent out to the first hop. This value is only different from the total_amt_msat field if this is a custom channel payment and the value transported in the HTLC is different from the BTC amount in the HTLC. If this value is zero, then this is an old payment that didn't have this value yet and can be ignored.	int64	string
custom_channel_data Custom channel data that might be populated in custom channels.	bytes	string

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

routerrpc.SendPaymentRequest.DestCustomRecordsEntry

Field	gRPC Type	REST Type
key	uint64	unknown
value	bytes	unknown

routerrpc.SendPaymentRequest.FirstHopCustomRecordsEntry

Field	gRPC Type	REST Type
key	uint64	unknown
value	bytes	unknown

Enums

lnrpc.Failure.FailureCode

Name	Number
RESERVED The numbers assigned in this enumeration match the failure codes as defined in BOLT #4. Because protobuf 3 requires enums to start with 0, a RESERVED value is added.	0
INCORRECT_OR_UNKNOWN_PAYMENT_DETAILS	1
INCORRECT_PAYMENT_AMOUNT	2
FINAL_INCORRECT_CLTV_EXPIRY	3
FINAL_INCORRECT_HTLC_AMOUNT	4
FINAL_EXPIRY_TOO_SOON	5
INVALID_REALM	6
EXPIRY_TOO_SOON	7
INVALID_ONION_VERSION	8
INVALID_ONION_HMAC	9
INVALID_ONION_KEY	10
AMOUNT_BELOW_MINIMUM	11
FEE_INSUFFICIENT	12
INCORRECT_CLTV_EXPIRY	13
CHANNEL_DISABLED	14
TEMPORARY_CHANNEL_FAILURE	15
REQUIRED_NODE_FEATURE_MISSING	16
REQUIRED_CHANNEL_FEATURE_MISSING	17
UNKNOWN_NEXT_PEER	18
TEMPORARY_NODE_FAILURE	19
PERMANENT_NODE_FAILURE	20
PERMANENT_CHANNEL_FAILURE	21
EXPIRY_TOO_FAR	22
MPP_TIMEOUT	23
INVALID_ONION_PAYLOAD	24
INVALID_ONION_BLINDING	25
INTERNAL_FAILURE An internal error occurred.	997
UNKNOWN_FAILURE The error source is known, but the failure itself couldn't be decoded.	998
UNREADABLE_FAILURE An unreadable failure result is returned if the received failure message cannot be decrypted. In that case the error source is unknown.	999

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
ROUTE_BLINDING_REQUIRED	24
ROUTE_BLINDING_OPTIONAL	25
AMP_REQ	30
AMP_OPT	31

lnrpc.HTLCAttempt.HTLCStatus

Name	Number
IN_FLIGHT	0
SUCCEEDED	1
FAILED	2

routerrpc.PaymentState

Name	Number
IN_FLIGHT Payment is still in flight.	0
SUCCEEDED Payment completed successfully.	1
FAILED_TIMEOUT There are more routes to try, but the payment timeout was exceeded.	2
FAILED_NO_ROUTE All possible routes were tried and failed permanently. Or were no routes to the destination at all.	3
FAILED_ERROR A non-recoverable error has occurred.	4
FAILED_INCORRECT_PAYMENT_DETAILS Payment details incorrect (unknown hash, invalid amt or invalid final cltv delta)	5
FAILED_INSUFFICIENT_BALANCE Insufficient local balance.	6