SubscribeInvoices

SubscribeInvoices returns a uni-directional stream (server -> client) for notifying the client of newly added/settled invoices. The caller can optionally specify the add_index and/or the settle_index. If the add_index is specified, then we'll first start by sending add invoice events for all invoices with an add_index greater than the specified value. If the settle_index is specified, the next, we'll send out all settle events for invoices with a settle_index greater than the specified value. One or both of these fields can be set. If no fields are set, then we'll only send out the latest add/settle events.

Source: lightning.proto

gRPC

info

This is a server-streaming RPC

rpc SubscribeInvoices (InvoiceSubscription) returns (stream Invoice);

REST

HTTP Method	Path
GET	/v1/invoices/subscribe

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 = {
  add_index: <uint64>,
  settle_index: <uint64>,
};
let call = client.subscribeInvoices(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>,
//  }

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.InvoiceSubscription(
  add_index=<uint64>,
  settle_index=<uint64>,
)
for response in stub.SubscribeInvoices(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>,
# }

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/invoices/subscribe`,
  // 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> (base64 encoded)
//    "r_hash": <string>, // <bytes> (base64 encoded)
//    "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> (base64 encoded)
//    "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> (base64 encoded)
//    "is_amp": <boolean>, // <bool> 
//    "amp_invoice_state": <object>, // <AmpInvoiceStateEntry> 
//  }



// --------------------------
// 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}/v1/invoices/subscribe?method=GET`, {
  // Work-around for self-signed certificates.
  rejectUnauthorized: false,
  headers: {
    'Grpc-Metadata-Macaroon': fs.readFileSync(MACAROON_PATH).toString('hex'),
  },
});
let requestBody = {
  add_index: <uint64>, // <uint64> 
  settle_index: <uint64>, // <uint64> 
};
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>
//  }

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/invoices/subscribe'
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>,
# }

Shell

# There is no CLI command for this RPC

Messages

lnrpc.InvoiceSubscription

Source: lightning.proto

Field	gRPC Type	REST Type	REST Placement
add_index If specified (non-zero), then we'll first start by sending out notifications for all added indexes with an add_index greater than this value. This allows callers to catch up on any events they missed while they weren't connected to the streaming RPC.	uint64	string	query
settle_index If specified (non-zero), then we'll first start by sending out notifications for all settled indexes with an settle_index greater than this value. This allows callers to catch up on any events they missed while they weren't connected to the streaming RPC.	uint64	string	query

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 3600 (1 hour).	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_paid 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. 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. 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 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

Nested Messages

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

lnrpc.InvoiceHTLC.CustomRecordsEntry

Field	gRPC Type	REST Type
key	uint64	unknown
value	bytes	unknown

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

Field	gRPC Type	REST Type
key	uint32	unknown
value	Feature	unknown

lnrpc.Feature

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

lnrpc.Invoice.AmpInvoiceStateEntry

Field	gRPC Type	REST Type
key	string	unknown
value	AMPInvoiceState	unknown

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

Enums

lnrpc.Invoice.InvoiceState

Name	Number
OPEN	0
SETTLED	1
CANCELED	2
ACCEPTED	3

lnrpc.InvoiceHTLCState

Name	Number
ACCEPTED	0
SETTLED	1
CANCELED	2