custom payment methods by asmogo · Pull Request #382 · cashubtc/nuts

asmogo · 2026-05-27T21:57:04Z

support custom payment methods not defined in a dedicated NUT.

robwoodgate

I think this is a fantastic step forward for wallets to be able to better support unknown methods - I've added some suggested tweaks to the base structs to make life even better.

robwoodgate · 2026-05-28T10:42:03Z

+
+### Websocket Notifications
+
+Custom methods **MAY** support websocket subscriptions via [NUT-17][17] with kind `"{method}_mint_quote"`.


Related: #372

robwoodgate · 2026-05-28T10:42:35Z

+
+### Websocket Notifications
+
+Custom methods **MAY** support websocket subscriptions via [NUT-17][17] with kind `"{method}_melt_quote"`.


Related: #372

robwoodgate · 2026-05-28T10:49:29Z

 {
  "unit": <str_enum[UNIT]>
  // Additional method-specific fields may be required
 }


To better support custom, I think we should expand the base request something like:

Suggested change

{

"unit": <str_enum[UNIT]>,

"amount": <int>, // Optional

"description": <str>, // Optional

"pubkey": <str> // Optional (NUT-20)

}

Then NUT specific methods can enforce / ignore as needed - eg: NUT-23 makes amount required., NUT-25 makes pubkey required.

robwoodgate · 2026-05-28T10:55:01Z

 {
  "quote": <str>,
  "request": <str>,
  "unit":  <str_enum[UNIT]>,
  // Additional method-specific fields will be included
 }


Custom would be better supported if the base reply is more like:

Suggested change

{

"quote": <str>,

"request": <str>,

"unit": <str_enum[UNIT]>,

"expiry": <int|null>,

"pubkey": <str>, // Optional (NUT-20)

"amount_paid": <int>,

"amount_issued": <int>

// Additional method-specific fields will be included

}

robwoodgate · 2026-05-28T11:00:37Z

 {
  "request": <str>,
  "unit": <str_enum[UNIT]>
  // Additional method-specific fields will be required
 }


Melt base suggestion for better custom handling:

Suggested change

{

"request": <str>,

"unit": <str_enum[UNIT]>,

"amount": <int>, // Optional

// Additional method-specific fields will be required

}

robwoodgate · 2026-05-28T11:15:05Z

 {
  "quote": <str>,
  "amount": <int>,
  "unit": <str_enum[UNIT]>,
  "state": <str_enum[STATE]>,
  "expiry": <int>
  // Additional method-specific fields will be included
 }
 ```

 Where `quote` is the quote ID, `amount` and `unit` the amount and unit that need to be provided, and `expiry` is the Unix timestamp until which the melt quote is valid.


Melt response base suggestion for better custom method handling:

Suggested change

{

"quote": <str>,

"request": <str>,

"amount": <int>,

"unit": <str_enum[UNIT]>,

"fee_reserve": <int>, // Optional

"state": <str_enum[STATE]>,

"expiry": <int>

// Additional method-specific fields will be included

}

Where `quote` is the quote ID, `amount` and `unit` the amount and unit that need to be provided, and `expiry` is the Unix timestamp until which the melt quote is valid.

`request` contains the method-specific payment routing instructions (eg bolt11 Lightning invoice, Bitcoin onchain address, bank account details, paypal email etc).

`fee_reserve` is the additional fee for using the method. The mint expects the wallet to include `Proofs` of _at least_ `total_amount = amount + fee_reserve + fee` where `fee` is calculated from the keyset's `input_fee_ppk` as described in [NUT-02][02].

robwoodgate · 2026-05-28T11:31:44Z

Sorry @asmogo - I questioned an earlier draft that included method in the quote structs (thinking mint and wallet know by virtue of the endpoint used to request it), but this related issue highlights that for WS, and especially with the suggestion on harmonizing the base structs for custom methods, the distinction is easy to blur/lose.

So maybe we DO need to include method: <str>, in the quote structs for both mint and melt.

robwoodgate · 2026-05-28T13:32:27Z

Related #377

which adds the amount_oaid, amount_issued, updated_at parms to default quote structs

robwoodgate

Have implemented custom method support in cashu-ts on top of this + #377 + #387 (cashubtc/cashu-ts#693) and it works nicely. Wallets can quote, mint and melt methods they don't fully understand using just the base structs.

A few tweaks below that came out of implementing. Note the suggestions assume #377 merges first.

Related to my base struct suggestions above: expiry really wants to be in the common mint quote response - every method has one, and a wallet showing a quote for an unknown method needs to know when to stop polling. With #377 in, it's the only field from the suggested base response still left as method-specific.

(method in the quote structs is now covered by #387, which also resolves the WS routing question from #378.)

Can also confirm the optional fee_reserve in the melt base works in practice - onchain can't make it required (it uses fee_options), and bolt11/12 tighten it to required in their own NUTs.

robwoodgate · 2026-06-12T16:43:47Z

+
+For a custom `{method}`, the wallet sends a request following the common mint quote request format (see [General Flow](#general-flow)). Method-specific fields (e.g., an `amount` of tokens to mint, a `description`, or a `pubkey` for [NUT-20][20] locks) are defined by the method-specific NUT.
+
+The mint responds with the common mint quote response format. The `request` field contains the method-specific payment request (e.g., a payment URL, an on-chain address, an account identifier). Additional method-specific fields (such as `amount` or `expiry`) are defined by the method-specific NUT.


Wallets can derive the accounting fields from state for methods they know, but for an unknown method there's no fallback, so these need to be explicit. Suggest:

Suggested change

The mint responds with the common mint quote response format. The `request` field contains the method-specific payment request (e.g., a payment URL, an on-chain address, an account identifier). Additional method-specific fields (such as `amount` or `expiry`) are defined by the method-specific NUT.

The mint responds with the common mint quote response format, and **MUST** include the `amount_paid`, `amount_issued` and `updated_at` fields. The `request` field contains the method-specific payment request (e.g., a payment URL, an on-chain address, an account identifier). Additional method-specific fields (such as `amount` or `expiry`) are defined by the method-specific NUT.

robwoodgate · 2026-06-12T16:45:41Z

+
+For a custom `{method}`, the wallet sends a request following the common melt quote request format (see [General Flow](#general-flow)). The `request` field is the method-specific payment target (e.g., a bank account identifier, an on-chain address, a payment processor reference). `unit` is the unit the wallet would like to pay with.
+
+The mint responds with the common melt quote response format. Method-specific fields are defined by the method-specific NUT.


Wallets can't interpret a custom state machine for a method they don't understand, so custom melts need the standard states. Suggest:

Suggested change

The mint responds with the common melt quote response format. Method-specific fields are defined by the method-specific NUT.

The mint responds with the common melt quote response format, using the standard `state` values (`"UNPAID"`, `"PENDING"`, `"PAID"`). Method-specific fields are defined by the method-specific NUT.

Implements the base-shape harmonization proposed on cashubtc/nuts#382: - MintQuoteBaseRequest gains optional amount and description; method NUTs tighten as needed (bolt11 requires amount). - MintQuoteBaseResponse gains expiry (normalized to null when unset), subsuming the per-method expiry fields. - MeltQuoteBaseRequest gains optional amount (onchain requires it). - MeltQuoteBaseResponse gains request and optional fee_reserve; bolt methods keep fee_reserve required. - Melt base validation now requires the payment request for every method, and normalizes fee_reserve when present. - New MintQuoteGenericResponse/MeltQuoteGenericResponse passthrough types are the defaults on the generic quote methods, so custom-method fields are reachable without casting. BREAKING CHANGE: melt quote responses without a request field now throw; generic quote methods default to the Generic response types.

Add generic payment method support

2ed6709

github-project-automation Bot added this to nuts May 27, 2026

github-project-automation Bot moved this to Backlog in nuts May 27, 2026

robwoodgate reviewed May 28, 2026

View reviewed changes

thesimplekid self-requested a review June 9, 2026 14:47

robwoodgate mentioned this pull request Jun 12, 2026

feat(nut04/05)!: quote accounting and custom payment method base structs cashubtc/cashu-ts#693

Open

robwoodgate reviewed Jun 12, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

custom payment methods#382

custom payment methods#382
asmogo wants to merge 1 commit into
cashubtc:mainfrom
asmogo:generic-payment-method

asmogo commented May 27, 2026

Uh oh!

robwoodgate left a comment

Uh oh!

robwoodgate May 28, 2026

Uh oh!

robwoodgate May 28, 2026

Uh oh!

robwoodgate May 28, 2026

Uh oh!

robwoodgate May 28, 2026

Uh oh!

robwoodgate May 28, 2026

Uh oh!

robwoodgate May 28, 2026 •

edited

Loading

Uh oh!

robwoodgate commented May 28, 2026

Uh oh!

robwoodgate commented May 28, 2026

Uh oh!

robwoodgate left a comment

Uh oh!

robwoodgate Jun 12, 2026

Uh oh!

robwoodgate Jun 12, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants


		### Websocket Notifications

		Custom methods MAY support websocket subscriptions via [NUT-17][17] with kind `"{method}_mint_quote"`.

+{
+  "unit": <str_enum[UNIT]>,
+  "amount": <int>, // Optional
+  "description": <str>, // Optional
+  "pubkey": <str> // Optional (NUT-20)
+}


		For a custom `{method}`, the wallet sends a request following the common mint quote request format (see [General Flow](#general-flow)). Method-specific fields (e.g., an `amount` of tokens to mint, a `description`, or a `pubkey` for [NUT-20][20] locks) are defined by the method-specific NUT.

		The mint responds with the common mint quote response format. The `request` field contains the method-specific payment request (e.g., a payment URL, an on-chain address, an account identifier). Additional method-specific fields (such as `amount` or `expiry`) are defined by the method-specific NUT.


		For a custom `{method}`, the wallet sends a request following the common melt quote request format (see [General Flow](#general-flow)). The `request` field is the method-specific payment target (e.g., a bank account identifier, an on-chain address, a payment processor reference). `unit` is the unit the wallet would like to pay with.

		The mint responds with the common melt quote response format. Method-specific fields are defined by the method-specific NUT.

Conversation

asmogo commented May 27, 2026

Uh oh!

robwoodgate left a comment

Choose a reason for hiding this comment

Uh oh!

robwoodgate May 28, 2026

Choose a reason for hiding this comment

Uh oh!

robwoodgate May 28, 2026

Choose a reason for hiding this comment

Uh oh!

robwoodgate May 28, 2026

Choose a reason for hiding this comment

Uh oh!

robwoodgate May 28, 2026

Choose a reason for hiding this comment

Uh oh!

robwoodgate May 28, 2026

Choose a reason for hiding this comment

Uh oh!

robwoodgate May 28, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

robwoodgate commented May 28, 2026

Uh oh!

robwoodgate commented May 28, 2026

Uh oh!

robwoodgate left a comment

Choose a reason for hiding this comment

Uh oh!

robwoodgate Jun 12, 2026

Choose a reason for hiding this comment

Uh oh!

robwoodgate Jun 12, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

robwoodgate May 28, 2026 •

edited

Loading