Cashu TS

code coverage

⚠️ Don't be reckless: This project is in early development, it does however work with real sats! Always use amounts you don't mind losing.

Cashu TS is a JavaScript library for Cashu wallets written in TypeScript.

Install

npm i @cashu/cashu-ts
Copy

Quick Start (Create a wallet)

There are a number of ways to instantiate a wallet, depending on your needs.

Wallet classes are mostly stateless, so you can instantiate and throw them away as needed. Your app must therefore manage state, such as fetching and storing proofs in a database.

NB: You must always call loadMint() or loadMintFromCache after instantiating a wallet.

import { Wallet } from '@cashu/cashu-ts';

// Simplest: With a mint URL
const mintUrl = 'http://localhost:3338';
const wallet1 = new Wallet(mintUrl); // unit is 'sat'
await wallet1.loadMint(); // wallet is now ready to use

// Persist these in your app
const keychainCache = wallet1.keyChain.cache; // KeyChainCache
const mintInfoCache = wallet1.getMintInfo().cache; // GetInfoResponse

// Advanced: With cached mint data (avoids network calls on startup)
const wallet2 = new Wallet(keychainCache.mintUrl, { unit: keychainCache.unit });
wallet2.loadMintFromCache(mintInfoCache, keychainCache);
// wallet2 is now ready to use
Copy

Usage

We provide comprehensive examples categorized by use case:

• Basic Guide: Getting Started, and basic token operations.
• WalletOps: Translation Builder Usage Recipes.
• WalletEvents: Event Subscriptions
• Deterministic Counters: Deterministic counters (persist, inspect, bump).

Note: Builder hooks vs Global events

WalletOps builders include per-operation hooks (onCountersReserved) that fire during a single transaction build.

WalletEvents provides global subscriptions (wallet.on.*) that can outlive a single builder call.

Use the builder hooks for transaction-local callbacks, and WalletEvents for app-wide subscriptions.

Browser usage (standalone build)

Cashu TS provides a standalone browser build (IIFE) intended for demos and non-bundler usage. The standalone bundle is published as part of GitHub Releases rather than the npm package.

Contribute

Contributions are very welcome.

If you want to contribute, please open an Issue or a PR. We are also tracking the status with projects. Please refer to the contributing guide for more info.

Contact & Maintainers

Feel free to join the matrix server or telegram channel