The Future of API Monetization: Implementing HTTP 402 for Multi-Chain Micropayments

For decades, the HTTP status code 402 Payment Required has been reserved for future use. While 404 Not Found and 500 Internal Server Error became part of our daily developer vocabulary, 402 sat dormant, waiting for a native digital value transfer layer.

With the rise of high-speed blockchains like Solana, Avalanche, and Base, that future is finally here.

At ZelfProof, we have implemented a production-ready HTTP 402 architecture that allows users to pay for API usage on a per-request basis using our ZNS token. This system eliminates the friction of monthly subscriptions for occasional users and demonstrates the true power of "programmable money."

TL;DR:

Innovation: ZelfProof implements HTTP 402 Payment Required for seamless, pay-per-request API access.
Multi-Chain: Users can pay using ZNS tokens on Solana, Avalanche, and Base.
The Flow: Standard challenge-response: Server sends 402 with cost -> Client pays on-chain -> Client retries with Tx Hash.
Impact: Enables true micropayments, replacing expensive monthly subscriptions with a fair, usage-based model.

The Architecture Overview

Our system is designed to be chain-agnostic, allowing users to pay on their preferred network while accessing the same unified API services.

Core Components

Payment Middleware: Validates payment headers and proofs before allowing access to protected endpoints.
Chain-Specific Verification Modules: Dedicated modules for Solana, Avalanche, and Base that verify transactions on their respective ledgers.
ZNS Token: The utility token used for all payments.

How the Flow Works

The beauty of this architecture lies in its simplicity. It follows a standard challenge-response pattern:

The Challenge: A user attempts to access a protected endpoint (e.g., /api/zelf-proof/encrypt).
The 402 Response: The server checks for payment headers. If missing, it returns a 402 Payment Required status. This response includes a JSON payload with precise instructions:
- Cost of the request (e.g., 0.1 ZNS)
- Accepted chains
- Service wallet addresses
The Payment: The user (or their client application) sends the required ZNS tokens on their chosen chain.
The Retry: The client retries the original request, this time attaching the transaction hash in the x-payment-tx header.
The Access: The middleware verifies the transaction on-chain. If valid, the API request is processed.

sequenceDiagram
    participant User
    participant API
    participant Blockchain

    User->>API: POST /encrypt (No Payment)
    API-->>User: 402 Payment Required (Cost: 0.1 ZNS)
    User->>Blockchain: Send 0.1 ZNS
    Blockchain-->>User: Transaction Hash
    User->>API: POST /encrypt (x-payment-tx: Hash)
    API->>Blockchain: Verify Transaction
    Blockchain-->>API: Valid
    API-->>User: 200 OK (Encrypted Data)

Why Multi-Chain?

We chose to support Solana, Avalanche, and Base to maximize accessibility and minimize costs.

Solana: For sub-second finality (~400ms) and negligible fees.
Avalanche: For a robust EVM-compatible experience with fast confirmation times.
Base: Leveraging the security of Ethereum with the speed of an L2.

Each chain has its own verification logic to handle differences in block times and confirmation requirements, ensuring that we never keep the user waiting longer than necessary.

Developer Experience

Integrating this from the frontend is straightforward. Here is how a typical client handles the 402 challenge:

async function callPaidEndpoint(endpoint, data, chain, wallet) {
    try {
        // Attempt request
        return await axios.post(endpoint, data);
    } catch (error) {
        if (error.response?.status === 402) {
            // 1. Get payment details
            const { cost, serviceWallet } = error.response.data.paymentDetails;

            // 2. Perform crypto transaction
            const txHash = await wallet.sendTokens(cost, serviceWallet);

            // 3. Retry with proof
            return await axios.post(endpoint, data, {
                headers: {
                    "x-payment-chain": chain,
                    "x-payment-tx": txHash,
                },
            });
        }
        throw error;
    }
}

Security & Replay Protection

Allowing payments via transaction hashes introduces a risk: Replay Attacks. A malicious user could try to use the same transaction hash for multiple API calls.

To prevent this, our middleware implements:

Transaction Tracking: Every used transaction hash is stored in a database.
Redis Caching: Recent payments are cached for instant lookups.
Atomic Verification: The check-and-mark-used operation is atomic to prevent race conditions.

The Future of Micropayments

This architecture paves the way for a new internet economy. Instead of walling off content behind $20/month subscriptions, services can charge fractions of a cent per article, per second of video, or per API call.

By leveraging HTTP 402 and high-performance blockchains, ZelfProof is not just building a product; we are building a blueprint for the future of web monetization.

Build the Future with Zelf

Ready to implement this in your own application? Or looking for a secure, biometric-enabled wallet that handles these micro-transactions seamlessly?

Integrate ZelfProof: Add privacy-preserving identity verification to your app with just a few lines of code.
Explore Our Stack: Check out our open-source documentation to see how we build secure, scalable crypto infrastructure.
Join the Network: Use Zelf Wallet to interact with ZelfProof services cleanly and securely.

Start Building | Download Zelf