Cashu TS

⚠️ 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

ESM-only since v4. This package ships only ES modules. CommonJS require() is no longer supported. If upgrading from v3, see migration-4.0.0.md.

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 defaults to 'sat'
wallet2.loadMintFromCache(mintInfoCache, keychainCache);
// wallet2 is now ready to use

Usage

We provide comprehensive examples categorized by use case:

• Basic Guide: Getting Started, and basic token operations.
• Create Wallet: Initialize a wallet from a mint URL or cached mint state.
• 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

We welcome contributions from anyone — newcomers, experienced developers, and AI-assisted workflows alike.

If you want to contribute:

• Start by reading COMMUNITY.md to understand our contribution philosophy, review expectations, and how to get involved.
• Open an Issue or a PR.
• Track progress using our projects.
• For process details, see the contributing guide.

Contact & Community

We are building in the open and encourage active participation:

• Join our weekly call — listen, introduce yourself, or ask questions.
• Participate in our matrix server or telegram channel for ongoing discussion and collaboration.

Being part of the conversation is the best way to have impact and become a long-term contributor.