GRPC API Examples

4min
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:
GetInfo - https://lightning.engineering/api-docs/api/lnd/lightning/get-info﻿
JS
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);

  client.getInfo({}, (err, response) => {
    if (err) {
      console.log('Error: ' + err);
    }
    console.log('GetInfo:', response);
  });
}

main();
﻿
AddInvoice - https://lightning.engineering/api-docs/api/lnd/lightning/add-invoice﻿
JS
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();
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﻿
JS
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();
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.
Updated 17 May 2024
Did this page help you?
REST API Examples
Voltage API