pyln-client: A python client library for lightningd

This package implements the Unix socket based JSON-RPC protocol that lightningd exposes to the rest of the world. It can be used to call arbitrary functions on the RPC interface, and serves as a basis for plugins written in python.

Installation

pyln-client is available on pip:

pip install pyln-client

Alternatively you can also install the development version to get access to currently unreleased features by checking out the Core Lightning source code and installing into your python3 environment:

git clone https://github.com/ElementsProject/lightning.git
cd lightning/contrib/pyln-client
uv sync

This will add links to the library into your environment so changing the checked out source code will also result in the environment picking up these changes. Notice however that unreleased versions may change API without warning, so test thoroughly with the released version.

Examples

Using the JSON-RPC client

"""
Generate invoice on one daemon and pay it on the other
"""
from pyln.client import LightningRpc
import random

# Create two instances of the LightningRpc object using two different Core Lightning daemons on your computer
l1 = LightningRpc("/tmp/lightning1/lightning-rpc")
l5 = LightningRpc("/tmp/lightning5/lightning-rpc")

info5 = l5.getinfo()
print(info5)

# Create invoice for test payment
invoice = l5.invoice(100, "lbl{}".format(random.random()), "testpayment")
print(invoice)

# Get route to l1
route = l1.getroute(info5['id'], 100, 1)
print(route)

# Pay invoice
print(l1.sendpay(route['route'], invoice['payment_hash']))

Writing a plugin

Plugins are programs that lightningd can be configured to execute alongside the main daemon. They allow advanced interactions with and customizations to the daemon.

#!/usr/bin/env python3
from pyln.client import Plugin

plugin = Plugin()

@plugin.method("hello")
def hello(plugin, name="world"):
    """This is the documentation string for the hello-function.

    It gets reported as the description when registering the function
    as a method with `lightningd`.

    If this returns (a dict), that's the JSON "result" returned.  If
    it raises an exception, that causes a JSON "error" return (raising
    pyln.client.RpcException allows finer control over the return).
    """
    greeting = plugin.get_option('greeting')
    s = '{} {}'.format(greeting, name)
    plugin.log(s)
    return s


@plugin.init()
def init(options, configuration, plugin):
    plugin.log("Plugin helloworld.py initialized")
    # This can also return {'disabled': <reason>} to self-disable,
	# but normally it returns None.


@plugin.subscribe("connect")
def on_connect(plugin, connect, **kwargs):
    plugin.log("Received connect event for peer {}".format(connect))


plugin.add_option('greeting', 'Hello', 'The greeting I should use.')
plugin.run()

Release files for pyln-client 26.6.8

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for pyln-client 26.6.8
File	Size	Uploaded
pyln_client-26.6.8.tar.gz	92.5 kB	Sep 22, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for pyln-client 26.6.8
File	Interpreter	ABI	Platform	Reset
pyln_client-26.6.8-py3-none-any.whl 38.0 kB Sep 22, 2026	Python 3	none	any	Details

Total release size: 130.5 kB

Release files / pyln_client-26.6.8.tar.gz

Download URL	pyln_client-26.6.8.tar.gz
Size	92.5 kB
Tags	Source
SHA-256 checksum How to use checksums	`13b2a936a3e50d7a37c5c2b0291e812d082c55db9143593f01f616e3596f6f97`
BLAKE2b-256 checksum How to use checksums	`dcd52e099134935129d0c4ed1a29e46a2fe737cae395f9795fcc6ae40c8c50d3`
Upload date	Sep 22, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`uv/0.12.17 {"installer":{"name":"uv","version":"0.12.17","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"22.04","id":"jammy","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}`

Release files / pyln_client-26.6.8-py3-none-any.whl

Download URL	pyln_client-26.6.8-py3-none-any.whl
Size	38.0 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`367584a32ccee42db387e7b4dfc899dc8685cac609251e409faa4e3ecba19e6c`
BLAKE2b-256 checksum How to use checksums	`d7cd53967e05a16aa867f017815223127cc89b1b31198effaadd35d3fc609582`
Upload date	Sep 22, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`uv/0.12.17 {"installer":{"name":"uv","version":"0.12.17","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"22.04","id":"jammy","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}`