SubscribeSingleInvoice

SubscribeSingleInvoice returns a uni-directional stream (server -> client) to notify the client of state transitions of the specified invoice. Initially the current invoice state is always sent out.

Source: invoicesrpc/invoices.proto

gRPC

info

This is a server-streaming RPC

rpc SubscribeSingleInvoice (SubscribeSingleInvoiceRequest) returns (stream Invoice);

REST

HTTP Method	Path
GET	/v2/invoices/subscribe/{r_hash}

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', 'invoicesrpc/invoices.proto'], loaderOptions);
const invoicesrpc = grpc.loadPackageDefinition(packageDefinition).invoicesrpc;
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 invoicesrpc.Invoices(GRPC_HOST, creds);
let request = {
  r_hash: <bytes>,
};
let call = client.subscribeSingleInvoice(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:
//  {
//    "memo": <string>,
//    "r_preimage": <bytes>,
//    "r_hash": <bytes>,
//    "value": <int64>,
//    "value_msat": <int64>,
//    "settled": <bool>,
//    "creation_date": <int64>,
//    "settle_date": <int64>,
//    "payment_request": <string>,
//    "description_hash": <bytes>,
//    "expiry": <int64>,
//    "fallback_addr": <string>,
//    "cltv_expiry": <uint64>,
//    "route_hints": <RouteHint>,
//    "private": <bool>,
//    "add_index": <uint64>,
//    "settle_index": <uint64>,
//    "amt_paid": <int64>,
//    "amt_paid_sat": <int64>,
//    "amt_paid_msat": <int64>,
//    "state": <InvoiceState>,
//    "htlcs": <InvoiceHTLC>,
//    "features": <FeaturesEntry>,
//    "is_keysend": <bool>,
//    "payment_addr": <bytes>,
//    "is_amp": <bool>,
//    "amp_invoice_state": <AmpInvoiceStateEntry>,
//    "is_blinded": <bool>,
//    "blinded_path_config": <BlindedPathConfig>,
//  }

Python

import codecs, grpc, os
# Generate the following 2 modules by compiling the invoicesrpc/invoices.proto with the grpcio-tools.
# See https://github.com/lightningnetwork/lnd/blob/master/docs/grpc/python.md for instructions.
import invoices_pb2 as invoicesrpc, invoices_pb2_grpc as invoicesstub

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 = invoicesstub.InvoicesStub(channel)
request = invoicesrpc.SubscribeSingleInvoiceRequest(
  r_hash=<bytes>,
)
for response in stub.SubscribeSingleInvoice(request):
  print(response)
# {
#    "memo": <string>,
#    "r_preimage": <bytes>,
#    "r_hash": <bytes>,
#    "value": <int64>,
#    "value_msat": <int64>,
#    "settled": <bool>,
#    "creation_date": <int64>,
#    "settle_date": <int64>,
#    "payment_request": <string>,
#    "description_hash": <bytes>,
#    "expiry": <int64>,
#    "fallback_addr": <string>,
#    "cltv_expiry": <uint64>,
#    "route_hints": <RouteHint>,
#    "private": <bool>,
#    "add_index": <uint64>,
#    "settle_index": <uint64>,
#    "amt_paid": <int64>,
#    "amt_paid_sat": <int64>,
#    "amt_paid_msat": <int64>,
#    "state": <InvoiceState>,
#    "htlcs": <InvoiceHTLC>,
#    "features": <FeaturesEntry>,
#    "is_keysend": <bool>,
#    "payment_addr": <bytes>,
#    "is_amp": <bool>,
#    "amp_invoice_state": <AmpInvoiceStateEntry>,
#    "is_blinded": <bool>,
#    "blinded_path_config": <BlindedPathConfig>,
# }

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}/v2/invoices/subscribe/{r_hash}`,
  // 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:
//  {
//    "memo": <string>, // <string> 
//    "r_preimage": <string>, // <bytes> 
//    "r_hash": <string>, // <bytes> 
//    "value": <string>, // <int64> 
//    "value_msat": <string>, // <int64> 
//    "settled": <boolean>, // <bool> 
//    "creation_date": <string>, // <int64> 
//    "settle_date": <string>, // <int64> 
//    "payment_request": <string>, // <string> 
//    "description_hash": <string>, // <bytes> 
//    "expiry": <string>, // <int64> 
//    "fallback_addr": <string>, // <string> 
//    "cltv_expiry": <string>, // <uint64> 
//    "route_hints": <array>, // <RouteHint> 
//    "private": <boolean>, // <bool> 
//    "add_index": <string>, // <uint64> 
//    "settle_index": <string>, // <uint64> 
//    "amt_paid": <string>, // <int64> 
//    "amt_paid_sat": <string>, // <int64> 
//    "amt_paid_msat": <string>, // <int64> 
//    "state": <string>, // <InvoiceState> 
//    "htlcs": <array>, // <InvoiceHTLC> 
//    "features": <object>, // <FeaturesEntry> 
//    "is_keysend": <boolean>, // <bool> 
//    "payment_addr": <string>, // <bytes> 
//    "is_amp": <boolean>, // <bool> 
//    "amp_invoice_state": <object>, // <AmpInvoiceStateEntry> 
//    "is_blinded": <boolean>, // <bool> 
//    "blinded_path_config": <object>, // <BlindedPathConfig> 
//  }



// --------------------------
// Example with websockets:
// --------------------------
const WebSocket = require('ws');
const fs = require('fs');

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

let ws = new WebSocket(`wss://${REST_HOST}/v2/invoices/subscribe/{r_hash}?method=GET`, {
  // Work-around for self-signed certificates.
  rejectUnauthorized: false,
  headers: {
    'Grpc-Metadata-Macaroon': fs.readFileSync(MACAROON_PATH).toString('hex'),
  },
});
let requestBody = {
  r_hash: <bytes>, // <bytes> 
};
ws.on('open', function() {
    ws.send(JSON.stringify(requestBody));
});
ws.on('error', function(err) {
    console.log('Error: ' + err);
});
ws.on('message', function(body) {
    console.log(body);
});
// Console output:
//  {
//    "memo": <string>, // <string>
//    "r_preimage": <string>, // <bytes>
//    "r_hash": <string>, // <bytes>
//    "value": <string>, // <int64>
//    "value_msat": <string>, // <int64>
//    "settled": <boolean>, // <bool>
//    "creation_date": <string>, // <int64>
//    "settle_date": <string>, // <int64>
//    "payment_request": <string>, // <string>
//    "description_hash": <string>, // <bytes>
//    "expiry": <string>, // <int64>
//    "fallback_addr": <string>, // <string>
//    "cltv_expiry": <string>, // <uint64>
//    "route_hints": <array>, // <RouteHint>
//    "private": <boolean>, // <bool>
//    "add_index": <string>, // <uint64>
//    "settle_index": <string>, // <uint64>
//    "amt_paid": <string>, // <int64>
//    "amt_paid_sat": <string>, // <int64>
//    "amt_paid_msat": <string>, // <int64>
//    "state": <string>, // <InvoiceState>
//    "htlcs": <array>, // <InvoiceHTLC>
//    "features": <object>, // <FeaturesEntry>
//    "is_keysend": <boolean>, // <bool>
//    "payment_addr": <string>, // <bytes>
//    "is_amp": <boolean>, // <bool>
//    "amp_invoice_state": <object>, // <AmpInvoiceStateEntry>
//    "is_blinded": <boolean>, // <bool>
//    "blinded_path_config": <object>, // <BlindedPathConfig>
//  }

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/invoices/subscribe/{r_hash}'
macaroon = codecs.encode(open(MACAROON_PATH, 'rb').read(), 'hex')
headers = {'Grpc-Metadata-macaroon': macaroon}
r = requests.get(url, headers=headers, stream=True, verify=TLS_PATH)
for raw_response in r.iter_lines():
  json_response = json.loads(raw_response)
  print(json_response)
# {
#    "memo": <string>,
#    "r_preimage": <bytes>,
#    "r_hash": <bytes>,
#    "value": <int64>,
#    "value_msat": <int64>,
#    "settled": <bool>,
#    "creation_date": <int64>,
#    "settle_date": <int64>,
#    "payment_request": <string>,
#    "description_hash": <bytes>,
#    "expiry": <int64>,
#    "fallback_addr": <string>,
#    "cltv_expiry": <uint64>,
#    "route_hints": <RouteHint>,
#    "private": <bool>,
#    "add_index": <uint64>,
#    "settle_index": <uint64>,
#    "amt_paid": <int64>,
#    "amt_paid_sat": <int64>,
#    "amt_paid_msat": <int64>,
#    "state": <InvoiceState>,
#    "htlcs": <InvoiceHTLC>,
#    "features": <FeaturesEntry>,
#    "is_keysend": <bool>,
#    "payment_addr": <bytes>,
#    "is_amp": <bool>,
#    "amp_invoice_state": <AmpInvoiceStateEntry>,
#    "is_blinded": <bool>,
#    "blinded_path_config": <BlindedPathConfig>,
# }

Shell

# There is no CLI command for this RPC

Messages

invoicesrpc.SubscribeSingleInvoiceRequest

Source: invoicesrpc/invoices.proto

Field	gRPC Type	REST Type	REST Placement
r_hash Hash corresponding to the (hold) invoice to subscribe to. When using REST, this field must be encoded as base64url.	bytes	string	path

lnrpc.Invoice

Source: lightning.proto

Field	gRPC Type	REST Type
memo An optional memo to attach along with the invoice. Used for record keeping purposes for the invoice's creator, and will also be set in the description field of the encoded payment request if the description_hash field is not being used.	string	string
r_preimage The hex-encoded preimage (32 byte) which will allow settling an incoming HTLC payable to this preimage. When using REST, this field must be encoded as base64.	bytes	string
r_hash The hash of the preimage. When using REST, this field must be encoded as base64. Note: Output only, don't specify for creating an invoice.	bytes	string
value The value of this invoice in satoshis The fields value and value_msat are mutually exclusive.	int64	string
value_msat The value of this invoice in millisatoshis The fields value and value_msat are mutually exclusive.	int64	string
settleddeprecated Whether this invoice has been fulfilled. The field is deprecated. Use the state field instead (compare to SETTLED).	bool	boolean
creation_date When this invoice was created. Measured in seconds since the unix epoch. Note: Output only, don't specify for creating an invoice.	int64	string
settle_date When this invoice was settled. Measured in seconds since the unix epoch. Note: Output only, don't specify for creating an invoice.	int64	string
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. Note: Output only, don't specify for creating an invoice.	string	string
description_hash Hash (SHA-256) of a description of the payment. Used if the description of payment (memo) is too long to naturally fit within the description field of an encoded payment request. When using REST, this field must be encoded as base64.	bytes	string
expiry Payment request expiry time in seconds. Default is 86400 (24 hours).	int64	string
fallback_addr Fallback on-chain address.	string	string
cltv_expiry Delta to use for the time-lock of the CLTV extended to the final hop.	uint64	string
route_hints Route hints that can each be individually used to assist in reaching the invoice's destination.	RouteHint[]	array
private Whether this invoice should include routing hints for private channels. Note: When enabled, if value and value_msat are zero, a large number of hints with these channels can be included, which might not be desirable.	bool	boolean
add_index The "add" index of this invoice. Each newly created invoice will increment this index making it monotonically increasing. Callers to the SubscribeInvoices call can use this to instantly get notified of all added invoices with an add_index greater than this one. Note: Output only, don't specify for creating an invoice.	uint64	string
settle_index The "settle" index of this invoice. Each newly settled invoice will increment this index making it monotonically increasing. Callers to the SubscribeInvoices call can use this to instantly get notified of all settled invoices with an settle_index greater than this one. Note: Output only, don't specify for creating an invoice.	uint64	string
amt_paiddeprecated Deprecated, use amt_paid_sat or amt_paid_msat.	int64	string
amt_paid_sat The amount that was accepted for this invoice, in satoshis. This will ONLY be set if this invoice has been settled or accepted. We provide this field as if the invoice was created with a zero value, then we need to record what amount was ultimately accepted. Additionally, it's possible that the sender paid MORE that was specified in the original invoice. So we'll record that here as well. Note: Output only, don't specify for creating an invoice.	int64	string
amt_paid_msat The amount that was accepted for this invoice, in millisatoshis. This will ONLY be set if this invoice has been settled or accepted. We provide this field as if the invoice was created with a zero value, then we need to record what amount was ultimately accepted. Additionally, it's possible that the sender paid MORE that was specified in the original invoice. So we'll record that here as well. Note: Output only, don't specify for creating an invoice.	int64	string
state The state the invoice is in. Note: Output only, don't specify for creating an invoice.	InvoiceState	string
htlcs List of HTLCs paying to this invoice [EXPERIMENTAL]. Note: Output only, don't specify for creating an invoice.	InvoiceHTLC[]	array
features List of features advertised on the invoice. Note: Output only, don't specify for creating an invoice.	FeaturesEntry[]	object
is_keysend Indicates if this invoice was a spontaneous payment that arrived via keysend [EXPERIMENTAL]. Note: Output only, don't specify for creating an invoice.	bool	boolean
payment_addr The payment address of this invoice. This is also called payment secret in specifications (e.g. BOLT 11). This value will be used in MPP payments, and also for newer invoices that always require the MPP payload for added end-to-end security. Note: Output only, don't specify for creating an invoice.	bytes	string
is_amp Signals whether or not this is an AMP invoice.	bool	boolean
amp_invoice_state [EXPERIMENTAL]: Maps a 32-byte hex-encoded set ID to the sub-invoice AMP state for the given set ID. This field is always populated for AMP invoices, and can be used along side LookupInvoice to obtain the HTLC information related to a given sub-invoice. Note: Output only, don't specify for creating an invoice.	AmpInvoiceStateEntry[]	object
is_blinded Signals that the invoice should include blinded paths to hide the true identity of the recipient.	bool	boolean
blinded_path_config Config values to use when creating blinded paths for this invoice. These can be used to override the defaults config values provided in by the global config. This field is only used if is_blinded is true.	BlindedPathConfig	object

Nested Messages

lnrpc.AMP

Field	gRPC Type	REST Type
root_share An n-of-n secret share of the root seed from which child payment hashes and preimages are derived.	bytes	string
set_id An identifier for the HTLC set that this HTLC belongs to.	bytes	string
child_index A nonce used to randomize the child preimage and child hash from a given root_share.	uint32	integer
hash The payment hash of the AMP HTLC.	bytes	string
preimage The preimage used to settle this AMP htlc. This field will only be populated if the invoice is in InvoiceState_ACCEPTED or InvoiceState_SETTLED.	bytes	string

lnrpc.AMPInvoiceState

Field	gRPC Type	REST Type
state The state the HTLCs associated with this setID are in.	InvoiceHTLCState	string
settle_index The settle index of this HTLC set, if the invoice state is settled.	uint64	string
settle_time The time this HTLC set was settled expressed in unix epoch.	int64	string
amt_paid_msat The total amount paid for the sub-invoice expressed in milli satoshis.	int64	string

lnrpc.BlindedPathConfig

Field	gRPC Type	REST Type
min_num_real_hops The minimum number of real hops to include in a blinded path. This doesn't include our node, so if the minimum is 1, then the path will contain at minimum our node along with an introduction node hop. If it is zero then the shortest path will use our node as an introduction node.	uint32	integer
num_hops The number of hops to include in a blinded path. This doesn't include our node, so if it is 1, then the path will contain our node along with an introduction node or dummy node hop. If paths shorter than NumHops is found, then they will be padded using dummy hops.	uint32	integer
max_num_paths The maximum number of blinded paths to select and add to an invoice.	uint32	integer
node_omission_list A list of node IDs of nodes that should not be used in any of our generated blinded paths.	bytes[]	array

lnrpc.Feature

Field	gRPC Type	REST Type
name	string	string
is_required	bool	boolean
is_known	bool	boolean

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.Invoice.AmpInvoiceStateEntry

Field	gRPC Type	REST Type
key	string	unknown
value	AMPInvoiceState	unknown

lnrpc.Invoice.FeaturesEntry

Field	gRPC Type	REST Type
key	uint32	unknown
value	Feature	unknown

lnrpc.InvoiceHTLC

Field	gRPC Type	REST Type
chan_id Short channel id over which the htlc was received.	uint64	string
htlc_index Index identifying the htlc on the channel.	uint64	string
amt_msat The amount of the htlc in msat.	uint64	string
accept_height Block height at which this htlc was accepted.	int32	integer
accept_time Time at which this htlc was accepted.	int64	string
resolve_time Time at which this htlc was settled or canceled.	int64	string
expiry_height Block height at which this htlc expires.	int32	integer
state Current state the htlc is in.	InvoiceHTLCState	string
custom_records Custom tlv records.	CustomRecordsEntry[]	object
mpp_total_amt_msat The total amount of the mpp payment in msat.	uint64	string
amp Details relevant to AMP HTLCs, only populated if this is an AMP HTLC.	AMP	object
custom_channel_data Custom channel data that might be populated in custom channels.	bytes	string

lnrpc.InvoiceHTLC.CustomRecordsEntry

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

Enums

lnrpc.Invoice.InvoiceState

Name	Number
OPEN	0
SETTLED	1
CANCELED	2
ACCEPTED	3

lnrpc.InvoiceHTLCState

Name	Number
ACCEPTED	0
SETTLED	1
CANCELED	2