Skip to main content
Python Software Foundation 20th Year Anniversary Fundraiser  Donate today!

LNURL implementation for Python.

Project description

LNURL implementation for Python

github-tests-badge github-mypy-badge codecov-badge pypi-badge pypi-versions-badge license-badge

A collection of helpers for building LNURL support into wallets and services.

Configuration

Developers can force strict RFC3986 validation for the URLs that the library encodes/decodes, using this env var:

LNURL_STRICT_RFC3986 = "0" by default (False)

Basic usage

>>> import lnurl
>>> lnurl.encode('https://service.io/?q=3fc3645b439ce8e7')
Lnurl('LNURL1DP68GURN8GHJ7UM9WFMXJCM99E5K7TELWY7NXENRXVMRGDTZXSENJCM98PJNWXQ96S9', bech32=Bech32('LNURL1DP68GURN8GHJ7UM9WFMXJCM99E5K7TELWY7NXENRXVMRGDTZXSENJCM98PJNWXQ96S9', hrp='lnurl', data=[13, 1, 26, 7, 8, 28, 3, 19, 7, 8, 23, 18, 30, 28, 27, 5, 14, 9, 27, 6, 18, 24, 27, 5, 5, 25, 20, 22, 30, 11, 25, 31, 14, 4, 30, 19, 6, 25, 19, 3, 6, 12, 27, 3, 8, 13, 11, 2, 6, 16, 25, 19, 18, 24, 27, 5, 7, 1, 18, 19, 14]), url=WebUrl('https://service.io/?q=3fc3645b439ce8e7', scheme='https', host='service.io', tld='io', host_type='domain', path='/', query='q=3fc3645b439ce8e7'))
>>> lnurl.decode('LNURL1DP68GURN8GHJ7UM9WFMXJCM99E5K7TELWY7NXENRXVMRGDTZXSENJCM98PJNWXQ96S9')
WebUrl('https://service.io/?q=3fc3645b439ce8e7', scheme='https', host='service.io', tld='io', host_type='domain', path='/', query='q=3fc3645b439ce8e7')

The Lnurl object wraps a bech32 LNURL to provide some extra utilities.

from lnurl import Lnurl

lnurl = Lnurl("LNURL1DP68GURN8GHJ7UM9WFMXJCM99E5K7TELWY7NXENRXVMRGDTZXSENJCM98PJNWXQ96S9")
lnurl.bech32  # "LNURL1DP68GURN8GHJ7UM9WFMXJCM99E5K7TELWY7NXENRXVMRGDTZXSENJCM98PJNWXQ96S9"
lnurl.bech32.hrp  # "lnurl"
lnurl.url  # "https://service.io/?q=3fc3645b439ce8e7"
lnurl.url.host  # "service.io"
lnurl.url.base  # "https://service.io/"
lnurl.url.query  # "q=3fc3645b439ce8e7"
lnurl.url.query_params  # {"q": "3fc3645b439ce8e7"}

Parsing LNURL responses

You can use a LnurlResponse to wrap responses you get from a LNURL. The different types of responses defined in the LNURL spec have a different model with different properties (see models.py):

import requests

from lnurl import Lnurl, LnurlResponse

lnurl = Lnurl('LNURL1DP68GURN8GHJ7MRWW4EXCTNZD9NHXATW9EU8J730D3H82UNV94MKJARGV3EXZAELWDJHXUMFDAHR6WFHXQERSVPCA649RV')
r = requests.get(lnurl.url)

res = LnurlResponse.from_dict(r.json())  # LnurlPayResponse
res.ok  # bool
res.max_sendable  # int
res.max_sats  # int
res.callback.base  # str
res.callback.query_params # dict
res.metadata  # str
res.metadata.list()  # list
res.metadata.text  # str
res.metadata.images  # list

If you have already requests installed, you can also use the .handle() function directly. It will return the appropriate response for a LNURL.

>>> import lnurl
>>> lnurl.handle('lightning:LNURL1DP68GURN8GHJ7MRWW4EXCTNZD9NHXATW9EU8J730D3H82UNV94CXZ7FLWDJHXUMFDAHR6V33XCUNSVE38QV6UF')
LnurlPayResponse(tag='payRequest', callback=WebUrl('https://lnurl.bigsun.xyz/lnurl-pay/callback/2169831', scheme='https', host='lnurl.bigsun.xyz', tld='xyz', host_type='domain', path='/lnurl-pay/callback/2169831'), min_sendable=10000, max_sendable=10000, metadata=LnurlPayMetadata('[["text/plain","NgHaEyaZNDnW iI DsFYdkI"],["image/png;base64","iVBOR...uQmCC"]]'))

Building your own LNURL responses

For LNURL services, the lnurl package can be used to build valid responses.

from lnurl import LnurlWithdrawResponse

res = LnurlWithdrawResponse(
    callback="https://lnurl.bigsun.xyz/lnurl-withdraw/callback/9702808",
    k1="38d304051c1b76dcd8c5ee17ee15ff0ebc02090c0afbc6c98100adfa3f920874",
    min_withdrawable=551000,
    max_withdrawable=551000,
    default_description="sample withdraw",
)
res.json()  # str
res.dict()  # dict

All responses are pydantic models, so the information you provide will be validated and you have access to .json() and .dict() methods to export the data.

Data is exported using :camel: camelCase keys by default, as per spec. You can also use camelCases when you parse the data, and it will be converted to snake_case to make your Python code nicer.

If you want to export the data using :snake: snake_case (in your Python code, for example), you can change the by_alias parameter: res.dict(by_alias=False) (it is True by default).

Project details


Download files

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

Files for lnurl, version 0.3.6
Filename, size File type Python version Upload date Hashes
Filename, size lnurl-0.3.6-py3-none-any.whl (10.3 kB) File type Wheel Python version py3 Upload date Hashes View
Filename, size lnurl-0.3.6.tar.gz (9.2 kB) File type Source Python version None Upload date Hashes View

Supported by

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