Launch Week Day 5: Introducing Reachability for PHP.Learn More →

Book a Demo Sign in

lnurl

Package Overview

Advanced tools

Install Socket

Detect and block malicious and high-risk dependencies

Install

lnurl

LNURL implementation for Python.

PyPI

Version: 2.0.1

Maintainers: 3

LNURL implementation for Python

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

LUDS support

Check out the LUDS repository: luds

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.query  # "q=3fc3645b439ce8e7"
lnurl.url.query_params()  # [("q", "3fc3645b439ce8e7")]
dict(lnurl.url.query_params())  # {"q": "3fc3645b439ce8e7"}

query_params() returns a list of (key, value) tuples so query parameters stay lossless and ordered. Use dict(...) when you want convenient mapping-style access and duplicate keys do not matter.

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][lnurl-spec] have a different model with different properties (see models.py):

import httpx

from lnurl import Lnurl, LnurlResponse

lnurl = Lnurl('LNURL1DP68GURN8GHJ7MRWW4EXCTNZD9NHXATW9EU8J730D3H82UNV94MKJARGV3EXZAELWDJHXUMFDAHR6WFHXQERSVPCA649RV')
try:
  async with httpx.AsyncClient() as client:
    r = await client.get(lnurl.url)
    res = LnurlResponse.from_dict(r.json())  # LnurlPayResponse
    res.ok  # bool
    res.maxSendable  # int
    res.max_sats  # int
    res.callback.host  # str
    res.callback.query_params()  # list[tuple] [("amount", "1000")]
    dict(res.callback.query_params())  # dict
    res.metadata  # str
    res.metadata.list()  # list
    res.metadata.text  # str
    res.metadata.images  # list
r = requests.get(lnurl.url)

If you have already httpx 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'), minSendable=10000, maxSendable=10000, metadata=LnurlPayMetadata('[["text/plain","NgHaEyaZNDnW iI DsFYdkI"],["image/png;base64","iVBOR...uQmCC"]]'))

You can execute and LNURL with either payRequest, withdrawRequest or login tag using the execute function.

>>> import lnurl
>>> lnurl.execute('lightning:LNURL1DP68GURN8GHJ7MRWW4EXCTNZD9NHXATW9EU8J730D3H82UNV94CXZ7FLWDJHXUMFDAHR6V33XCUNSVE38QV6UF', 100000)

Building your own LNURL responses

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

from lnurl import CallbackUrl, LnurlWithdrawResponse, MilliSatoshi
from pydantic import TypeAdapter, ValidationError
try:
    res = LnurlWithdrawResponse(
        callback=TypeAdapter(CallbackUrl).validate_python("https://lnurl.bigsun.xyz/lnurl-withdraw/callback/9702808"),
        k1="38d304051c1b76dcd8c5ee17ee15ff0ebc02090c0afbc6c98100adfa3f920874",
        minWithdrawable=MilliSatoshi(1000),
        maxWithdrawable=MilliSatoshi(1000000),
        defaultDescription="sample withdraw",
    )
    res.json()  # str
    res.dict()  # dict
except ValidationError as e:
    print(e.json())

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. Use the LNURL spec field names when parsing and exporting response models.

Will throw and ValidationError if the data is not valid, so you can catch it and return an error response.

CLI

$ uv run lnurl
Usage: lnurl [OPTIONS] COMMAND [ARGS]...

  Python CLI for LNURL decode and encode lnurls

Options:
  --help  Show this message and exit.

Commands:
  decode           decode a LNURL
  encode           encode a URL
  handle           handle a LNURL
  execute          execute a LNURL

FAQs

What is lnurl?

Is lnurl well maintained?

Did you know?

Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.

Install