Payment Protocol

Multiple interaction models for using the X-Cashu header to pay for access to LLM or other AI services over HTTP.

Overview

This section describes multiple interaction models ("protocols") for using the X-Cashu header to pay for access to LLM or other AI services over HTTP. It also standardizes an endpoint for model and pricing discovery, enabling wallet-aware clients to act responsibly based on current rates.

1. Single-use Cashu Notes
Stateless
Most Secure

Summary:

Each API request is accompanied by a freshly-issued Cashu note in the X-Cashu header, representing the payment for only that request. The provider server verifies, redeems (burns) the note, and returns a new note as change if any remains. Payments are not reused or linked across calls.

Security:

  • Statelessness and Single-use means no long-lived token risk
  • No provider-side wallet tracking (only redemption)
  • This is the highest privacy and anti-replay approach

Flow (Sequence Diagram):

ClientWalletClientProviderProviderWalletPrepare exact (or over) value noteReturns noteAPI Request + X-Cashu headerRedeem note & compute usage/feeUsage result, optionally issue change noteAPI response (+ X-Cashu header if change)Store change note for next use
2. Persistent-Token Balance Tracking
Stateful
Wallet-Session

Summary:

A Cashu token with a nonzero balance is retrieved from client storage (database or external service) and sent with every request. The provider tracks the balance of this particular token, deducts the cost on each invocation, and replies with HTTP 402 if the balance is insufficient. The client updates the token balance in storage and manages issuing new tokens as necessary.

Security:

  • Server must manage reliable per-token state, increasing operational complexity
  • Slightly decreased privacy as token may correlate requests

Flow:

ClientDB/ExternalClientProviderProviderDBGet persistent tokenReturn stored tokenloop: Token has balanceAPI Request + X-Cashu headerDeduct usage from token balanceBalance updatedalt: Sufficient balanceAPI Response (+ balance optional)Update token balancealt: Insufficient balanceHTTP 402 Payment RequiredRequest new tokenProvide fresh token
3. Prepaid Account / Top-up Model
Traditional

Summary:

Clients request an API key by paying ecash upfront to prepay for service credits. Once the API key is obtained, clients use only the API key for requests without sending ecash with each call. When credits are exhausted (HTTP 402 response), clients purchase a new API key or top up their existing account.

Flow:

WalletClientProviderProviderDBGet ecash for API key purchaseProvide ecash paymentRequest API key + ecash paymentCreate account with creditsAccount createdReturn API keyloop: Using API keyAPI Request + API keyCheck/deduct creditsCredit statusalt: Credits availableAPI Responsealt: Credits exhaustedHTTP 402 Payment RequiredGet ecash for top-upProvide ecash paymentTop-up account + ecash paymentAdd credits to existing accountCredits addedTop-up successful
Protocol Comparison
ProtocolPrivacyServer StatePayment GranularityDifficultyAppropriate Usage
Single-use (Stateless)
High
NoneExact per-request
Mid
Maximum security
Persistent-Token
Mid
Per-tokenUp to token value
Low
High-frequency calls
Prepaid Account/Top-up
Mid
Per-accountUp to top-up size
Low
Enterprise/bulk use