Provider Protocol

Implementation guidelines, API extensions, and operational best practices for X-Cashu payment providers.

Provider Implementation Overview

This section outlines the specific requirements and best practices for implementing X-Cashu payment protocols on the provider side. It covers server setup, API extensions, security considerations, and operational guidelines for maintaining a reliable payment gateway.

Integration Guidelines

Existing API Integration:

For providers with existing OpenAI-compatible APIs, X-Cashu support can be added as middleware:

  • Add X-Cashu header processing before existing authentication
  • Integrate payment verification into request pipeline
  • Modify response handling to include change notes
  • Update documentation to reflect new payment options
Implementation Notes
  • X-Cashu header is used in all protocols for both requests (payment) and responses (returning change).
  • Providers are required to implement the /infos and /v1/models endpoint for provider information Discovery and pricing and model discovery.
Provider Information Discovery
REQUIRED

Providers MUST implement an information endpoint that exposes essential operational details including supported mints, payment configurations, and provider capabilities.

Endpoint: GET /infos

Description: Returns provider operational information including supported Cashu mints, payment configurations, contact details, and service capabilities.

Example Response:

{
   "name": "THUDM AI Provider",
   "description": "High-performance AI inference provider",
   "version": "1.2.0",
   "website": "https://thudm-ai.com",
   "payment_info": {
     "supported_mints": [
       {
         "mint_url": "https://mecash.routstr.com",
         "unit": "msat"
       },
       {
         "mint_url": "https://ecash.routstr.com",
         "unit": "sat"
       }
     ],
     "payment_methods": [
       "x-cashu",
       "prepaid"
     ]
   }
 }

Key Information Categories:

Provider Details
  • Provider name and description
  • API version information
  • Provider website URL
Payment Configuration
  • Supported Cashu mint URLs
  • Currency unit denominations
  • Available payment methods

Benefits:

  • Enables mint selection based on provider support and unit preferences
  • Provides essential service discovery for payment integration
  • Supports payment method negotiation between client and provider
  • Facilitates proper currency unit handling and conversion
Model & Pricing Discovery
REQUIRED

To enable wallet-aware clients to estimate and optimize payment, every provider MUST implement a discovery endpoint:

Endpoint: GET /v1/models

Description: Returns a list of supported models with detailed pricing information, architecture specifications, and provider capabilities.

Example Response:

{
   "models": [
     {
       "id": "thudm/glm-4.1v-9b-thinking",
       "canonical_slug": "thudm/glm-4.1v-9b-thinking",
       "hugging_face_id": "THUDM/GLM-4.1V-9B-Thinking",
       "name": "THUDM: GLM 4.1V 9B Thinking",
       "created": 1752244385,
       "description": "GLM-4.1V-9B-Thinking is a 9B parameter vision-language model developed by THUDM",
       "context_length": 65536,
       "architecture": {
         "modality": "text+image->text",
         "input_modalities": [
           "image",
           "text"
         ],
         "output_modalities": [
           "text"
         ],
         "tokenizer": "Other",
         "instruct_type": null
       },
       "pricing": {
         "prompt": "0.000000035",
         "completion": "0.000000138",
         "request": "0",
         "image": "0",
         "web_search": "0",
         "internal_reasoning": "0"
       },
       "pricing_sats": {
         "prompt": "1",
         "completion": "1",
         "request": "0",
         "image": "0",
         "web_search": "0",
         "internal_reasoning": "0",
         "max_cost": "7",
       },
       "top_provider": {
         "context_length": 65536,
         "max_completion_tokens": 8000,
         "is_moderated": false
       },
       "per_request_limits": null,
       "supported_parameters": [
         "max_tokens",
         "temperature",
         "top_p",
         "reasoning",
         "include_reasoning",
         "stop",
         "frequency_penalty",
         "presence_penalty",
         "seed",
         "top_k",
         "min_p",
         "repetition_penalty",
         "logit_bias"
       ]
     }
   ]
 }

Benefits:

  • Clients can create notes with the exact amount based on detailed pricing
  • Architecture information enables input validation and compatibility checking
  • Comprehensive model metadata supports intelligent model selection
  • Supports dynamic pricing and model availability changes
  • Provider-specific configurations enable optimized client behavior
X-Cashu Header Specification

Request Headers:

X-Cashu: <cashu_token>

Contains the Cashu note(s) for payment. Format depends on the chosen protocol.

Response Headers:

X-Cashu: <change_token>

Contains change notes when payment exceeds actual usage cost.