Skip to main content

An LND gRPC client for Python 3

Project description


A simple library to provide a Python 3 interface to the lnd lightning client gRPC.

This version of the library has been compiled with rpc.proto from the v0.5.1-beta tag on github

Install requires:

  • grpcio
  • grpcio-tools
  • googleapis-common-protos
  • codecs

Note: Configuration for coins other than bitcoin will require modifying the source code directly.

Installation via pip

pip install lnd-grpc

Bitcoin setup

bitcoind or btcd must be running and be ready to accept rpc connections from lnd.

LND setup

lnd daemon must be running on the host machine. This can typically be accomplished in a screen/tmux session.

If lnd.conf is not already configured to communicate with your bitcoin client, an example lnd daemon startup command for bitcoind connection might look like:

lnd \
--bitcoin.mainnet \
--debuglevel=debug \
--bitcoin.node=bitcoind \
--bitcoind.rpcuser=xxxxx \
--bitcoind.rpcpass=xxxxxxxxxxxxxx \
--externalip=xx.xx.xx.xx \
--bitcoind.zmqpubrawblock=tcp://host:port \
--bitcoind.zmqpubrawtx=tcp://host:port \


Import the module into your project:

from lnd_grpc import lnd_grpc

Create an instance of the client class:

rpc = lnd_grpc.Client()

Note: The class is instantiated to work with default bitcoind rpc port and lnd in default installation path unless additional arguments are passed.

The class instantiation takes the the following arguments which you can change as required by your bitcoin node setup:

    lnd_dir: str = None, \
    macaroon_path: str = None, \
    network: str = 'mainnet', \
    grpc_host: str = 'localhost', \
    grpc_port: str = '10009'

Initialization of a new lnd installation

Note: If you have already created a wallet during lnd setup/installation you can skip this section.

If this is the first time you have run lnd you will not have a wallet created. 'Macaroons', the authentication technique used to communicate securely with lnd, are tied to a wallet (seed) and therefore an alternative connection must be made with lnd to create the wallet, before recreating the connection stub using the wallet's macaroon.

Initialization requires the following steps:

  1. Generate a new seed rpc.gen_seed()
  2. Initialize a new wallet rpc.init_wallet()

These steps have been combined into a helper function which does not exist in the lnd gRPC, called 'initialize', which you can simply run passing it the arguments for those 2 functions to it. E.g.:

rpc.initialize(aezeed_passphrase:str = 'xxxxx' (optional),
               wallet_password:str = 'xxxxx',
               recovery_window: int = xxxxx (optional),
               seed_entropy: '16 bytes' = xxxxx (optional)

Wallet_password must be at least 8 characters long.

The helper function will return the cipher_seed_mnemonic and the enciphered_seed in case these were not provided and therefore were auto-generated.

Connecting and re-connecting after wallet created

If you did not run the initialization sequence above, you will only need to unlock your wallet before issuing further RPC commands:


General usage

Further RPC commands can then be issued to the lnd gRPC interface using the following convention, where gRPC commands are converted from CamelCase to lowercase_with_underscores and keyword arguments named to exactly match the parameters the gRPC uses:


Valid gRPC commands and their keyword arguments can be found here

Additional Notes

This library does not handle any errors directly, except for notifying the user of missing tls certificate or macaroon .

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

lnd_grpc-0.2.1.tar.gz (41.4 kB view hashes)

Uploaded source

Built Distribution

lnd_grpc-0.2.1-py3-none-any.whl (41.9 kB view hashes)

Uploaded py3

Supported by

AWS AWS Cloud computing Datadog Datadog Monitoring Facebook / Instagram Facebook / Instagram PSF Sponsor Fastly Fastly CDN Google Google Object Storage and Download Analytics Huawei Huawei PSF Sponsor Microsoft Microsoft PSF Sponsor NVIDIA NVIDIA PSF Sponsor Pingdom Pingdom Monitoring Salesforce Salesforce PSF Sponsor Sentry Sentry Error logging StatusPage StatusPage Status page