Skip to main content

LookupInvoice

LookupInvoice attempts to look up an invoice according to its payment hash. The passed payment hash must be exactly 32 bytes, if not, an error is returned.

Source: lightning.proto

gRPC

rpc LookupInvoice (PaymentHash) returns (Invoice);

REST

HTTP MethodPath
GET /v1/invoice/{r_hash_str}

Code Samples

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 = {
r_hash_str: <string>,
r_hash: <bytes>,
};
client.lookupInvoice(request, function(err, response) {
console.log(response);
});
// 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>,
// }

Messages

lnrpc.PaymentHash

Source: lightning.proto

FieldgRPC TypeREST TypeREST Placement
r_hash_str
stringstringpath
r_hash
bytesstringquery

lnrpc.Invoice

Source: lightning.proto

FieldgRPC TypeREST Type
memo
stringstring
r_preimage
bytesstring
r_hash
bytesstring
value
int64string
value_msat
int64string
settleddeprecated
boolboolean
creation_date
int64string
settle_date
int64string
payment_request
stringstring
description_hash
bytesstring
expiry
int64string
fallback_addr
stringstring
cltv_expiry
uint64string
route_hints
RouteHint[]array
private
boolboolean
add_index
uint64string
settle_index
uint64string
amt_paid
int64string
amt_paid_sat
int64string
amt_paid_msat
int64string
state
InvoiceStatestring
htlcs
InvoiceHTLC[]array
features
FeaturesEntry[]object
is_keysend
boolboolean
payment_addr
bytesstring
is_amp
boolboolean
amp_invoice_state
AmpInvoiceStateEntry[]object

Nested Messages

lnrpc.RouteHint

FieldgRPC TypeREST Type
hop_hints
HopHint[]array

lnrpc.HopHint

FieldgRPC TypeREST Type
node_id
stringstring
chan_id
uint64string
fee_base_msat
uint32integer
fee_proportional_millionths
uint32integer
cltv_expiry_delta
uint32integer

lnrpc.InvoiceHTLC

FieldgRPC TypeREST Type
chan_id
uint64string
htlc_index
uint64string
amt_msat
uint64string
accept_height
int32integer
accept_time
int64string
resolve_time
int64string
expiry_height
int32integer
state
InvoiceHTLCStatestring
custom_records
CustomRecordsEntry[]object
mpp_total_amt_msat
uint64string
amp
AMPobject

lnrpc.InvoiceHTLC.CustomRecordsEntry

FieldgRPC TypeREST Type
key
uint64unknown
value
bytesunknown

lnrpc.AMP

FieldgRPC TypeREST Type
root_share
bytesstring
set_id
bytesstring
child_index
uint32integer
hash
bytesstring
preimage
bytesstring

lnrpc.Invoice.FeaturesEntry

FieldgRPC TypeREST Type
key
uint32unknown
value
Featureunknown

lnrpc.Feature

FieldgRPC TypeREST Type
name
stringstring
is_required
boolboolean
is_known
boolboolean

lnrpc.Invoice.AmpInvoiceStateEntry

FieldgRPC TypeREST Type
key
stringunknown
value
AMPInvoiceStateunknown

lnrpc.AMPInvoiceState

FieldgRPC TypeREST Type
state
InvoiceHTLCStatestring
settle_index
uint64string
settle_time
int64string
amt_paid_msat
int64string

Enums

lnrpc.Invoice.InvoiceState

NameNumber
OPEN
0
SETTLED
1
CANCELED
2
ACCEPTED
3

lnrpc.InvoiceHTLCState

NameNumber
ACCEPTED
0
SETTLED
1
CANCELED
2