Skip to content

APIs Overview

Azzamo provides public APIs for payments, moderation, and automation across its services.

These APIs are designed to be predictable, composable, and safe to integrate into production systems that interact with Nostr and Bitcoin-native infrastructure.

Design principles

All Azzamo APIs follow a small set of consistent principles:

  • Explicit behavior over hidden side effects
  • Clear separation between read access and write access
  • Stable endpoints with versioned changes
  • Machine-readable errors
  • Bitcoin- and Nostr-native assumptions

APIs are infrastructure-facing. They are intended for developers and services, not end users.

Available APIs

Cashu API

The Cashu API enables redemption of Cashu ecash tokens to Lightning destinations.

Typical use cases include:

  • Accepting Cashu tokens as payment
  • Redeeming tokens to Lightning invoices or Lightning Addresses
  • Automating ecash-based payment flows

The API handles token validation, redemption, and error handling so integrators do not need to implement mint-specific logic.

Ban API

The Ban API provides shared moderation and enforcement signals for Nostr-based systems.

Typical use cases include:

  • Checking whether a public key is banned
  • Retrieving public blocklists
  • Submitting abuse reports
  • Applying or removing bans through authenticated tooling

The Ban API exposes state and signals. Enforcement is always performed by the consuming system.

Authentication

Authentication requirements depend on the API and endpoint.

Common patterns include:

  • Public, unauthenticated read endpoints
  • API key–protected admin endpoints
  • Nostr-based authentication where explicitly documented

Each API section documents its own authentication rules. Clients must not assume that authentication is optional unless stated.

Rate limits

All APIs enforce rate limits to protect service stability.

  • Limits vary per endpoint
  • Public endpoints are typically more permissive
  • Admin and write endpoints are more restrictive

When limits are exceeded, APIs return explicit error responses.

Error handling

Azzamo APIs return structured JSON errors.

  • HTTP status codes indicate the error class
  • Error bodies include machine-readable identifiers
  • Human-readable messages are provided for debugging

Clients should always handle non-200 responses explicitly.

Stability and changes

API stability is treated as a requirement.

  • Breaking changes are versioned
  • Deprecations are announced ahead of time
  • Behavioral changes are documented in the changelog

Integrators should monitor the changelog for updates.

Terms of use

Use of the APIs implies acceptance of Azzamo policies.

  • Abuse or automated attacks are not allowed
  • Excessive usage may be rate limited or blocked
  • Misuse may result in access revocation

APIs are provided as infrastructure, not as unrestricted public utilities.

Where to go next

  • Cashu API overview
  • Ban API overview
  • API-specific endpoints and examples