Skip to content

Widen common quote structs for custom payment methods #1

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

Merged
asmogo merged 1 commit into from
Jun 15, 2026
Merged

Widen common quote structs for custom payment methods #1

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
14 changes: 10 additions & 4 deletions 04.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -40,23 +40,30 @@ Depending on the payment method, the request structure may vary, but all methods

```json
{
"unit": <str_enum[UNIT]>
"unit": <str_enum[UNIT]>,
"amount": <int>, // Optional
"description": <str>, // Optional
"pubkey": <str> // Optional, NUT-20
// Additional method-specific fields may be required
}
```

`amount`, `description` and `pubkey` are common optional fields; method-specific NUTs make them required or ignore them as needed (e.g. NUT-23 requires `amount`, NUT-20 defines `pubkey`).

The mint `Bob` responds with a quote that includes some common fields for all methods:

```json
{
"quote": <str>,
"request": <str>,
"unit": <str_enum[UNIT]>,
"expiry": <int|null>,
"pubkey": <str> // Optional
// Additional method-specific fields will be included
}
```

Where `quote` is the quote ID, `request` is the payment request for the quote, and `unit` corresponds to the value provided in the request.
Where `quote` is the quote ID, `request` is the payment request for the quote, `unit` corresponds to the value provided in the request, and `expiry` is the Unix timestamp until which the quote is valid (`null` if it does not expire).

> [!CAUTION]
>
Expand Down Expand Up @@ -109,8 +116,7 @@ Payment methods not specified in a dedicated NUT can be supported as custom paym

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.

The mint responds with the common mint quote response format and **MUST** include the `amount_paid`, `amount_issued` and `updated_at` accounting 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 are defined by the method-specific NUT.

@robwoodgate robwoodgate Jun 15, 2026

Copy link
Copy Markdown
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This foreshadows cashubtc#377 being merged


### Method-Specific Fields

Expand Down
11 changes: 8 additions & 3 deletions 05.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -46,25 +46,30 @@ Depending on the payment method, the request structure may vary, but all methods
```json
{
"request": <str>,
"unit": <str_enum[UNIT]>
"unit": <str_enum[UNIT]>,
"amount": <int> // Optional
// Additional method-specific fields will be required
}
```

`amount` is a common optional field; method-specific NUTs make it required or ignore it as needed (e.g. NUT-30 requires `amount` for onchain melts).

The mint `Bob` responds with a quote that includes some common fields for all methods:

```json
{
"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.
Where `quote` is the quote ID, `request` is the method-specific payment routing target, `amount` and `unit` the amount and unit that need to be provided, `fee_reserve` is the additional fee reserve for using the method (the wallet provides proofs covering at least `amount + fee_reserve + fee`, where `fee` is the keyset input fee per [NUT-02][02]), and `expiry` is the Unix timestamp until which the melt quote is valid.

`state` is an enum string field with possible values `"UNPAID"`, `"PENDING"`, `"PAID"`:

Expand Down Expand Up @@ -211,7 +216,7 @@ Payment methods not specified in a dedicated NUT can be supported as custom paym

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

### Websocket Notifications

Expand Down