GitHub
DEVELOPERS / NUT-CCP DRAFT

Build on Cashu Card

Cards, wallets and tills share NUT-CCP, a draft Cashu protocol. Issuance tools prepare the cards for use. Start with the parts below, then choose your guide.

  • Experimental
  • Applet 2.1
  • Java Card 3.0.5
  • MIT license
Contents
  1. How the parts fit
  2. Issuing cards
  3. Status
  4. The specification
  5. The code
  6. Building a reader
  7. Testing on a card
  8. Issues and security
  9. Questions and contributions

How the parts fit

One card connects the holder, merchant and issuer. Payments, installation and recovery have separate paths.

Wallet and till connect to the mint and tap the same physical card. Ops-service authorizes CCP to install the applet. Encrypted exports flow through a backup job to independent storage and alerts; the backup key has separate custody.
NFCOnline APIBackup + alertsDownload SVG ↗

* Atoll Recovery pairs with Workers/R2. The Docker service uses filesystem exports with your scheduled copy and alert jobs. Backup setup ↗

Who runs each part?
Card hardware and applet firmware
A compatible secure chip is the physical card. The open source applet is the software installed on it. Together they hold ecash and answer NFC commands.
Holder wallet
The holder runs a compatible wallet to set ownership and a PIN, load ecash and manage their card.
Till app
The merchant runs a compatible till on an NFC device to accept payments and settle them with the card's mint.
Mint
The mint operator issues the ecash proofs and checks redemption. A card issuer can reference an existing compatible mint.
CCP and ops-service
The card issuer's operators use Cashu Card Provisioner (CCP). The issuer runs an ops-service or uses an existing service they trust. The service manages issuance; holder wallets and tills handle payments through the card and mint.
Optional backup storage and notifications

An issuer also needs operational recovery: encrypted exports, verified copies outside the service host, separate key custody and alerts for failed or stale backups. These support issuance and recovery; card payments follow the flow above.

  • Nextcloud is one destination for encrypted backup files.
  • ntfy is one way to deliver failure and freshness alerts.
  • Atoll Recovery is an optional StartOS companion that copies encrypted Workers exports to backup storage, reports freshness and can send alerts.

The hosting guide covers encrypted exports, independent copying, alerts and recovery-key custody.

Issuing cards

Use Cashu Card Provisioner to install the applet from a phone. An ops-service supplies operator accounts, assigned manager keys and durable installation/reset records. Read why this service is needed, then use your issuer's service or follow the Docker self-hosting guide.

For a computer with a USB reader, the manual install guide covers the card commands and leaves manager-key custody with the operator. Holder-wallet setup follows either installation path.

Status

Cashu Card is an experimental open source project. NUT-CCP is a draft written by this project for proposal to cashubtc/nuts, where it is still to be proposed, numbered or merged, and it has had little testing or review outside the project. The applet's current release is 2.1.0, tested on NXP J3R180 cards with a few named phones. An independent security review is still to come.

Build against it to learn, test and give feedback. Read the risks before your users hold real value on a card.

The specification

  • NUT-CCPThe core every card and reader share: selecting the card, card proofs, reading, paying with one signature, the card's change and loading.
  • NUT-CCP test vectorsCard proof secrets, payments with and without change, and AUTH, worked through.
  • The APDU referenceThis applet's commands byte for byte, with the profiles for the owner key, the clock and limits, and the NFC tag.
  • Applet vectorsJSON vectors for secrets, the owner's proofs, block headers and a full transcript.

The code

  • The appletThe Java Card applet, the reference implementation of NUT-CCP and its profiles.
  • cardsimThe real applet in jCardSim behind a small HTTP API, for a wallet's or till's tests without a card.
  • cashucard/clientA TypeScript library with the Cashu primitives a reader needs and a client for the mint's HTTP API.
  • cardctlA Python command-line driver for the card over any PC/SC reader, contact or contactless.
  • cardkitA TypeScript API for installing the applet and resetting cards, over a transport you supply.
  • Cashu Card ProvisionerThe app card issuers use to install the applet from a phone.

The repository's architecture shows how the parts fit, and its decisions record why the card works as it does.

Building a reader

A reader is anything that talks to the card: a wallet that loads it, or a till that takes its payments. NUT-CCP sets what a reader must do. The points that protect money most:

  • Select the card by its full AID, F0 43 41 53 48 55 43 41 52 44 01.
  • Take every proof on the card as issued by the mint and unit that GET_CARD names, and check each input's keyset against that mint.
  • Check each piece's DLEQ proof, from the mint's keys, before accepting it offline.
  • When online, ask the mint whether the pieces are unspent before accepting.
  • When offline, keep the payment and its change, swap at the mint as soon as you can, and report the payment settled only once the mint accepts the swap.
  • Handle the card's answers for a PIN, a limit and a locked card, listed in the draft's status words.

The security model explains the risks each rule answers.

Testing on a card

cardsim runs the applet without a card. To test on a real one, the install guide puts the applet on a card from a computer and lists the cards it runs on.

The tests on silicon are recorded as dated reports, among them the end-to-end payment run of 23 October 2026, on Android and iOS.

Issues and security

Report a bug or a place where the spec and the code disagree as a GitHub issue. Report anything that could affect funds privately, to security@cashucard.org or through a security advisory, as the security policy asks. A flaw in the draft NUT itself goes there too.

Questions and contributions

Ask in GitHub Discussions on the main repository, the one place for questions about the draft NUT, the applet and the client library. Show what you build in its Show and tell category.

The contributing guide lists where help is needed. Much of it, from the documentation to the client library, needs no card or reader.