lnd-grpc

library0.5.4jsnpmunverified

A gRPC wrapper for LND (Lightning Network Daemon) that provides easy-to-use async/promise support, automatic version detection, and supports all lnd gRPC sub-services. Version 0.5.4 is stable and actively maintained. Key differentiators include automatic lnd version detection and lndconnect URI support, making it simpler than using raw gRPC libraries. It bundles protobuf definitions for various lnd versions and handles TLS/macaroon authentication. Released under MIT license by LN-Zap.

payments

npm install lnd-grpc

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · LND-GRPC

lnd-grpc

paymentsjavascriptv0.5.4

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

LndGrpc

✓ import LndGrpc from 'lnd-grpc'

✗ const LndGrpc = require('lnd-grpc')

Default export as ESM since v0.4; CommonJS require() works but may lack type definitions.

LndGrpc

✓ import LndGrpc from 'lnd-grpc'

✗ import { LndGrpc } from 'lnd-grpc'

Named import is incorrect; only default export is provided.

LndGrpc

✓ const LndGrpc = require('lnd-grpc').default

✗ const LndGrpc = require('lnd-grpc')

If using CommonJS with transpilation, you may need .default due to ESM interop.

Initializes and connects to an lnd node using environment variables, then fetches node info via the Lightning service.

import LndGrpc from 'lnd-grpc'; const grpc = new LndGrpc({ host: process.env.LND_HOST || 'localhost:10009', cert: process.env.LND_CERT || '~/.lnd/tls.cert', macaroon: process.env.LND_MACAROON || '~/.lnd/data/chain/bitcoin/mainnet/admin.macaroon', }); grpc.connect() .then(() => { console.log('Connected to lnd'); return grpc.services.Lightning.getInfo({}); }) .then(res => console.log('Node info:', res.toObject())) .catch(err => console.error('Error:', err));

Debug

Known issues

breakingVersion 0.4.0 changed the import from named to default export. Code using `import { LndGrpc }` will break.

fix

Use `import LndGrpc from 'lnd-grpc'` instead.

affects: <0.4.0

gotchaThe `connect` method may hang indefinitely if the lnd node is unreachable or not unlocked. No timeout is set by default.

fix

Use `waitForCert` and `waitForMacaroon` options to set timeouts, or implement your own timeout wrapper.

affects: >=0.0.0

deprecatedThe `grpc` package used as a dependency is deprecated in favor of `@grpc/grpc-js`. Future versions may switch.

fix

Monitor releases for migration to `@grpc/grpc-js`.

affects: >=0.0.0

gotchaMacaroon paths are resolved relative to process.cwd(), not home directory. Using '~/.lnd/...' may fail if shell expansion is not applied.

fix

Use absolute paths or `path.resolve(os.homedir(), '.lnd/...')`.

affects: >=0.0.0

gotchaThe `version` option must match exactly the lnd version string (e.g., '0.6.0-beta') or it will be ignored.

fix

Check the lnd version with `lncli getinfo` and pass the exact string.

affects: >=0.0.0

Errors

Common errors & fixes

Error: 14 UNAVAILABLE: failed to connect to all addresses

LND node is not running or unreachable, or TLS certificate mismatch.

fix

Ensure LND is running and `host` is correct. Verify TLS certificate path is valid.

TypeError: LndGrpc is not a constructor

Incorrect import style (e.g., named import instead of default import) or CommonJS without .default.

fix

Use `import LndGrpc from 'lnd-grpc'` or `const LndGrpc = require('lnd-grpc').default`.

Error: ENOENT: no such file or directory, open 'macaroon'

Macaroon file path does not exist, possibly because the wallet hasn't been created or path is wrong.

fix

Ensure wallet is initialized and provide correct path. Use `waitForMacaroon` if wallet is created after startup.

TypeError: Cannot read property 'getInfo' of undefined

Services object is not initialized because `connect()` hasn't been called or failed.

fix

Ensure `await grpc.connect()` resolves before accessing `grpc.services.Lightning`.

Upgrade

Version history

0.5.4latest on npm

Audit

Dependencies

grpcrequiredCore gRPC library for Node.js

lndconnectoptionalParsing lndconnect URIs

Agent activity

37 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/LN-Zap/node-lnd-grpc ↗

packagelnd-grpc ↗

homepagehttps://github.com/LN-Zap/node-lnd-grpc ↗