AddInvoice

AddInvoice attempts to add a new invoice to the invoice database. Any duplicated invoices are rejected, therefore all invoices must have a unique payment preimage.

Source: lightning.proto

gRPC

rpc AddInvoice (Invoice) returns (AddInvoiceResponse);

REST

HTTP Method	Path
POST	/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 = {
  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>,
};
client.addInvoice(request, function(err, response) {
  console.log(response);
});
// Console output:
//  {
//    "r_hash": <bytes>,
//    "payment_request": <string>,
//    "add_index": <uint64>,
//    "payment_addr": <bytes>,
//  }

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.Invoice(
  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>,
)
response = stub.AddInvoice(request)
print(response)
# {
#    "r_hash": <bytes>,
#    "payment_request": <string>,
#    "add_index": <uint64>,
#    "payment_addr": <bytes>,
# }

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 requestBody = {
  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> 
  is_blinded: <boolean>, // <bool> 
  blinded_path_config: <object>, // <BlindedPathConfig> 
};
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'),
  },
  form: JSON.stringify(requestBody),
}
request.post(options, function(error, response, body) {
  console.log(body);
});
// Console output:
//  {
//    "r_hash": <string>, // <bytes> 
//    "payment_request": <string>, // <string> 
//    "add_index": <string>, // <uint64> 
//    "payment_addr": <string>, // <bytes> 
//  }

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}
data = {
  'memo': <string>,
  'r_preimage': base64.b64encode(<bytes>),
  'r_hash': base64.b64encode(<bytes>),
  'value': <int64>,
  'value_msat': <int64>,
  'settled': <bool>,
  'creation_date': <int64>,
  'settle_date': <int64>,
  'payment_request': <string>,
  'description_hash': base64.b64encode(<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': base64.b64encode(<bytes>),
  'is_amp': <bool>,
  'amp_invoice_state': <AmpInvoiceStateEntry>,
  'is_blinded': <bool>,
  'blinded_path_config': <BlindedPathConfig>,
}
r = requests.post(url, headers=headers, data=json.dumps(data), verify=TLS_PATH)
print(r.json())
# {
#    "r_hash": <bytes>,
#    "payment_request": <string>,
#    "add_index": <uint64>,
#    "payment_addr": <bytes>,
# }

Shell

$ lncli addinvoice --help

NAME:
   lncli addinvoice - Add a new invoice.

USAGE:
   lncli addinvoice [command options] value preimage

CATEGORY:
   Invoices

DESCRIPTION:
   
  Add a new invoice, expressing intent for a future payment.

  Invoices without an amount can be created by not supplying any
  parameters or providing an amount of 0. These invoices allow the payer
  to specify the amount of satoshis they wish to send.

OPTIONS:
   --memo value                     a description of the payment to attach along with the invoice (default="")
   --preimage value                 the hex-encoded preimage (32 byte) which will allow settling an incoming HTLC payable to this preimage. If not set, a random preimage will be created.
   --amt value                      the amt of satoshis in this invoice (default: 0)
   --amt_msat value                 the amt of millisatoshis in this invoice (default: 0)
   --description_hash value         SHA-256 hash of the description of the payment. Used if the purpose of payment cannot naturally fit within the memo. If provided this will be used instead of the description(memo) field in the encoded invoice.
   --fallback_addr value            fallback on-chain address that can be used in case the lightning payment fails
   --expiry value                   the invoice's expiry time in seconds. If not specified, an expiry of 86400 seconds (24 hours) is implied. (default: 0)
   --cltv_expiry_delta value        The minimum CLTV delta to use for the final hop. If this is set to 0, the default value is used. The default value for cltv_expiry_delta is configured by the 'bitcoin.timelockdelta' option. (default: 0)
   --private                        encode routing hints in the invoice with private channels in order to assist the payer in reaching you. If amt and amt_msat are zero, a large number of hints with these channels can be included, which might not be desirable.
   --amp                            creates an AMP invoice. If true, preimage should not be set.
   --blind                          creates an invoice that contains blinded paths. Note that invoices with blinded paths will be signed using a random ephemeral key so as not to reveal the real node ID of this node.
   --min_real_blinded_hops --blind  The minimum number of real hops to use in a blinded path. This option will only be used if --blind has also been set. (default: 0)
   --num_blinded_hops --blind       The number of hops to use for each blinded path included in the invoice. This option will only be used if --blind has also been set. Dummy hops will be used to pad paths shorter than this. (default: 0)
   --max_blinded_paths --blind      The maximum number of blinded paths to add to an invoice. This option will only be used if --blind has also been set. (default: 0)
   --blinded_path_omit_node value   The pub key (in hex) of a node not to use on a blinded path. The flag may be specified multiple times.
   

Messages

lnrpc.Invoice

Source: lightning.proto

Field	gRPC Type	REST Type	REST Placement
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	body
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	body
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	body
value The value of this invoice in satoshis The fields value and value_msat are mutually exclusive.	int64	string	body
value_msat The value of this invoice in millisatoshis The fields value and value_msat are mutually exclusive.	int64	string	body
settleddeprecated Whether this invoice has been fulfilled. The field is deprecated. Use the state field instead (compare to SETTLED).	bool	boolean	body
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	body
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	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. Note: Output only, don't specify for creating an invoice.	string	string	body
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	body
expiry Payment request expiry time in seconds. Default is 86400 (24 hours).	int64	string	body
fallback_addr Fallback on-chain address.	string	string	body
cltv_expiry Delta to use for the time-lock of the CLTV extended to the final hop.	uint64	string	body
route_hints Route hints that can each be individually used to assist in reaching the invoice's destination.	RouteHint[]	array	body
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	body
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	body
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	body
amt_paiddeprecated Deprecated, use amt_paid_sat or amt_paid_msat.	int64	string	body
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	body
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	body
state The state the invoice is in. Note: Output only, don't specify for creating an invoice.	InvoiceState	string	body
htlcs List of HTLCs paying to this invoice [EXPERIMENTAL]. Note: Output only, don't specify for creating an invoice.	InvoiceHTLC[]	array	body
features List of features advertised on the invoice. Note: Output only, don't specify for creating an invoice.	FeaturesEntry[]	object	body
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	body
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	body
is_amp Signals whether or not this is an AMP invoice.	bool	boolean	body
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	body
is_blinded Signals that the invoice should include blinded paths to hide the true identity of the recipient.	bool	boolean	body
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	body

lnrpc.AddInvoiceResponse

Source: lightning.proto

Field	gRPC Type	REST Type
r_hash	bytes	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.	string	string
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.	uint64	string
payment_addr The payment address of the generated invoice. This is also called payment secret in specifications (e.g. BOLT 11). This value should be used in all payments for this invoice as we require it for end to end security.	bytes	string

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