ListInvoices

ListInvoices returns a list of all the invoices currently stored within the database. Any active debug invoices are ignored. It has full support for paginated responses, allowing users to query for specific invoices through their add_index. This can be done by using either the first_index_offset or last_index_offset fields included in the response as the index_offset of the next request. By default, the first 100 invoices created will be returned. Backwards pagination is also supported through the Reversed flag.

Source: lightning.proto

gRPC

rpc ListInvoices (ListInvoiceRequest) returns (ListInvoiceResponse);

REST

HTTP Method	Path
GET	/v1/invoices

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 = {
  pending_only: <bool>,
  index_offset: <uint64>,
  num_max_invoices: <uint64>,
  reversed: <bool>,
  creation_date_start: <uint64>,
  creation_date_end: <uint64>,
};
client.listInvoices(request, function(err, response) {
  console.log(response);
});
// Console output:
//  {
//    "invoices": <Invoice>,
//    "last_index_offset": <uint64>,
//    "first_index_offset": <uint64>,
//  }

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.ListInvoiceRequest(
  pending_only=<bool>,
  index_offset=<uint64>,
  num_max_invoices=<uint64>,
  reversed=<bool>,
  creation_date_start=<uint64>,
  creation_date_end=<uint64>,
)
response = stub.ListInvoices(request)
print(response)
# {
#    "invoices": <Invoice>,
#    "last_index_offset": <uint64>,
#    "first_index_offset": <uint64>,
# }

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`,
  // 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:
//  {
//    "invoices": <array>, // <Invoice> 
//    "last_index_offset": <string>, // <uint64> 
//    "first_index_offset": <string>, // <uint64> 
//  }

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'
macaroon = codecs.encode(open(MACAROON_PATH, 'rb').read(), 'hex')
headers = {'Grpc-Metadata-macaroon': macaroon}
r = requests.get(url, headers=headers, verify=TLS_PATH)
print(r.json())
# {
#    "invoices": <Invoice>,
#    "last_index_offset": <uint64>,
#    "first_index_offset": <uint64>,
# }

Shell

$ lncli listinvoices --help

NAME:
   lncli listinvoices - List all invoices currently stored within the database. Any active debug invoices are ignored.

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

CATEGORY:
   Invoices

DESCRIPTION:
   
  This command enables the retrieval of all invoices currently stored
  within the database. It has full support for paginationed responses,
  allowing users to query for specific invoices through their add_index.
  This can be done by using either the first_index_offset or
  last_index_offset fields included in the response as the index_offset of
  the next request. Backward pagination is enabled by default to receive
  current invoices first. If you wish to paginate forwards, set the 
  paginate-forwards flag.  If none of the parameters are specified, then 
  the last 100 invoices will be returned.

  For example: if you have 200 invoices, "lncli listinvoices" will return
  the last 100 created. If you wish to retrieve the previous 100, the
  first_offset_index of the response can be used as the index_offset of
  the next listinvoices request.

OPTIONS:
   --pending_only               toggles if all invoices should be returned, or only those that are currently unsettled
   --index_offset value         the index of an invoice that will be used as either the start or end of a query to determine which invoices should be returned in the response (default: 0)
   --max_invoices value         the max number of invoices to return (default: 0)
   --paginate-forwards          if set, invoices succeeding the index_offset will be returned
   --creation_date_start value  timestamp in seconds, if set, filter invoices with creation date greater than or equal to it (default: 0)
   --creation_date_end value    timestamp in seconds, if set, filter invoices with creation date less than or equal to it (default: 0)
   

Messages

lnrpc.ListInvoiceRequest

Source: lightning.proto

Field	gRPC Type	REST Type	REST Placement
pending_only If set, only invoices that are not settled and not canceled will be returned in the response.	bool	boolean	query
index_offset The index of an invoice that will be used as either the start or end of a query to determine which invoices should be returned in the response.	uint64	string	query
num_max_invoices The max number of invoices to return in the response to this query.	uint64	string	query
reversed If set, the invoices returned will result from seeking backwards from the specified index offset. This can be used to paginate backwards.	bool	boolean	query
creation_date_start If set, returns all invoices with a creation date greater than or equal to it. Measured in seconds since the unix epoch.	uint64	string	query
creation_date_end If set, returns all invoices with a creation date less than or equal to it. Measured in seconds since the unix epoch.	uint64	string	query

lnrpc.ListInvoiceResponse

Source: lightning.proto

Field	gRPC Type	REST Type
invoices A list of invoices from the time slice of the time series specified in the request.	Invoice[]	array
last_index_offset The index of the last item in the set of returned invoices. This can be used to seek further, pagination style.	uint64	string
first_index_offset The index of the last item in the set of returned invoices. This can be used to seek backwards, pagination style.	uint64	string

Nested Messages

lnrpc.Invoice

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

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