GRPC API Examples
4 min
Prerequisites:
- Admin Macaroon - The admin macaroon is an authentication token that allows you to interact with your LND node's gRPC API with administrative permissions. You can also grab a "Read Only" macaroon that wont have permissions to spend. You can find your Macaroons in your Voltage Dashboard by visiting Manage Access -> Macaroon Bakery
- Lightning.proto File - The lightning.proto file is a Protocol Buffers (protobuf) definition file that defines the gRPC service and messages used to interact with an LND node. It specifies the methods available for communication, as well as the structure of the request and response messages. This file is essential for generating the client and server code needed to use the gRPC API. You can download the lightning.proto file from the LND GitHub repository: LND GitHub - lnrpc directory
Interacting With Your Node's LND gRPC API
Here are some code snippets demonstrating how to interact with some of the most common and popular LND API methods using the gRPC API:
const fs = require('fs');
const grpc = require('@grpc/grpc-js');
const protoLoader = require('@grpc/proto-loader');
const loaderOptions = {
keepCase: true,
longs: String,
enums: String,
defaults: true,
oneofs: true
};
const packageDefinition = protoLoader.loadSync('lightning.proto', loaderOptions);
async function main() {
process.env.GRPC_SSL_CIPHER_SUITES = 'HIGH+ECDSA';
let m = fs.readFileSync('~/path/to/admin.macaroon');
let macaroon = m.toString('hex');
// build meta data credentials
let metadata = new grpc.Metadata();
metadata.add('macaroon', macaroon);
let macaroonCreds = grpc.credentials.createFromMetadataGenerator((args, callback) => {
callback(null, metadata);
});
// build ssl credentials without needing to pass in the cert
const sslCreds = grpc.credentials.createSsl();
// combine the cert credentials and the macaroon auth credentials
// such that every call is properly encrypted and authenticated
let credentials = grpc.credentials.combineChannelCredentials(sslCreds, macaroonCreds);
// Pass the credentials when creating a channel
let lnrpcDescriptor = grpc.loadPackageDefinition(packageDefinition);
let lnrpc = lnrpcDescriptor.lnrpc;
let client = new lnrpc.Lightning('node-name.m.voltageapp.io:10009', credentials);
client.getInfo({}, (err, response) => {
if (err) {
console.log('Error: ' + err);
}
console.log('GetInfo:', response);
});
}
main();const fs = require('fs');
const grpc = require('@grpc/grpc-js');
const protoLoader = require('@grpc/proto-loader');
const loaderOptions = {
keepCase: true,
longs: String,
enums: String,
defaults: true,
oneofs: true
};
const packageDefinition = protoLoader.loadSync('lightning.proto', loaderOptions);
async function main() {
process.env.GRPC_SSL_CIPHER_SUITES = 'HIGH+ECDSA';
let m = fs.readFileSync('~/path/to/admin.macaroon');
let macaroon = m.toString('hex');
// build meta data credentials
let metadata = new grpc.Metadata();
metadata.add('macaroon', macaroon);
let macaroonCreds = grpc.credentials.createFromMetadataGenerator((args, callback) => {
callback(null, metadata);
});
// build ssl credentials without needing to pass in the cert
const sslCreds = grpc.credentials.createSsl();
// combine the cert credentials and the macaroon auth credentials
// such that every call is properly encrypted and authenticated
let credentials = grpc.credentials.combineChannelCredentials(sslCreds, macaroonCreds);
// Pass the credentials when creating a channel
let lnrpcDescriptor = grpc.loadPackageDefinition(packageDefinition);
let lnrpc = lnrpcDescriptor.lnrpc;
let client = new lnrpc.Lightning('node-name.m.voltageapp.io:10009', credentials);
let request = {
value: 1000, // Invoice amount in satoshis
memo: 'Test invoice', // Optional memo for the invoice
};
client.addInvoice(request, (err, response) => {
if (err) {
console.log('Error: ' + err);
}
console.log('Invoice:', response);
});
}
main();SendPaymentSync - https://lightning.engineering/api-docs/api/lnd/lightning/send-payment-sync
const fs = require('fs');
const grpc = require('@grpc/grpc-js');
const protoLoader = require('@grpc/proto-loader');
const loaderOptions = {
keepCase: true,
longs: String,
enums: String,
defaults: true,
oneofs: true
};
const packageDefinition = protoLoader.loadSync('lightning.proto', loaderOptions);
async function main() {
process.env.GRPC_SSL_CIPHER_SUITES = 'HIGH+ECDSA';
let m = fs.readFileSync('~/path/to/admin.macaroon');
let macaroon = m.toString('hex');
// build meta data credentials
let metadata = new grpc.Metadata();
metadata.add('macaroon', macaroon);
let macaroonCreds = grpc.credentials.createFromMetadataGenerator((args, callback) => {
callback(null, metadata);
});
// build ssl credentials without needing to pass in the cert
const sslCreds = grpc.credentials.createSsl();
// combine the cert credentials and the macaroon auth credentials
// such that every call is properly encrypted and authenticated
let credentials = grpc.credentials.combineChannelCredentials(sslCreds, macaroonCreds);
// Pass the credentials when creating a channel
let lnrpcDescriptor = grpc.loadPackageDefinition(packageDefinition);
let lnrpc = lnrpcDescriptor.lnrpc;
let client = new lnrpc.Lightning('node-name.m.voltageapp.io:10009', credentials);
let request = {
payment_request: 'lnbc...', // Paste the invoice's payment request here
amt: 1000, // Amount to pay in satoshis
};
client.sendPaymentSync(request, (err, response) => {
if (err) {
console.log('Error: ' + err);
}
console.log('Payment:', response);
});
}
main();This script demonstrates how to make three different API calls to your LND node using the gRPC API:
- getInfo: Retrieves general information about your node.
- addInvoice: Creates a new invoice with a specified amount and optional memo.
- sendPaymentSync: Pays an invoice by providing the payment request and the amount to pay.
Make sure to replace the placeholders in the script with your actual macaroon file path, TLS certificate path, node URL, and the desired invoice details.