Create a wallet for a given mint and unit. Call loadMint before use.
Binding, if options.keysetId is omitted, the wallet binds to the cheapest active keyset for
this unit during loadMint.
Caching, preload mint info and keychain data by calling loadMintFromCache after construction.
The keychain stores all loaded keysets and filters query results by the wallet unit.
Deterministic secrets, pass bip39seed and optionally secretsPolicy. Deterministic outputs
reserve counters from counterSource, or an ephemeral in memory source if not supplied.
initialCounter applies only with a supplied keysetId and the ephemeral source.
Splitting, denominationTarget guides proof splits, default is 3. Override coin selection with
selectProofs if needed. Logging defaults to a null logger.
Mint instance or URL.
Optionaloptions: {Optional settings.
OptionalauthProvider?: AuthProviderOptionalbip39seed?: Uint8Array<ArrayBufferLike>BIP39 seed for deterministic secrets.
OptionalcounterInit?: Record<string, number>Seed values for the built-in EphemeralCounterSource. Ignored if counterSource is also provided.
OptionalcounterSource?: CounterSourceCounter source for deterministic outputs. If provided, this takes precedence over counterInit. Use when you need persistence across processes or devices.
OptionaldenominationTarget?: numberTarget proofs per denomination, default 3.
OptionalkeysetId?: stringBind to this keyset id, else bind on loadMint.
Optionallogger?: LoggerLogger instance, default null logger.
OptionalsecretsPolicy?: SecretsPolicySecrets policy, default 'auto'.
OptionalselectProofs?: SelectProofsCustom proof selection function.
Optionalunit?: stringWallet unit, default 'sat'.
ReadonlycountersDeveloper-friendly counters API.
ReadonlymintMint instance - allows direct calls to the mint.
ReadonlyonConvenience wrapper for events.
ReadonlyopsEntry point for the builder.
The keyset ID bound to this wallet instance.
Get the wallet's unit.
The unit (e.g., 'sat').
Restores batches of deterministic proofs until no more signatures are returned from the mint.
OptionalgapLimit: number = 300The amount of empty counters that should be returned before restoring
ends (defaults to 300). Default is 300
OptionalbatchSize: number = 100The amount of proofs that should be restored at a time (defaults to
100). Default is 100
Optionalcounter: number = 0The counter that should be used as a starting point (defaults to 0). Default
is 0
OptionalkeysetId: stringWhich keysetId to use for the restoration. If none is passed the instance's default one will be used.
Bind this wallet to a specific keyset id.
The keyset identifier to bind to.
This changes the default keyset used by all operations that do not explicitly pass a keysetId. The method validates that the keyset exists in the keychain, matches the wallet unit, and has keys loaded.
Typical uses:
Checks an existing melt quote for any payment method.
The payment method (e.g., 'bolt11', 'bolt12', 'bacs', 'swift').
Quote ID or quote object (must have a quote field).
Optionaloptions: { normalize?: (raw: Record<string, unknown>) => TRes }Optionalnormalize?: (raw: Record<string, unknown>) => TResOptional callback to normalize method-specific response fields.
The melt quote response.
Returns an existing bolt11 melt quote from the mint.
ID of the melt quote.
The mint will return an existing melt quote.
Returns an existing bolt12 melt quote from the mint.
ID of the melt quote.
The mint will return an existing melt quote.
Checks an existing mint quote for any payment method.
The payment method (e.g., 'bolt11', 'bolt12', 'bacs', 'swift').
Quote ID or quote object (must have a quote field).
Optionaloptions: { normalize?: (raw: Record<string, unknown>) => TRes }Optionalnormalize?: (raw: Record<string, unknown>) => TResOptional callback to normalize method-specific response fields.
The mint quote response.
Gets an existing mint quote from the mint.
Quote ID.
The mint will create and return a Lightning invoice for the specified amount.
Gets an existing BOLT12 mint quote from the mint.
Quote ID.
The latest mint quote for the given quote ID.
Get an array of the states of proofs from the mint (as an array of CheckStateEnum's)
(only the secret field is required)
NUT-07 state for each proof, in same order.
Completes a pending melt by calling the melt endpoint and constructing change proofs.
The preview from prepareMelt().
Optionalprivkey: string | string[]The private key(s) for signing.
OptionalpreferAsync: booleanOptional override to request NUT-06 asynchronous melt.
Updated MeltProofsResponse.
Complete a prepared mint transaction.
Preview returned by prepareMint.
Minted proofs.
Complete a prepared swap transaction.
With metadata for swap transaction.
Optionalprivkey: string | string[]The private key(s) for signing.
SendResponse with keep/send proofs.
Requests a mint quote from the mint that is locked to a public key.
Amount requesting for mint.
Public key to lock the quote to.
Optionaldescription: stringOptional description for the mint quote.
The mint will return a mint quote with a Lightning invoice for minting tokens of the
specified amount and unit. The quote will be locked to the specified pubkey.
Creates a melt quote for any payment method.
The payment method (e.g., 'bolt11', 'bolt12', 'bacs', 'swift').
The request body to POST. unit is always set to the wallet's unit.
Optionaloptions: { normalize?: (raw: Record<string, unknown>) => TRes }Optionalnormalize?: (raw: Record<string, unknown>) => TResOptional callback to normalize method-specific response fields.
The melt quote response.
Generic method for requesting a melt quote. The payload is method-specific but must at minimum
include the fields required by the mint for the given method. An optional normalize callback
can be used to coerce method-specific response fields.
For first-class methods, prefer the typed helpers: createMeltQuoteBolt11(),
createMeltQuoteBolt12().
Requests a melt quote from the mint. Response returns amount and fees for a given unit in order to pay a Lightning invoice.
LN invoice that needs to get a fee estimate.
OptionalamountMsat: AmountLikeOptional amount in millisatoshis to attach for amountless invoices, must not be provided for invoices that already encode an amount.
The mint will create and return a melt quote for the invoice with an amount and fee reserve.
Requests a melt quote from the mint. Response returns amount and fees for a given unit in order to pay a BOLT12 offer.
BOLT12 offer that needs to get a fee estimate.
OptionalamountMsat: AmountLikeAmount in millisatoshis for amount-less offers. If this is defined and the offer has an amount, they MUST be equal.
The mint will create and return a melt quote for the offer with an amount and fee reserve.
Creates a mint quote for any payment method.
The payment method (e.g., 'bolt11', 'bolt12', 'bacs', 'swift').
The request body to POST. unit is always set to the wallet's unit.
Optionaloptions: { normalize?: (raw: Record<string, unknown>) => TRes }Optionalnormalize?: (raw: Record<string, unknown>) => TResOptional callback to normalize method-specific response fields.
The mint quote response.
Generic method for requesting a mint quote. The payload is method-specific but must at minimum
include the fields required by the mint for the given method. An optional normalize callback
can be used to coerce method-specific response fields.
For first-class methods, prefer the typed helpers: createMintQuoteBolt11(),
createMintQuoteBolt12().
Requests a mint quote from the mint. Response returns a Lightning payment request for the requested given amount and unit.
Amount requesting for mint.
Optionaldescription: stringOptional description for the mint quote.
The mint will return a mint quote with a Lightning invoice for minting tokens of the specified amount and unit.
Requests a mint quote from the mint. Response returns a Lightning BOLT12 offer for the requested given amount and unit.
Public key to lock the quote to.
Optionaloptions: { amount?: AmountLike; description?: string }Optionalamount?: AmountLikeBOLT12 offer amount requesting for mint. If not specified, the offer will be amountless.
Optionaldescription?: stringDescription for the mint quote.
The mint will return a mint quote with a BOLT12 offer for minting tokens of the specified amount and unit.
Requests a multi path melt quote from the mint.
LN invoice that needs to get a fee estimate.
The mint will create and return a melt quote for the invoice with an amount and fee reserve.
Decodes a string token.
The token in string format (cashuB...)
Token object.
Returns the default OutputType for this wallet, based on its configured secrets policy (options?.secretsPolicy) and seed state.
If the secrets policy is 'random', returns { type: 'random' }.
If the policy is 'deterministic', requires a seed and returns { type: 'deterministic', counter: 0 }. Counter 0 is a flag meaning "auto-increment from current state".
If no explicit policy is set, falls back to:
An OutputType object describing the default output strategy.
Calculates the fees based on inputs for a given keyset.
Number of inputs.
KeysetId used to lookup input_fee_ppk
Fee amount.
Gets the requested keyset or the keyset bound to the wallet.
Optionalid: stringOptional keyset id to resolve. If omitted, the wallet's bound keyset is used.
The resolved Keyset.
This method enforces wallet policies. If id is omitted, it returns the keyset bound to this
wallet, including validation that:
Contrast with keyChain.getKeyset(id?), which, when called without an id, returns the cheapest
active keyset for the unit, ignoring the wallet binding.
Load mint information, keysets, and keys.
OptionalforceRefresh: booleanIf true, re-fetches data even if cached.
Load mint information, keysets, and keys from cached data.
Melts proofs for any payment method.
The payment method (e.g., 'bolt11', 'bolt12', 'bacs', 'swift').
The melt quote object (must have at least quote and amount fields).
Proofs to melt.
Optionalconfig: MeltProofsConfigOptional parameters.
OptionaloutputType: OutputTypeConfiguration for proof generation. Defaults to wallet.defaultOutputType().
MeltProofsResponse with quote and change proofs.
Melt proofs for a bolt11 melt quote.
ID of the melt quote.
Proofs to melt.
Optionalconfig: MeltProofsConfigOptional parameters.
OptionaloutputType: OutputTypeConfiguration for proof generation. Defaults to wallet.defaultOutputType().
MeltProofsResponse with quote and change proofs.
Melt proofs for a bolt12 melt quote, returns change proofs using specified outputType.
ID of the melt quote.
Proofs to melt.
Optionalconfig: MeltProofsConfigOptional parameters.
OptionaloutputType: OutputTypeConfiguration for proof generation. Defaults to wallet.defaultOutputType().
MeltProofsResponse with quote and change proofs.
Mints proofs for any payment method.
The payment method (e.g., 'bolt11', 'bolt12', 'bacs', 'swift').
Amount to mint.
The mint quote object (must have at least a quote field).
Optionalconfig: MintProofsConfigOptional parameters (e.g. privkey for locked quotes).
OptionaloutputType: OutputTypeConfiguration for proof generation. Defaults to wallet.defaultOutputType().
Minted proofs.
Mint proofs for a bolt11 quote.
Amount to mint.
Mint quote ID or object (bolt11).
Optionalconfig: MintProofsConfigOptional parameters (e.g. privkey for locked quotes).
OptionaloutputType: OutputTypeConfiguration for proof generation. Defaults to wallet.defaultOutputType().
Minted proofs.
Mints proofs for a bolt12 quote.
Amount to mint.
Bolt12 mint quote.
Private key to unlock the quote.
Optionalconfig: { keysetId?: string }Optional parameters (e.g. keysetId).
OptionaloutputType: OutputTypeConfiguration for proof generation. Defaults to wallet.defaultOutputType().
Minted proofs.
Prepare A Melt Transaction.
Payment method of the quote.
The melt quote. Only quote (ID) and amount are required — a full
MeltQuoteBolt11Response works, but { quote: string, amount: Amount } is sufficient.
Proofs to melt.
Optionalconfig: MeltProofsConfigOptional configuration (keysetId, privkey, etc.).
OptionaloutputType: OutputTypeConfiguration for proof generation. Defaults to wallet.defaultOutputType().
MeltPreview.
Prepare a mint transaction for replay and later completion.
The mint quote. Only quote (ID) is required — a full MintQuoteBolt11Response
works, but { quote: string } is sufficient. Pass config.privkey to produce a NUT-20
signature regardless of whether the quote carries a pubkey field.
Optionalconfig: MintProofsConfigOptionaloutputType: OutputTypeGeneric method-oriented mint API. This supports current methods such as bolt11 and bolt12
as well as future custom methods exposed by the mint. For first-class typed ergonomics with the
built-in methods, prefer mintProofsBolt11(), mintProofsBolt12(), or
wallet.ops.mintBolt11()/mintBolt12().
Returns a MintPreview that contains the exact mint payload and output data needed to
construct proofs. Persist this preview to support NUT-19 replay safety.
Prepare A Receive Transaction.
Token string, decoded token, or raw proof array.
Optionalconfig: ReceiveConfigOptional receive config.
OptionaloutputType: OutputTypeConfiguration for proof generation. Defaults to wallet.defaultOutputType().
SwapPreview with metadata for swap transaction.
Prepare A Send Transaction.
Amount to send (receiver gets this net amount).
Array of proofs to split.
Optionalconfig: SendConfigOptional parameters for the swap.
OptionaloutputConfig: OutputConfigSwapPreview with metadata for swap transaction.
Allows you to preview fees for a send, get concrete outputs for P2PK SIG_ALL transactions, and do any pre-swap tasks (such as marking proofs in-flight etc)
Receive a token (swaps with mint for new proofs)
Token string, decoded token, or raw proof array.
Optionalconfig: ReceiveConfigOptional receive config.
OptionaloutputType: OutputTypeConfiguration for proof generation. Defaults to wallet.defaultOutputType().
Newly minted proofs.
Regenerates.
Set starting point for count (first cycle for each keyset should usually be 0)
Set number of blinded messages that should be generated.
Optionalconfig: RestoreConfigSelects proofs to send based on amount and fee inclusion.
Array of Proof objects available to select from.
The target amount to send.
Optional boolean to include fees; Default: false.
Optional boolean to require exact match; Default: false.
SendResponse containing proofs to keep and proofs to send.
Send proofs with online swap if necessary.
Amount to send (receiver gets this net amount).
Array of proofs to split.
Optionalconfig: SendConfigOptional parameters for the swap.
OptionaloutputConfig: OutputConfigSendResponse with keep/send proofs.
// Simple send
const result = await wallet.send(5, proofs);
// With a SendConfig
const result = await wallet.send(5, proofs, { includeFees: true });
// With Custom output configuration
const customConfig: OutputConfig = {
send: { type: 'p2pk', options: { pubkey: '...' } },
keep: { type: 'deterministic', counter: 0 },
};
const customResult = await wallet.send(5, proofs, { includeFees: true }, customConfig);
Sends proofs of a given amount from provided proofs.
Amount to send.
Array of proofs (must sum >= amount; pre-sign if P2PK-locked).
Optionalconfig: SendOfflineConfigOptional parameters for the send.
SendResponse with keep/send proofs.
Prepares proofs for sending by signing P2PK-locked proofs.
The proofs to sign.
The private key(s) for signing.
OptionaloutputData: OutputDataLike[]Optional. For signing of SIG_ALL transactions.
OptionalquoteId: stringOptional. For signing SIG_ALL melt transactions.
Signed proofs.
Creates a new Wallet bound to a different keyset, sharing the same CounterSource.
Use this to operate on multiple keysets concurrently without mutating your original wallet. Counters remain monotonic across instances because the same CounterSource is reused.
Do NOT pass a fresh CounterSource for the same seed unless you know exactly why. Reusing counters can recreate secrets that a mint will reject.
The keyset identifier to bind to.
Optionalopts: { counterSource?: CounterSource }
Class that represents a Cashu wallet.
Remarks
This class should act as the entry point for this library. Can be instantiated with a mint instance or mint url.
Example