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
- REST
- Shell
- Javascript
- Python
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>,
// }
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>,
# }
- Javascript
- Python
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>
// }
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>,
# }
$ 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 | string | string | body |
r_preimage | bytes | string | body |
r_hash | bytes | string | body |
value | int64 | string | body |
value_msat | int64 | string | body |
settled deprecated | bool | boolean | body |
creation_date | int64 | string | body |
settle_date | int64 | string | body |
payment_request | string | string | body |
description_hash | bytes | string | body |
expiry | int64 | string | body |
fallback_addr | string | string | body |
cltv_expiry | uint64 | string | body |
route_hints | RouteHint[] | array | body |
private | bool | boolean | body |
add_index | uint64 | string | body |
settle_index | uint64 | string | body |
amt_paid | int64 | string | body |
amt_paid_sat | int64 | string | body |
amt_paid_msat | int64 | string | body |
state | InvoiceState | string | body |
htlcs | InvoiceHTLC[] | array | body |
features | FeaturesEntry[] | object | body |
is_keysend | bool | boolean | body |
payment_addr | bytes | string | body |
is_amp | bool | boolean | body |
amp_invoice_state | AmpInvoiceStateEntry[] | object | body |
lnrpc.AddInvoiceResponse
Source: lightning.proto
Field | gRPC Type | REST Type |
---|---|---|
r_hash | bytes | string |
payment_request | string | string |
add_index | uint64 | string |
payment_addr | bytes | string |
Nested Messages
lnrpc.RouteHint
Field | gRPC Type | REST Type |
---|---|---|
hop_hints | HopHint[] | array |
lnrpc.HopHint
Field | gRPC Type | REST Type |
---|---|---|
node_id | string | string |
chan_id | uint64 | string |
fee_base_msat | uint32 | integer |
fee_proportional_millionths | uint32 | integer |
cltv_expiry_delta | uint32 | integer |
lnrpc.InvoiceHTLC
Field | gRPC Type | REST Type |
---|---|---|
chan_id | uint64 | string |
htlc_index | uint64 | string |
amt_msat | uint64 | string |
accept_height | int32 | integer |
accept_time | int64 | string |
resolve_time | int64 | string |
expiry_height | int32 | integer |
state | InvoiceHTLCState | string |
custom_records | CustomRecordsEntry[] | object |
mpp_total_amt_msat | uint64 | string |
amp | 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 | bytes | string |
set_id | bytes | string |
child_index | uint32 | integer |
hash | bytes | string |
preimage | 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 | InvoiceHTLCState | string |
settle_index | uint64 | string |
settle_time | int64 | string |
amt_paid_msat | 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 |