Back to Blog
architecturepaymentscryptoweb3http-402
The Future of API Monetization: Implementing HTTP 402 for Multi-Chain Micropayments
Explore how ZelfProof utilizes the HTTP 402 standard to enable seamless, improved micropayments across Solana, Avalanche, and Base.
Miguel Treviño•
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."
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 Requiredstatus. 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-txheader. - 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.