From dc1d5bd669ee94fd663e4fec912525c18298360e Mon Sep 17 00:00:00 2001 From: Ethan Rose Date: Wed, 17 Jun 2026 21:10:59 -0700 Subject: [PATCH 1/6] currencies spec --- 24.md | 79 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 79 insertions(+) create mode 100644 24.md diff --git a/24.md b/24.md new file mode 100644 index 0000000..70d9cfe --- /dev/null +++ b/24.md @@ -0,0 +1,79 @@ +LUD-24: `currencies` base spec. +======================================= + +`author: ethanrose` `author: lsunsi` `author: lorenzolfm` `author: jklein24` + +--- + +## Support for LNURL-pay currencies + +This document describes an extension to the [payRequest](https://github.com/lnurl/luds/blob/luds/06.md) base specification that allows the `WALLET` to send money to a `SERVICE` while denominating the amount in a different currency. The features proposed enable many use cases including: + +- Bitcoin-settled cash remittances +- Merchant bitcoin acceptance +- Lightning address aliases for bank & mobile money accounts +- Cross-border payroll + + +The main features provided by this extension are: +- `SERVICE` **MUST** inform `WALLET` what currencies it supports +- `WALLET` **MAY** request an invoice with an amount denominated in one of the currencies + + +## 1. `currencies` array in payRequest details + +`SERVICE` must alter its JSON response to the first request to include a `currencies` field, as follows: + +```diff +{ + "tag": "payRequest", + "callback": string, + "maxSendable": number, + "minSendable": number, + "metadata": string, ++ "currencies": [ ++ { ++ "code": "PHP", ++ "name": "Philippine Pesos", ++ "symbol": "₱", ++ "decimals": 2, ++ "minSendable": 1, ++ "maxSendable": 50000, ++ "multiplier": 64501 // (optional) ++ } ++ ] +} +``` + +- The inclusion of the `currencies` field indicates the support of this extension +- The `multiplier` may be included for informational purposes, not a guaranteed rate +- The `code` of a `currency` must be unique +- The order of the `currencies` may be interpreted by the `WALLET` as the receiving user preference for a currency + + +## 2. Wallet interface + +If there is a `currency` record, `WALLET` should display a modified interface: +- Display currency symbol and code +- If there are multiple currency options, allow user to select/change currencies +- Validate "decimals" count for user amount input + + +## 3. Including `currency` in callback parameters + +```diff +- amount= ++ currency=PHP&amount= +``` + +- Amount must be in SMALLEST UNIT INTEGER (wallet should use `decimals` value to modify amount) +- If `currency` param is omitted, the `amount` will be interpreted as millisatoshis (base spec) + + +## 4. Service processing + +`SERVICE` response is unchanged. The invoice amount will be in millisats, but the expiry may be short duraction if the service opts to lock-in a rate for auto-conversion. Auto-conversion is `SERVICE` recipient's preference, not relevant to `WALLET` sender. + +## 5. User interface for reviewing & confirming the exchange rate + +- `WALLET` must display a confirmation screen so that the user can review and confirm the invoice amount. From 805273f0c8e507df0dbc4bedebe6ffcf052ddcb7 Mon Sep 17 00:00:00 2001 From: Ethan Rose Date: Wed, 17 Jun 2026 21:11:41 -0700 Subject: [PATCH 2/6] formatting --- 24.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/24.md b/24.md index 70d9cfe..70cbddd 100644 --- a/24.md +++ b/24.md @@ -76,4 +76,4 @@ If there is a `currency` record, `WALLET` should display a modified interface: ## 5. User interface for reviewing & confirming the exchange rate -- `WALLET` must display a confirmation screen so that the user can review and confirm the invoice amount. +`WALLET` must display a confirmation screen so that the user can review and confirm the invoice amount. From 1f047b969ddd0b8ef04c0276d307613072a8284d Mon Sep 17 00:00:00 2001 From: Ethan Rose Date: Wed, 17 Jun 2026 21:14:23 -0700 Subject: [PATCH 3/6] Update 24.md --- 24.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/24.md b/24.md index 70cbddd..76bd61c 100644 --- a/24.md +++ b/24.md @@ -20,7 +20,7 @@ The main features provided by this extension are: - `WALLET` **MAY** request an invoice with an amount denominated in one of the currencies -## 1. `currencies` array in payRequest details +### 1. `currencies` array in payRequest details `SERVICE` must alter its JSON response to the first request to include a `currencies` field, as follows: @@ -51,7 +51,7 @@ The main features provided by this extension are: - The order of the `currencies` may be interpreted by the `WALLET` as the receiving user preference for a currency -## 2. Wallet interface +### 2. Wallet interface If there is a `currency` record, `WALLET` should display a modified interface: - Display currency symbol and code @@ -59,7 +59,7 @@ If there is a `currency` record, `WALLET` should display a modified interface: - Validate "decimals" count for user amount input -## 3. Including `currency` in callback parameters +### 3. Including `currency` in callback parameters ```diff - amount= @@ -70,10 +70,10 @@ If there is a `currency` record, `WALLET` should display a modified interface: - If `currency` param is omitted, the `amount` will be interpreted as millisatoshis (base spec) -## 4. Service processing +### 4. Service processing `SERVICE` response is unchanged. The invoice amount will be in millisats, but the expiry may be short duraction if the service opts to lock-in a rate for auto-conversion. Auto-conversion is `SERVICE` recipient's preference, not relevant to `WALLET` sender. -## 5. User interface for reviewing & confirming the exchange rate +### 5. User interface for reviewing & confirming the exchange rate `WALLET` must display a confirmation screen so that the user can review and confirm the invoice amount. From b829d90632a656d450481eb468fb2c3d28a4fedb Mon Sep 17 00:00:00 2001 From: Ethan Rose Date: Wed, 17 Jun 2026 21:35:32 -0700 Subject: [PATCH 4/6] Update SERVICE response explanation in documentation Clarified the role of the SERVICE in auto-conversion and its relevance to the WALLET sender. --- 24.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/24.md b/24.md index 76bd61c..d4b59a6 100644 --- a/24.md +++ b/24.md @@ -72,7 +72,9 @@ If there is a `currency` record, `WALLET` should display a modified interface: ### 4. Service processing -`SERVICE` response is unchanged. The invoice amount will be in millisats, but the expiry may be short duraction if the service opts to lock-in a rate for auto-conversion. Auto-conversion is `SERVICE` recipient's preference, not relevant to `WALLET` sender. +`SERVICE` response is unchanged. + +`SERVICE` may optionally lock-in a rate and auto-convert to the specified currency, but that is a `SERVICE` / recipient decision, not relevant to the `WALLET` / sender. ### 5. User interface for reviewing & confirming the exchange rate From 95927c61e808413bf3ed5d5cd4f6b51ae40d4d2a Mon Sep 17 00:00:00 2001 From: Ethan Rose Date: Fri, 19 Jun 2026 11:15:11 -0700 Subject: [PATCH 5/6] Update 24.md --- 24.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/24.md b/24.md index d4b59a6..c7ebe3c 100644 --- a/24.md +++ b/24.md @@ -16,8 +16,8 @@ This document describes an extension to the [payRequest](https://github.com/lnur The main features provided by this extension are: -- `SERVICE` **MUST** inform `WALLET` what currencies it supports -- `WALLET` **MAY** request an invoice with an amount denominated in one of the currencies +- `SERVICE` **MAY** provide `WALLET` with a list of supported currencies. +- `WALLET` **MAY** allow user to pay an amount denominated in a supported currency. ### 1. `currencies` array in payRequest details From aa62c6e73c9c5853edfabed3a2e3040f22ae41a5 Mon Sep 17 00:00:00 2001 From: Ethan Rose Date: Fri, 19 Jun 2026 11:18:22 -0700 Subject: [PATCH 6/6] Update WALLET capabilities for invoice requests Add functionality for requesting invoices in supported currencies. --- 24.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/24.md b/24.md index c7ebe3c..72e6d7d 100644 --- a/24.md +++ b/24.md @@ -17,7 +17,7 @@ This document describes an extension to the [payRequest](https://github.com/lnur The main features provided by this extension are: - `SERVICE` **MAY** provide `WALLET` with a list of supported currencies. -- `WALLET` **MAY** allow user to pay an amount denominated in a supported currency. +- `WALLET` **MAY** allow user to request an invoice for an amount denominated in a supported currency in place of millisats. ### 1. `currencies` array in payRequest details