x402: HTTP-Native Agent Payments

x402 is an open protocol that activates the HTTP 402 "Payment Required" status code, enabling AI agents and applications to make instant, permissionless micropayments using stablecoins.

When to Use

Implementing pay-per-use API endpoints
Building AI agents that pay for services autonomously
Creating micropayment flows for content or data access
Accepting stablecoin payments without traditional payment infrastructure

Key Benefits

Feature	Traditional Payments	x402
Setup Time	Days to weeks	Minutes
Settlement	2-7 days	Sub-second on Celo
Fees	2-3% + $0.30	~$0.001 gas
Minimum Payment	$0.50+	$0.001
AI Agent Support	Not possible	Native

Installation

npm install thirdweb

Client Side (React)

Use the useFetchWithPayment hook for automatic payment handling:

import { useFetchWithPayment } from "thirdweb/react";
import { createThirdwebClient } from "thirdweb";

const client = createThirdwebClient({ clientId: "your-client-id" });

function PaidAPIComponent() {
  const { fetchWithPayment, isPending } = useFetchWithPayment(client);

  const handleApiCall = async () => {
    // Automatically handles:
    // - Wallet connection prompts
    // - Payment signing
    // - Insufficient funds UI
    // - Retry logic
    const data = await fetchWithPayment(
      "https://api.example.com/paid-endpoint"
    );
    console.log(data);
  };

  return (
    <button onClick={handleApiCall} disabled={isPending}>
      {isPending ? "Processing..." : "Access Premium Content"}
    </button>
  );
}

Client Side (TypeScript)

For non-React applications, use wrapFetchWithPayment:

import { wrapFetchWithPayment } from "thirdweb/x402";
import { createThirdwebClient } from "thirdweb";
import { privateKeyToAccount } from "thirdweb/wallets";

const client = createThirdwebClient({ clientId: "your-client-id" });
const account = privateKeyToAccount({ client, privateKey: "0x..." });

const fetchWithPayment = wrapFetchWithPayment({
  client,
  account,
  paymentOptions: {
    maxValue: "1000000", // Max payment in base units
  },
});

// Use like regular fetch - payments handled automatically
const response = await fetchWithPayment("https://api.example.com/premium");
const data = await response.json();

Server Side (Next.js)

Accept x402 payments in API endpoints:

// app/api/premium-content/route.ts
import { settlePayment, facilitator } from "thirdweb/x402";
import { createThirdwebClient } from "thirdweb";
import { celo } from "thirdweb/chains";

const client = createThirdwebClient({
  secretKey: process.env.THIRDWEB_SECRET_KEY,
});

const thirdwebFacilitator = facilitator({
  client,
  serverWalletAddress: "0xYourServerWalletAddress",
});

export async function GET(request: Request) {
  const paymentData =
    request.headers.get("PAYMENT-SIGNATURE") ||
    request.headers.get("X-PAYMENT");

  const result = await settlePayment({
    resourceUrl: "https://your-api.com/premium-content",
    method: "GET",
    paymentData,
    payTo: "0xYourWalletAddress",
    network: celo, // Use Celo chain
    price: "$0.01", // Price in USD
    facilitator: thirdwebFacilitator,
    routeConfig: {
      description: "Access to premium API content",
      mimeType: "application/json",
    },
  });

  if (result.status === 200) {
    return Response.json({ data: "premium content" });
  } else {
    return Response.json(result.responseBody, {
      status: result.status,
      headers: result.responseHeaders,
    });
  }
}

Server Side (Express)

import express from "express";
import { settlePayment, facilitator } from "thirdweb/x402";
import { createThirdwebClient } from "thirdweb";
import { celo } from "thirdweb/chains";

const app = express();

const client = createThirdwebClient({
  secretKey: process.env.THIRDWEB_SECRET_KEY,
});

const thirdwebFacilitator = facilitator({
  client,
  serverWalletAddress: "0xYourServerWalletAddress",
});

app.get("/api/premium", async (req, res) => {
  const paymentData = req.headers["payment-signature"] || req.headers["x-payment"];

  const result = await settlePayment({
    resourceUrl: `${req.protocol}://${req.get("host")}${req.originalUrl}`,
    method: "GET",
    paymentData,
    payTo: "0xYourWalletAddress",
    network: celo,
    price: "$0.05",
    facilitator: thirdwebFacilitator,
  });

  if (result.status === 200) {
    res.json({ data: "premium content" });
  } else {
    res.status(result.status).set(result.responseHeaders).json(result.responseBody);
  }
});

Payment Flow

Client requests resource - AI agent or app sends HTTP request
Server returns 402 - If no payment, returns HTTP 402 Payment Required with payment details
Client signs payment - Client signs payment authorization
Client retries with payment - Request sent with X-PAYMENT header
Server verifies and settles - Payment verified and settled on-chain
Server delivers resource - Content returned with receipt

Supported Payment Tokens on Celo

Token	Address	Decimals
USDC	`0xcebA9300f2b948710d2653dD7B07f33A8B32118C`	6
USDT	`0x48065fbbe25f71c9282ddf5e1cd6d6a887483d5e`	6
USDm	`0x765DE816845861e75A25fCA122bb6898B8B1282a`	18

Celo Configuration

import { celo, celoSepolia } from "thirdweb/chains";

// Mainnet
const mainnetConfig = {
  network: celo,
  price: "$0.01",
};

// Testnet (Sepolia)
const testnetConfig = {
  network: celoSepolia,
  price: "$0.01",
};

AI Agent Usage

Autonomous API Payments

// AI agent paying for API calls autonomously
const agent = {
  wallet: agentWallet,
  fetchWithPayment: wrapFetchWithPayment({
    client,
    account: agentWallet
  }),
};

// Agent pays per API call - no API keys needed
const marketData = await agent.fetchWithPayment("https://api.market.com/prices");
const analysis = await agent.fetchWithPayment("https://api.ai.com/analyze");

Pay-Per-Use AI Inference

// Server: Charge based on actual token usage with "upto" scheme
const result = await settlePayment({
  resourceUrl: request.url,
  method: "POST",
  paymentData,
  payTo: "0xYourWallet",
  network: celo,
  scheme: "upto",           // Dynamic pricing
  price: "$1.00",           // Maximum amount
  minPrice: "$0.01",        // Minimum amount
  facilitator: thirdwebFacilitator,
});

// Verify first, then charge based on actual usage
const { tokens } = await runAIInference(prompt);
const actualPrice = tokens * 0.0001; // $0.0001 per token

await settlePayment({
  ...paymentArgs,
  price: actualPrice,
});

Micropayments for Content

// Pay-per-article instead of subscriptions
app.get("/articles/:id", async (req, res) => {
  const result = await settlePayment({
    resourceUrl: req.url,
    method: "GET",
    paymentData: req.headers["x-payment"],
    payTo: publisherWallet,
    network: celo,
    price: "$0.10",
    facilitator: thirdwebFacilitator,
    routeConfig: {
      description: "Premium article access",
    },
  });
  // ...
});

Integration with ERC-8004

Combine trust verification with payments:

import { ReputationRegistry } from '@chaoschain/sdk';
import { wrapFetchWithPayment } from 'thirdweb/x402';

async function payTrustedService(agentId, serviceUrl) {
  // 1. Check reputation first
  const summary = await reputationRegistry.getSummary(agentId);
  if (summary.averageScore < 80) {
    throw new Error('Service reputation too low');
  }

  // 2. Make payment
  const response = await fetchWithPayment(serviceUrl);

  // 3. Submit feedback
  await reputationRegistry.giveFeedback(agentId, 90, 0, 'starred', ...);

  return response.json();
}

Environment Variables

# Client-side
NEXT_PUBLIC_THIRDWEB_CLIENT_ID=your_client_id

# Server-side
THIRDWEB_SECRET_KEY=your_secret_key

Celo Network Reference

Network	Chain ID	RPC Endpoint
Celo Mainnet	42220	https://forno.celo.org
Celo Sepolia	11142220	https://forno.celo-sepolia.celo-testnet.org

x402