{"id":25891649,"url":"https://github.com/lnbits/lnurl","last_synced_at":"2025-04-13T08:18:24.150Z","repository":{"id":45048800,"uuid":"223287658","full_name":"lnbits/lnurl","owner":"lnbits","description":"LNURL implementation for Python.","archived":false,"fork":false,"pushed_at":"2025-04-07T09:49:16.000Z","size":401,"stargazers_count":65,"open_issues_count":2,"forks_count":18,"subscribers_count":4,"default_branch":"main","last_synced_at":"2025-04-13T08:18:07.587Z","etag":null,"topics":["lightning-network","lnurl","pydantic","python","python-package"],"latest_commit_sha":null,"homepage":"https://pypi.org/project/lnurl","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/lnbits.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null}},"created_at":"2019-11-22T00:01:55.000Z","updated_at":"2025-04-07T09:49:07.000Z","dependencies_parsed_at":"2024-04-23T21:18:52.244Z","dependency_job_id":"42d63dd6-285d-4722-8c67-f70541ed0cc7","html_url":"https://github.com/lnbits/lnurl","commit_stats":{"total_commits":49,"total_committers":6,"mean_commits":8.166666666666666,"dds":0.2857142857142857,"last_synced_commit":"8a19209f445a9861e1e04a48d9f7b55dee631e55"},"previous_names":[],"tags_count":23,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lnbits%2Flnurl","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lnbits%2Flnurl/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lnbits%2Flnurl/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lnbits%2Flnurl/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/lnbits","download_url":"https://codeload.github.com/lnbits/lnurl/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248681519,"owners_count":21144703,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["lightning-network","lnurl","pydantic","python","python-package"],"created_at":"2025-03-02T20:29:00.864Z","updated_at":"2025-04-13T08:18:24.143Z","avatar_url":"https://github.com/lnbits.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"LNURL implementation for Python\n===============================\n\n[![github-tests-badge]][github-tests]\n[![github-mypy-badge]][github-mypy]\n[![codecov-badge]][codecov]\n[![pypi-badge]][pypi]\n[![pypi-versions-badge]][pypi]\n[![license-badge]](LICENSE)\n\n\nA collection of helpers for building [LNURL][lnurl] support into wallets and services.\n\n\nLUDS support\n------------\n\nCheck out the LUDS repository: [luds](https://github.com/lnurl/luds/)\n\n- [x] LUD-01 - Base LNURL encoding and decoding\n- [x] LUD-02 - channelRequest base spec\n- [x] LUD-03 - withdrawRequest base spec\n- [x] LUD-04 - Auth base spec\n- [x] LUD-05 - BIP32-based seed generation for auth protocol\n- [x] LUD-06 - payRequest base spec\n- [x] LUD-07 - hostedChannelRequest base spec\n- [x] LUD-08 - Fast withdrawRequest\n- [x] LUD-09 - successAction field for payRequest\n- [x] LUD-10 - aes success action in payRequest\n- [x] LUD-11 - Disposable and storeable payRequests\n- [x] LUD-12 - Comments in payRequest\n- [x] LUD-13 - signMessage-based seed generation for auth protocol\n- [x] LUD-14 - balanceCheck: reusable withdrawRequests\n- [x] LUD-15 - balanceNotify: services hurrying up the withdraw process\n- [x] LUD-16 - Paying to static internet identifiers\n- [x] LUD-17 - Scheme prefixes and raw (non bech32-encoded) URLs\n- [x] LUD-18 - Payer identity in payRequest protocol\n- [x] LUD-19 - Pay link discoverable from withdraw link\n- [x] LUD-20 - Long payment description for pay protocol\n- [x] LUD-21 - verify LNURL-pay payments\n\n\nConfiguration\n-------------\n\nDevelopers can force strict RFC3986 validation for the URLs that the library encodes/decodes, using this env var:\n\n\u003e LNURL_STRICT_RFC3986 = \"0\" by default (False)\n\n\nBasic usage\n-----------\n\n```python\n\u003e\u003e\u003e import lnurl\n\u003e\u003e\u003e lnurl.encode('https://service.io/?q=3fc3645b439ce8e7')\nLnurl('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'))\n\u003e\u003e\u003e lnurl.decode('LNURL1DP68GURN8GHJ7UM9WFMXJCM99E5K7TELWY7NXENRXVMRGDTZXSENJCM98PJNWXQ96S9')\nWebUrl('https://service.io/?q=3fc3645b439ce8e7', scheme='https', host='service.io', tld='io', host_type='domain', path='/', query='q=3fc3645b439ce8e7')\n```\n\nThe `Lnurl` object wraps a bech32 LNURL to provide some extra utilities.\n\n```python\nfrom lnurl import Lnurl\n\nlnurl = Lnurl(\"LNURL1DP68GURN8GHJ7UM9WFMXJCM99E5K7TELWY7NXENRXVMRGDTZXSENJCM98PJNWXQ96S9\")\nlnurl.bech32  # \"LNURL1DP68GURN8GHJ7UM9WFMXJCM99E5K7TELWY7NXENRXVMRGDTZXSENJCM98PJNWXQ96S9\"\nlnurl.bech32.hrp  # \"lnurl\"\nlnurl.url  # \"https://service.io/?q=3fc3645b439ce8e7\"\nlnurl.url.host  # \"service.io\"\nlnurl.url.base  # \"https://service.io/\"\nlnurl.url.query  # \"q=3fc3645b439ce8e7\"\nlnurl.url.query_params  # {\"q\": \"3fc3645b439ce8e7\"}\n```\n\nParsing LNURL responses\n-----------------------\n\nYou can use a `LnurlResponse` to wrap responses you get from a LNURL.\nThe different types of responses defined in the [LNURL spec][lnurl-spec] have a different model\nwith different properties (see `models.py`):\n\n```python\nimport httpx\n\nfrom lnurl import Lnurl, LnurlResponse\n\nlnurl = Lnurl('LNURL1DP68GURN8GHJ7MRWW4EXCTNZD9NHXATW9EU8J730D3H82UNV94MKJARGV3EXZAELWDJHXUMFDAHR6WFHXQERSVPCA649RV')\ntry:\n  async with httpx.AsyncClient() as client:\n    r = await client.get(lnurl.url)\n    res = LnurlResponse.from_dict(r.json())  # LnurlPayResponse\n    res.ok  # bool\n    res.max_sendable  # int\n    res.max_sats  # int\n    res.callback.base  # str\n    res.callback.query_params # dict\n    res.metadata  # str\n    res.metadata.list()  # list\n    res.metadata.text  # str\n    res.metadata.images  # list\nr = requests.get(lnurl.url)\n```\n\nIf you have already `httpx` installed, you can also use the `.handle()` function directly.\nIt will return the appropriate response for a LNURL.\n\n```python\n\u003e\u003e\u003e import lnurl\n\u003e\u003e\u003e lnurl.handle('lightning:LNURL1DP68GURN8GHJ7MRWW4EXCTNZD9NHXATW9EU8J730D3H82UNV94CXZ7FLWDJHXUMFDAHR6V33XCUNSVE38QV6UF')\nLnurlPayResponse(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\"]]'))\n```\n\nYou can execute and LNURL with either payRequest, withdrawRequest or login tag using the `execute` function.\n```python\n\u003e\u003e\u003e import lnurl\n\u003e\u003e\u003e lnurl.execute('lightning:LNURL1DP68GURN8GHJ7MRWW4EXCTNZD9NHXATW9EU8J730D3H82UNV94CXZ7FLWDJHXUMFDAHR6V33XCUNSVE38QV6UF', 100000)\n```\n\nBuilding your own LNURL responses\n---------------------------------\n\nFor LNURL services, the `lnurl` package can be used to build **valid** responses.\n\n```python\nfrom lnurl import LnurlWithdrawResponse\n\nres = LnurlWithdrawResponse(\n    callback=\"https://lnurl.bigsun.xyz/lnurl-withdraw/callback/9702808\",\n    k1=\"38d304051c1b76dcd8c5ee17ee15ff0ebc02090c0afbc6c98100adfa3f920874\",\n    min_withdrawable=551000,\n    max_withdrawable=551000,\n    default_description=\"sample withdraw\",\n)\nres.json()  # str\nres.dict()  # dict\n```\n\nAll responses are [`pydantic`][pydantic] models, so the information you provide will be validated and you have\naccess to `.json()` and `.dict()` methods to export the data.\n\n**Data is exported using :camel: camelCase keys by default, as per spec.**\nYou can also use camelCases when you parse the data, and it will be converted to snake_case to make your\nPython code nicer.\n\nIf you want to export the data using :snake: snake_case (in your Python code, for example), you can change\nthe `by_alias` parameter: `res.dict(by_alias=False)` (it is `True` by default).\n\n\n[github-tests]: https://github.com/lnbits/lnurl/actions?query=workflow%3Atests\n[github-tests-badge]: https://github.com/lnbits/lnurl/workflows/tests/badge.svg\n[github-mypy]: https://github.com/lnbits/lnurl/actions?query=workflow%3Amypy\n[github-mypy-badge]: https://github.com/lnbits/lnurl/workflows/mypy/badge.svg\n[codecov]: https://codecov.io/gh/lnbits/lnurl\n[codecov-badge]: https://codecov.io/gh/lnbits/lnurl/branch/master/graph/badge.svg\n[pypi]: https://pypi.org/project/lnurl/\n[pypi-badge]: https://badge.fury.io/py/lnurl.svg\n[pypi-versions-badge]: https://img.shields.io/pypi/pyversions/lnurl.svg\n[license-badge]: https://img.shields.io/badge/license-MIT-blue.svg\n\n\nCLI\n---------\n```console\n$ poetry run lnurl\nUsage: lnurl [OPTIONS] COMMAND [ARGS]...\n\n  Python CLI for LNURL decode and encode lnurls\n\nOptions:\n  --help  Show this message and exit.\n\nCommands:\n  decode           decode a LNURL\n  encode           encode a URL\n  handle           handle a LNURL\n  execute          execute a LNURL\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flnbits%2Flnurl","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flnbits%2Flnurl","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flnbits%2Flnurl/lists"}