Skip to content

update lnurlp extension docs #19

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
talvasconcelos wants to merge 1 commit into
base: main
Choose a base branch
from
Open

update lnurlp extension docs #19

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
140 changes: 121 additions & 19 deletions docs/extensions/lnurlp/api.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,48 +12,150 @@ These are auto-generated from your running version and always up to date.

## Base URL

```
```text
https://your-lnbits.com/lnurlp/api/v1/
```

## Authentication

| 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.
Expand Down
129 changes: 88 additions & 41 deletions docs/extensions/lnurlp/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,56 +1,103 @@
<ExtensionHeader
name="LNURLp"
description="Create static LNURL-pay links and branded payment pages."
description="Create static LNURL-pay links, QR codes, and Lightning addresses."
category="Payments & Commerce"
icon="🔗"
repo="lnbits/lnurlp"
/>

## 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

Expand Down