Skip to content

Cashu API Overview

The Azzamo Cashu Redeem API provides a production-grade interface for decoding and redeeming Cashu ecash tokens to Lightning destinations.

It is designed for applications that want to accept Cashu tokens and convert them into Lightning payments in a safe, precise, and automated way.

Purpose

Cashu tokens represent Bitcoin value as bearer ecash. Redeeming them correctly requires coordination with the mint, accurate fee calculation, and Lightning payment handling.

The Cashu API exists to:

  • Validate and decode Cashu tokens
  • Safely redeem tokens via their issuing mint
  • Deliver value to Lightning addresses using LNURLp
  • Remove the need for applications to implement mint-specific logic

What the Cashu API does

The Cashu API allows integrators to:

  • Decode Cashu tokens and inspect their contents
  • Check whether a token is already spent
  • Redeem tokens to Lightning addresses
  • Validate Lightning addresses before redemption
  • Monitor API health and availability

All redemption logic is handled server-side using the cashu-ts library and standard Cashu protocols.

Key guarantees

The Cashu API is built around correctness and transparency.

  • Exact fees are obtained from the mint before redemption
  • No satoshis are lost to fee estimation errors
  • Redemption amounts are deterministic and reported explicitly
  • Tokens are checked for spendability before melting

The invoiceAmount returned by the API reflects the exact amount paid over Lightning.

Supported token formats

The API supports multiple Cashu token formats:

  • Cashu v1
  • Cashu v3

Token format is detected automatically during decoding and redemption.

Lightning integration

Redemptions are performed using Lightning addresses via LNURLp.

  • A Lightning address may be provided per request
  • A default Lightning address may be configured server-side
  • Address validation can be performed without redeeming a token

Lightning invoice creation and payment are fully handled by the API.

Typical use cases

The Cashu API is suitable for:

  • Websites accepting Cashu tokens as payment
  • Wallets offering Cashu-to-Lightning redemption
  • Automation and payout services
  • Applications bridging ecash and Lightning

It is not intended to replace a full Cashu wallet or mint implementation.

Authentication

The Cashu API does not require user authentication for standard operations.

  • Endpoints are protected by rate limits
  • Abuse prevention is enforced at the infrastructure level

Applications should treat the API as a public service and avoid exposing it to untrusted automation.

Rate limits

All endpoints are rate limited to protect service stability.

  • Limits apply per client and per IP
  • Excessive usage results in HTTP 429 responses

Exact limits may change and should not be hardcoded.

Errors

All endpoints return structured JSON responses.

  • Success responses include success: true
  • Error responses include success: false and an error message
  • Some errors include an explicit errorType for programmatic handling

Clients must always check the success field.

What the Cashu API is not

To avoid confusion:

  • It is not a Cashu mint
  • It does not issue ecash
  • It does not store user balances
  • It does not custody funds beyond the redemption flow

The API performs validation and redemption only.

When to use the Cashu API

Use the Cashu API if you:

  • Want to accept Cashu tokens without running a mint
  • Need precise, reliable Lightning payouts
  • Prefer a simple HTTP-based integration

If you want to issue ecash or manage wallets, you need a Cashu mint instead.

Where to go next

  • Cashu API endpoints and examples
  • Redeem and decode flows
  • Error and edge-case handling