X402 Accessibility Extension Specification

Abstract

This specification extends the X402 HTTP Payment Protocol to include accessibility features that make payment flows universally accessible to users with disabilities, language barriers, or varying cognitive abilities. The extension maintains full backward compatibility with existing X402 implementations while adding optional accessibility metadata and preferences.

Motivation

The current X402 protocol focuses on payment mechanics but lacks provisions for:

Multilingual support - Users who don’t speak English
Cognitive accessibility - Users who need simple explanations
Screen reader compatibility - Visually impaired users
Contextual help - Users new to blockchain/cryptocurrencies
Error explanation - Users who need actionable guidance

This extension addresses these gaps while maintaining the protocol’s simplicity and elegance.

Design Principles

Backward Compatibility: Non-accessible clients continue working
Optional: Servers MAY implement, clients MAY request
Language-Agnostic: Not tied to any specific language
AI-Ready: Structure supports both templates and LLM generation
Semantic: Machine-readable for assistive technologies

Specification

1. Client Accessibility Preferences

Clients MAY include accessibility preferences in the payment payload or HTTP headers.

1.1 In Payment Payload (Recommended)

{
  "x402Version": 1,
  "scheme": "exact",
  "network": "bsv-testnet",
  "payload": {
    "transaction": "0100000001..."
  },
  "accessibility": {
    "language": "en",
    "cognitiveLevel": "simple",
    "format": "audio-friendly",
    "features": ["step-by-step", "analogies", "hints"]
  }
}

1.2 In HTTP Headers (Alternative)

X-PAYMENT: <base64-payload>
X-ACCESSIBILITY-LANGUAGE: es
X-ACCESSIBILITY-LEVEL: simple
X-ACCESSIBILITY-FORMAT: audio-friendly

1.3 Accessibility Preferences Schema

interface AccessibilityPreferences {
  language?: string;          // ISO 639-1 code (default: "en")
  cognitiveLevel?: string;    // "simple" | "intermediate" | "technical"
  format?: string;            // "text" | "audio-friendly" | "visual"
  features?: string[];        // ["step-by-step", "analogies", "hints", "examples"]
}

Field Descriptions:

language: ISO 639-1 language code for response messages
cognitiveLevel: Complexity of explanations
- simple: ELI5-style, plain language, max 100 chars
- intermediate: Technical but accessible
- technical: Full technical details
format: Optimization for output medium
- text: Standard text format
- audio-friendly: Optimized for screen readers (no symbols, linear)
- visual: May include diagrams/emojis
features: Optional enhancements requested

2. Server Accessibility Metadata

Servers that support accessibility MUST include an accessibility field in responses.

2.1 Response Structure

All X402 responses (verify, settle, errors) SHOULD wrap data in:

interface AccessibleResponse<T> {
  data: T;                           // Original response data
  accessibility?: AccessibilityMetadata;  // Optional metadata
}

2.2 Accessibility Metadata Schema

interface AccessibilityMetadata {
  plainLanguage: string;      // Simple one-line summary (max 100 chars)
  explanation: string;        // Detailed explanation (max 300 chars)
  stepByStep?: string[];      // Ordered steps (max 5 items, 80 chars each)
  hints?: {                   // Contextual hints
    nextSteps?: string;       // What to do next
    common?: string;          // Common mistakes
    technical?: string;       // Technical details
  };
  analogies?: string[];       // Real-world analogies
  examples?: string[];        // Concrete examples
  language: string;           // Language of this metadata (ISO 639-1)
  audioFriendly: boolean;     // Optimized for screen readers
  cognitiveLevel: string;     // "simple" | "intermediate" | "technical"
}

2.3 Example: Successful Payment

{
  "data": {
    "success": true,
    "transaction": "abc123...",
    "payer": "mxyz...",
    "network": "bsv-testnet"
  },
  "accessibility": {
    "plainLanguage": "The payment completed successfully",
    "explanation": "Your transaction was broadcast to the BSV testnet blockchain with ID abc123...",
    "stepByStep": [
      "We received your signed transaction",
      "We validated it against the BSV network",
      "We broadcast it to the blockchain",
      "The transaction is confirmed on the network"
    ],
    "hints": {
      "nextSteps": "You can verify your transaction on WhatsOnChain with the provided ID"
    },
    "language": "en",
    "audioFriendly": true,
    "cognitiveLevel": "simple"
  }
}

2.4 Example: Payment Error

{
  "data": {
    "isValid": false,
    "invalidReason": "insufficient_funds"
  },
  "accessibility": {
    "plainLanguage": "There are insufficient funds in your wallet",
    "explanation": "Your wallet has 500 satoshis but you need 1113 satoshis (1000 for the payment + 113 for mining fee)",
    "stepByStep": [
      "Check your balance on a blockchain explorer",
      "Get more funds from a faucet or exchange",
      "Try again when you have enough funds"
    ],
    "hints": {
      "nextSteps": "Get test funds at https://faucet.bitcoincloud.net/",
      "common": "The mining fee is calculated based on transaction size (~100-200 sats)"
    },
    "analogies": [
      "It's like trying to buy something for $11 when you only have $5 in your wallet"
    ],
    "language": "en",
    "audioFriendly": true,
    "cognitiveLevel": "simple"
  }
}

3. Resource Server Requirements

Resource servers that want to provide accessible experiences SHOULD:

Extract preferences from client payload or headers
Pass preferences to the facilitator in verify/settle requests
Propagate accessibility metadata from facilitator to client
Preserve metadata through the entire payment flow

3.1 Modified Verify Request

interface VerifyRequest {
  payload: PaymentPayload;
  paymentRequirements: PaymentRequirements;
  accessibilityPreferences?: AccessibilityPreferences;  // NEW
}

3.2 Example Flow

# 1. Client → Resource Server
GET /api/data
X-PAYMENT: <payload-with-accessibility-prefs>

# 2. Resource Server → Facilitator
POST /verify
{
  "payload": {...},
  "paymentRequirements": {...},
  "accessibilityPreferences": {
    "language": "en",
    "cognitiveLevel": "simple"
  }
}

# 3. Facilitator → Resource Server
{
  "data": { "isValid": true, ... },
  "accessibility": { "plainLanguage": "...", ... }
}

# 4. Resource Server → Client
{
  "message": "Payment successful!",
  "data": {...},
  "accessibility": { ... }  // Propagated from facilitator
}

4. AI-Enhanced Accessibility (Optional)

Facilitators MAY use LLM APIs (OpenAI, Anthropic, etc.) to generate dynamic accessibility metadata.

4.1 When to Use AI

Standard errors: Use templates (fast, consistent, free)
Complex errors: Use AI (contextual, adaptive)
Multilingual: Use AI (automatic translation)
Custom explanations: Use AI (personalized)

4.2 Hybrid Approach (Recommended)

async function generateAccessibility(
  eventType: string,
  context: any,
  preferences: AccessibilityPreferences
): Promise<AccessibilityMetadata> {
  // Use cache for common cases
  const cacheKey = `${eventType}:${preferences.language}:${preferences.cognitiveLevel}`;
  const cached = await cache.get(cacheKey);
  if (cached) return cached;

  // Use templates for standard cases
  if (hasTemplate(eventType)) {
    return generateFromTemplate(eventType, context, preferences);
  }

  // Use AI for complex/rare cases
  const aiMetadata = await generateWithAI(eventType, context, preferences);
  await cache.set(cacheKey, aiMetadata, { ttl: 3600 });
  return aiMetadata;
}

5. Error Codes and Templates

Standard error codes SHOULD have predefined accessibility templates:

Error Code	Plain Language (EN)
`invalid_address`	The address is invalid
`insufficient_funds`	Insufficient funds
`invalid_amount`	The amount is incorrect
`invalid_network`	Wrong network (mainnet vs testnet)
`already_broadcast`	Transaction already broadcast
`broadcast_failed`	Broadcast failed
`parse_error`	Error reading the transaction

6. Discovery and Capability Negotiation

6.1 Facilitator Capabilities

Facilitators SHOULD advertise accessibility support in their root endpoint:

GET / HTTP/1.1

{
  "data": {
    "networks": ["bsv-testnet"],
    "accessibility": {
      "supported": true,
      "languages": ["es", "en", "fr", "pt"],
      "cognitiveLevels": ["simple", "intermediate", "technical"],
      "formats": ["text", "audio-friendly", "visual"],
      "aiEnhanced": true,
      "version": "1.0.0"
    }
  },
  "accessibility": {
    "plainLanguage": "This facilitator supports Bitcoin SV testnet",
    "explanation": "We process X402 payments on the Bitcoin SV test network...",
    "language": "en",
    "cognitiveLevel": "simple"
  }
}

7. Security Considerations

Privacy: Accessibility preferences may reveal user characteristics (language, disability)
- Servers SHOULD NOT log preferences
- Use HTTPS always
AI Data: When using AI, avoid sending sensitive transaction data
- Hash/anonymize addresses
- Redact amounts if possible
Cache Poisoning: If caching AI responses
- Use secure cache keys
- Validate cached content
Injection Attacks: When using AI
- Sanitize error messages before sending to LLM
- Validate AI responses before returning

8. Implementation Checklist

Facilitator Implementation

Parse accessibilityPreferences from verify/settle requests
Generate AccessibilityMetadata for all responses
Support at least 2 languages (e.g., English + Spanish)
Implement templates for common errors
Return AccessibleResponse<T> wrapper
Advertise capabilities in root endpoint
(Optional) Integrate AI for complex cases

Resource Server Implementation

Extract accessibility preferences from client
Pass preferences to facilitator
Propagate accessibility metadata to client
Preserve metadata in error responses
Handle missing metadata gracefully

Client (MCP/Wallet) Implementation

Allow users to specify language preference
Allow users to specify cognitive level
Parse and display accessibility metadata
Support screen readers (ARIA labels)
Cache user preferences

9. Examples and Reference Implementation

See the reference implementation at:

Facilitator: https://github.com/bsv402facilitator
Resource Server: (same repo) /src/resource-server
MCP Client: https://github.com/bsv402facilitator/mcp-wallet-bsv

10. Future Enhancements

Potential future additions to this specification:

Visual Accessibility: Diagrams, flowcharts for visual learners
Video Tutorials: Links to explainer videos
Interactive Guides: Step-by-step wizards
Personalization: Learning from user feedback
Compliance: WCAG 2.1 AA certification
Voice Commands: Integration with voice assistants

License

This specification is released under CC0 1.0 Universal (Public Domain).

Contributing

Contributions welcome! Please submit issues and PRs to the reference implementation repository.