From 93232f15c70600aff0c82ac00c4c7c284e40c724 Mon Sep 17 00:00:00 2001 From: Tiago Vasconcelos Date: Fri, 26 Jun 2026 10:15:11 +0100 Subject: [PATCH] update lnurlp extension docs --- docs/extensions/lnurlp/api.md | 140 +++++++++++++++++++++++++++----- docs/extensions/lnurlp/index.md | 129 +++++++++++++++++++---------- 2 files changed, 209 insertions(+), 60 deletions(-) diff --git a/docs/extensions/lnurlp/api.md b/docs/extensions/lnurlp/api.md index b9ec58d..6a9da34 100644 --- a/docs/extensions/lnurlp/api.md +++ b/docs/extensions/lnurlp/api.md @@ -12,7 +12,7 @@ These are auto-generated from your running version and always up to date. ## Base URL -``` +```text https://your-lnbits.com/lnurlp/api/v1/ ``` @@ -20,40 +20,142 @@ https://your-lnbits.com/lnurlp/api/v1/ | Key Type | Header | Access | |---|---|---| -| **Admin key** | `X-Api-Key` | Full access (create, update, delete) | -| **Invoice key** | `X-Api-Key` | Read-only access (list, get) | +| **Admin key** | `X-Api-Key` | Create, update, delete | +| **Invoice key** | `X-Api-Key` | List and retrieve | +| **Super user/admin session** | Browser session | Extension settings | +| Public | None | Public link and LNURL payment flow | ## Endpoints | Method | Path | Auth | Description | |---|---|---|---| -| `GET` | `/lnurlp/api/v1/` | Invoice | List all items | -| `GET` | `/lnurlp/api/v1/{id}` | Invoice | Get a specific item | -| `POST` | `/lnurlp/api/v1/` | Admin | Create a new item | -| `PUT` | `/lnurlp/api/v1/{id}` | Admin | Update an item | -| `DELETE` | `/lnurlp/api/v1/{id}` | Admin | Delete an item | - -::: info Note -This is the standard CRUD pattern. The actual resource names and additional endpoints may vary. Check the **Swagger UI** on your instance for the exact paths and request/response schemas. -::: +| `GET` | `/lnurlp/api/v1/links` | Invoice | List pay links for the key wallet | +| `GET` | `/lnurlp/api/v1/links?all_wallets=true` | Invoice | List pay links for all wallets owned by the user | +| `GET` | `/lnurlp/api/v1/links/{link_id}` | Invoice | Get a pay link | +| `GET` | `/lnurlp/api/v1/links/public/{link_id}` | Public | Get public pay link details | +| `POST` | `/lnurlp/api/v1/links` | Admin | Create a pay link | +| `PUT` | `/lnurlp/api/v1/links/{link_id}` | Admin | Update a pay link | +| `DELETE` | `/lnurlp/api/v1/links/{link_id}` | Admin | Delete a pay link | +| `GET` | `/lnurlp/{link_id}` | Public | LNURL-pay metadata endpoint | +| `GET` | `/lnurlp/api/v1/lnurl/cb/{link_id}` | Public | LNURL-pay callback that creates the invoice | +| `GET` | `/.well-known/lnurlp/{username}` | Public | Lightning Address lookup | +| `GET` | `/lnurlp/api/v1/well-known/{username}` | Public | Internal Lightning Address lookup endpoint | +| `GET` | `/lnurlp/api/v1/settings` | Admin session | Get or create LNURLp settings | +| `PUT` | `/lnurlp/api/v1/settings` | Admin session | Update LNURLp settings | +| `DELETE` | `/lnurlp/api/v1/settings` | Admin session | Delete LNURLp settings | + +## Pay Link Object + +| Field | Type | Notes | +|---|---|---| +| `id` | string | Pay link ID | +| `wallet` | string | Wallet ID that receives payments | +| `description` | string | Pay link description and invoice memo | +| `min` | number | Minimum amount in sats, or stored fiat minor units when `currency` is set | +| `max` | number | Maximum amount in sats, or stored fiat minor units when `currency` is set | +| `currency` | string or null | Fiat currency code, or null for sats | +| `fiat_base_multiplier` | integer | Usually `100` for fiat cents | +| `comment_chars` | integer | Max payer comment length, `0` disables comments | +| `username` | string or null | Lightning Address username | +| `domain` | string or null | Custom Lightning Address / LNURL domain | +| `zaps` | boolean | Enables NIP-57 zap support | +| `disposable` | boolean | Whether LNURL pay requests are disposable | +| `webhook_url` | string or null | URL called after payment | +| `webhook_headers` | string or null | JSON string for webhook headers | +| `webhook_body` | string or null | JSON string included as webhook body data | +| `success_text` | string or null | Wallet success message after payment | +| `success_url` | string or null | Secure success URL after payment | +| `lnurl` | string | Deprecated bech32 LNURL returned for compatibility | + +## Create or Update a Pay Link + +```json +{ + "wallet": "WALLET_ID", + "description": "Coffee", + "min": 1000, + "max": 1000, + "comment_chars": 100, + "currency": null, + "fiat_base_multiplier": 100, + "username": "coffee", + "domain": "example.com", + "zaps": false, + "disposable": true, + "webhook_url": "https://example.com/webhook", + "webhook_headers": "{\"Authorization\":\"Bearer token\"}", + "webhook_body": "{\"source\":\"lnurlp\"}", + "success_text": "Thanks!", + "success_url": "https://example.com/thanks" +} +``` + +Validation rules: + +- `min` must be less than or equal to `max`. +- Sat amounts must be whole sats when `currency` is not set. +- Fiat amounts are sent as normal decimal values; LNURLp stores them using `fiat_base_multiplier`. +- `success_url` must start with `https://`. +- `username` can contain lowercase `a-z`, `0-9`, `-`, `_`, and `.`. +- `webhook_headers` and `webhook_body` must be valid JSON strings when set. +- If `wallet` is omitted, LNURLp uses the wallet that belongs to the admin key. -## Example +## Examples ```bash -# List items -curl https://your-lnbits.com/lnurlp/api/v1/ \ +# List pay links +curl https://your-lnbits.com/lnurlp/api/v1/links \ -H "X-Api-Key: YOUR_INVOICE_KEY" -# Create item -curl -X POST https://your-lnbits.com/lnurlp/api/v1/ \ +# Create a fixed 1000 sat pay link +curl -X POST https://your-lnbits.com/lnurlp/api/v1/links \ -H "X-Api-Key: YOUR_ADMIN_KEY" \ -H "Content-Type: application/json" \ - -d '{"name": "example"}' + -d '{ + "description": "Coffee", + "min": 1000, + "max": 1000, + "comment_chars": 100, + "disposable": true + }' + +# Get public pay link details +curl https://your-lnbits.com/lnurlp/api/v1/links/public/LINK_ID ``` +## Webhook Payload + +When a paid link has `webhook_url` set, LNURLp sends a `POST` request with payment data: + +```json +{ + "payment_hash": "PAYMENT_HASH", + "payment_request": "BOLT11_INVOICE", + "amount": 1000, + "comment": "Great coffee", + "webhook_data": "optional-data", + "lnurlp": "LINK_ID", + "body": { + "source": "lnurlp" + }, + "zap_receipt": "" +} +``` + +## LNURL Payment Flow + +Wallets use the public LNURL endpoints directly: + +1. `GET /lnurlp/{link_id}` returns LNURL-pay metadata, min/max sendable amount, callback URL, comments, and zap support. +2. `GET /lnurlp/api/v1/lnurl/cb/{link_id}?amount=1000000` creates a BOLT11 invoice for the requested millisatoshi amount. +3. Optional query parameters: + - `comment`: payer comment, limited by `comment_chars` + - `nostr`: NIP-57 zap request + - `webhook_data`: custom data passed through to the webhook payload + ::: tip For AI Agents Fetch the full OpenAPI spec from any running instance: -``` +```text GET https://your-lnbits.com/openapi.json ``` Filter for paths starting with `/lnurlp/` to isolate this extension's endpoints. diff --git a/docs/extensions/lnurlp/index.md b/docs/extensions/lnurlp/index.md index 2063d58..9431693 100644 --- a/docs/extensions/lnurlp/index.md +++ b/docs/extensions/lnurlp/index.md @@ -1,56 +1,103 @@ -## Create a static QR code or LNaddress people can use to pay over Lightning Network +## Features -LNURL is a range of lightning-network standards that allow us to use lightning-network differently. An LNURL-pay is a link that wallets use to fetch an invoice from a server on-demand. The link or QR code is fixed, but each time it is read by a compatible wallet a new invoice is issued by the service and sent to the wallet. +- **Reusable pay links** - one QR code or link can receive many payments +- **Lightning Address** - receive payments at names like `alice@example.com` +- **Fixed or flexible amounts** - set one amount or a min/max range +- **Fiat pricing** - price in a fiat currency and convert to sats at payment time +- **Comments and success messages** - collect a short note and reply after payment +- **Webhooks** - notify another system when a link is paid +- **Nostr zaps** - receive NIP-57 zaps through a pay link -[**Wallets supporting LNURL**](https://github.com/fiatjaf/awesome-lnurl#wallets) +## Overview + +LNURLp creates reusable Lightning payment links. The QR code stays the same, but every time someone scans it with an LNURL-compatible wallet, LNbits creates a fresh invoice for that payment. + +Use LNURLp for donation pages, tip jars, checkout links, printed QR codes, Lightning Addresses, or simple payment pages that do not need a full shop. + +[Wallets supporting LNURL](https://github.com/fiatjaf/awesome-lnurl#wallets) ## Usage -1. Create an LNURLp (New Pay link)\ - ![create lnurlp](https://i.imgur.com/rhUBJFy.jpg) - - select your wallets - - make a small description - - enter amount - - if _Fixed amount_ is unchecked you'll have the option to configure a Max and Min amount - - you can set the currency to something different than sats. For example if you choose EUR, the satoshi amount will be calculated when a user scans the LNURLp - - You can ask the user to send a comment that will be sent along with the payment (for example a comment to a blog post) - - Webhook URL allows to call an URL when the LNURLp is paid - - Success mesage, will send a message back to the user after a successful payment, for example a thank you note - - Success URL, will send back a clickable link to the user. Access to some hidden content, or a download link - -2. Use the shareable link or view the LNURLp you just created\ - ![LNURLp](https://i.imgur.com/C8s1P0Q.jpg) - - you can now open your LNURLp and copy the LNURL, get the shareable link or print it\ - ![view lnurlp](https://i.imgur.com/4n41S7T.jpg) - -3. Optional - add Lightning Address - - attach a username to your lnurlp to create a lightning address - - the LN address format will be username@lnbits-domain-name - - Find out more about the lightning address spec at lightningaddress.com - -## Update your LNURL-pay extension - -Now that the extensions are taken out of core LNbits we can update each extension separately without the need to reload or restart LNbits as a whole. -This new version of the extension will give you the option to add a Lightning Address to each LNURLpay link. - -- Open your LNbits instance as super admin (not as a regular user. You will find the SuperUser-ID in your server logs on restart of LNbits. Use that to bookmark and manage LNbits from there in the future.) - Now lets install the new version of a given extension like extensively [described in this guide](https://github.com/lnbits/lnbits/blob/main/docs/guide/extension-install.md#install-new-extension). In short: -- Go to "Manage extensions", click on "ALL", search for e.g. LNURLp, click on "Manage" -- Open the details of the extension and click on version 0.2.1, click "Install". You´re done! - -- Open the LNURLp extension from the left panel -- If you already have had some LNURLp defined, you can now click on edit and add a LN Address to each. _Note that this will change your QR-Code!_ -- If you didn't create any LNURLp before nothing changed except the window for defining new ones - -Now you can receive sats to your newly created LN address. You will find this info also in the transaction overview for each payment (click on the green arrow). +1. **Create** a new pay link. + + ![Create LNURLp](https://i.imgur.com/rhUBJFy.jpg) + +2. Fill in the basics: + + - Wallet to receive payments + - Description shown to the payer + - Amount, or min/max amount if it is not fixed + - Currency, if you want fiat pricing instead of sats + +3. Open the link details. + + ![LNURLp list](https://i.imgur.com/C8s1P0Q.jpg) + +4. Share the page, copy the LNURL, write it to NFC, or print the QR code. + + ![View LNURLp](https://i.imgur.com/4n41S7T.jpg) + +## Lightning Address + +Add a username to a pay link to create a Lightning Address. + +For example, username `alice` on `example.com` becomes: + +```text +alice@example.com +``` + +You can also set a custom domain on the pay link. Use this when your public Lightning Address domain is different from the LNbits host. + +## Fiat Amounts + +Set a currency such as EUR or USD when you want the payer to pay a fiat-denominated price. LNbits converts the amount to sats when the wallet requests the invoice. + +Use fixed amounts for products or donations with a set price. Use min/max amounts for tips, pay-what-you-want pages, and open donations. + +## Comments and Success Actions + +LNURLp can ask the payer for a short comment. This is useful for names, order notes, blog comments, or donation messages. + +After payment, the payer's wallet can show: + +- A success message +- A secure `https://` success URL + +Use success actions for thank-you notes, download links, gated pages, or next steps after payment. + +## Webhooks + +Add a webhook URL when another app should be notified after a payment. LNURLp sends payment details to the webhook and can include: + +- The payment hash and invoice +- The paid amount +- The payer comment +- Custom webhook data +- Optional custom headers and body data +- Zap receipt data when Nostr zaps are enabled + +## Nostr Zaps + +Enable zaps when the pay link should support [NIP-57](https://nips.nostr.com/57) Nostr zap payments. Admins can set the extension's Nostr private key in the LNURLp settings dialog. + +When a zap payment is paid, LNURLp signs a zap receipt and sends it to the relays from the zap request. + +## Disposable Pay Requests + +LNURLp supports disposable and storeable pay requests. The default is disposable, which is the safest option for normal reusable QR codes and payment pages. + +When enabled, wallets can save the LNURLp or lnaddress, for reuse later. [LUD-11](https://github.com/lnurl/luds/blob/luds/11.md) + +Only change this if you know your wallet or integration needs storeable pay requests. ## API Reference