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>,
};
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>,
)
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> 
};
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>,
}
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 3600 seconds (1 hour) is implied. (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.
   

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

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 value should be used in all payments for this invoice as we require it for end to end security.	bytes	string

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