Skip to main content
MNNR/Documentation
โšก x402 Protocol

HTTP 402 Payment Required

The internet's native payment protocol. Enable sub-cent micropayments for APIs, content, and agent-to-agent transactions without API keys.

๐Ÿ†MNNR is the First AI Billing Platform to Support x402

Native protocol support for machine-to-machine payments on the open web.

๐Ÿ“–What is x402?

HTTP status code 402 "Payment Required" was reserved in the original HTTP specification for future use with digital payments. The x402 protocol finally implements this vision, enabling any HTTP endpoint to request payment before serving content.

Unlike traditional payment APIs that require API keys, OAuth tokens, and complex integration, x402 works at the HTTP protocol level. When a server returns a 402 response, it includes payment instructions in the headers. The client makes a payment and retries the request with proof of payment. It's that simple.

๐Ÿ’ฐ

Sub-Cent Payments

Minimum payment of $0.001 enables true micropayments

๐Ÿ”‘

No API Keys

Payment is the authentication - no signup required

โšก

Instant Settlement

Payments settle on Base L2 in seconds

โš™๏ธHow It Works

1

Request

Client makes HTTP request to protected endpoint

2

402 Response

Server returns 402 with payment instructions

3

Payment

Client sends stablecoin to specified address

4

Access

Retry with payment proof, receive content

Complete Flow ExamplePython
import requests
from web3 import Web3

# Step 1: Make initial request
response = requests.get("https://api.example.com/premium-data")

# Step 2: Handle 402 Payment Required
if response.status_code == 402:
    payment_info = {
        "amount": response.headers["X-402-Amount"],
        "receiver": response.headers["X-402-Receiver"],
        "network": response.headers["X-402-Network"],
        "token": response.headers["X-402-Token"]
    }
    
    # Step 3: Send payment on Base network
    w3 = Web3(Web3.HTTPProvider("https://mainnet.base.org"))
    usdc = w3.eth.contract(address=USDC_ADDRESS, abi=ERC20_ABI)
    
    tx = usdc.functions.transfer(
        payment_info["receiver"],
        int(float(payment_info["amount"]) * 1e6)  # USDC has 6 decimals
    ).transact()
    
    tx_hash = w3.eth.wait_for_transaction_receipt(tx)
    
    # Step 4: Retry with payment proof
    response = requests.get(
        "https://api.example.com/premium-data",
        headers={
            "X-402-Payment-Proof": json.dumps({
                "txHash": tx_hash.hex(),
                "network": "base",
                "token": "USDC",
                "amount": payment_info["amount"]
            })
        }
    )
    
    # Success! Access granted
    data = response.json()

๐ŸŒSupported Networks & Tokens

Networks

B
Base
Recommended - Low fees, fast settlement
Primary
E
Ethereum
Higher fees, maximum security
P
Polygon
Low fees, wide adoption

Stablecoins

$
USDC
Circle USD - Most liquid
Primary
$
USDT
Tether USD - Wide support
$
DAI
MakerDAO - Decentralized

๐Ÿ’ตx402 Pricing

ResourcePriceExample
Tokens (LLM)$0.01 / 1,000 tokens1,000 word response = $0.01
API Requests$0.10 / 1,000 requestsSingle API call = $0.0001
Compute Time$0.001 / 1,000ms5 second task = $0.005
Minimum Payment$0.001One tenth of a cent

๐ŸŽฏUse Cases

๐Ÿค–

Agent-to-Agent Payments

AI agents can autonomously pay for services from other agents without human intervention. A research agent can pay a data analysis agent per query.

Agent A โ†’ $0.05 โ†’ Agent B (per analysis)
๐Ÿ“ฐ

Content Micropayments

Pay-per-article instead of subscriptions. Readers pay only for what they read, creators get paid instantly.

Reader โ†’ $0.10 โ†’ Publisher (per article)
๐Ÿ”Œ

API Monetization

Monetize your API without managing API keys, rate limits, or billing. Every request pays automatically.

Developer โ†’ $0.001 โ†’ API Provider (per call)
๐ŸŽฎ

Gaming & Virtual Goods

In-game purchases without app store fees. Players pay directly for items, power-ups, or access.

Player โ†’ $0.25 โ†’ Game (per item)

๐Ÿ”งIntegration Guide

Server-Side: Protecting an Endpoint

Next.js API RouteTypeScript
import { handleX402, createPaymentRequest, createX402Headers } from '@/lib/x402';

export async function GET(request: Request) {
  // Check for payment proof in headers
  const paymentProof = request.headers.get('X-402-Payment-Proof');
  
  if (!paymentProof) {
    // Return 402 Payment Required
    const paymentRequest = createPaymentRequest({
      amountUSD: 0.01,
      resource: '/api/premium-data',
      description: 'Access to premium data endpoint',
    });
    
    return new Response(
      JSON.stringify({
        error: 'Payment required',
        paymentRequest,
      }),
      {
        status: 402,
        headers: {
          'Content-Type': 'application/json',
          ...createX402Headers(paymentRequest),
        },
      }
    );
  }
  
  // Verify payment proof
  const isValid = await verifyPayment(JSON.parse(paymentProof));
  
  if (!isValid) {
    return new Response(
      JSON.stringify({ error: 'Invalid payment proof' }),
      { status: 402 }
    );
  }
  
  // Payment verified - serve content
  return Response.json({
    data: 'Premium content here',
    payment: { verified: true }
  });
}

Client-Side: Making Paid Requests

JavaScript ClientJavaScript
import { MNNR } from '@mnnr/sdk';

const client = new MNNR({ apiKey: 'your-api-key' });

// The SDK handles x402 automatically
async function fetchPremiumData() {
  try {
    // SDK automatically handles 402 responses
    const response = await client.x402.request({
      url: 'https://api.example.com/premium-data',
      method: 'GET',
      // Optional: set spending limits
      maxPayment: 1.00,  // Max $1.00 per request
    });
    
    return response.data;
  } catch (error) {
    if (error.code === 'PAYMENT_LIMIT_EXCEEDED') {
      console.log('Request would exceed payment limit');
    }
    throw error;
  }
}

// Or handle manually
async function manualX402Flow() {
  const response = await fetch('https://api.example.com/premium-data');
  
  if (response.status === 402) {
    const paymentInfo = {
      amount: response.headers.get('X-402-Amount'),
      receiver: response.headers.get('X-402-Receiver'),
      network: response.headers.get('X-402-Network'),
    };
    
    // Make payment through MNNR
    const payment = await client.payments.create({
      amount: paymentInfo.amount,
      to: paymentInfo.receiver,
      network: paymentInfo.network,
    });
    
    // Retry with payment proof
    return fetch('https://api.example.com/premium-data', {
      headers: {
        'X-402-Payment-Proof': JSON.stringify({
          txHash: payment.txHash,
          network: payment.network,
          token: payment.token,
          amount: payment.amount,
        }),
      },
    });
  }
  
  return response;
}

๐Ÿ“‹HTTP Headers Reference

HeaderDirectionDescriptionExample
X-402-VersionResponseProtocol version1.0
X-402-AmountResponsePayment amount in USD0.001
X-402-CurrencyResponseCurrency codeUSD
X-402-NetworkResponseBlockchain networkbase
X-402-TokenResponseToken to pay withUSDC
X-402-ReceiverResponsePayment address0x1234...abcd
X-402-ExpiresResponsePayment deadline2025-12-28T12:00:00Z
X-402-Payment-ProofRequestJSON proof of payment{"txHash":"0x..."}

๐Ÿš€Try x402 Now

Test the x402 protocol with our demo endpoint. Send a request and see the 402 response in action.

Demo Request
curl -i https://mnnr.app/api/x402?demo=true

Learn More

Explore the x402 specification and community resources.