x402: Agent Payments

​

Key Features

• HTTP-Native: Built into existing HTTP requests with no additional communication required
• Instant Settlement: Sub-second on Celo, compared to days with traditional payments
• Zero Protocol Fees: Only pay nominal blockchain gas fees
• Agent-First: Designed for autonomous AI agent transactions
• Chain Agnostic: Supports 170+ EVM chains including Celo

​

Why x402?

​

How It Works

1. Client requests resource - AI agent or app sends HTTP request to API
2. Server returns 402 - If no payment attached, server responds with HTTP 402 Payment Required and payment details in headers
3. Client signs payment - Client signs payment authorization using their wallet
4. Client retries with payment - Request sent again with a PAYMENT-SIGNATURE header
5. Server verifies and settles - Payment is verified and settled on-chain
6. Server delivers resource - Requested content returned with payment receipt

​

Get Started with the Celo Facilitator

• Dashboard — x402.celo.org serves the web dashboard (a single-page app). Do not point a resource server at it.
• Payment API — https://api.x402.celo.org (mainnet) is the facilitator endpoint your resource server talks to for /verify, /settle, and /supported. Celo Sepolia is at https://api.x402.sepolia.celo.org.

​

Endpoints

• Mainnet — https://api.x402.celo.org
• Celo Sepolia — https://api.x402.sepolia.celo.org

​

Pointing a Resource Server at It

npm i @x402/express @x402/core @x402/evm

import express from "express";
import { paymentMiddleware, x402ResourceServer } from "@x402/express";
import { HTTPFacilitatorClient, type RoutesConfig } from "@x402/core/server";
import { ExactEvmScheme } from "@x402/evm/exact/server";

// Celo's hosted facilitator — note the api. subdomain
const facilitator = new HTTPFacilitatorClient({
  url: "https://api.x402.celo.org",
  // Attaches your metering key to every facilitator request. /settle is
  // key-gated; without a valid key it returns 401 Missing X-API-Key.
  createAuthHeaders: async () => {
    const h = { "X-API-Key": process.env.X402_API_KEY! };
    return { verify: h, settle: h, supported: h };
  },
});

const server = new x402ResourceServer(facilitator);
server.register("eip155:*", new ExactEvmScheme());

// The RoutesConfig annotation is load-bearing: without it `network` widens to
// `string` and no longer satisfies the CAIP-2 `${string}:${string}` type.
const routes: RoutesConfig = {
  "GET /premium": {
    accepts: [
      {
        scheme: "exact",
        network: "eip155:42220", // Celo mainnet
        payTo: "0xYourSellerPayoutAddress", // your wallet — receives the USDC
        price: {
          amount: "10000", // $0.01 — USDC has 6 decimals; always a string
          asset: "0xcebA9300f2b948710d2653dD7B07f33A8B32118C",
          extra: { name: "USDC", version: "2" }, // EIP-712 domain, must match the token
        },
      },
    ],
    description: "Premium content",
  },
};

const app = express();
app.use(paymentMiddleware(routes, server)); // routes first, then server
app.get("/premium", (_req, res) => res.json({ data: "paid content" }));
app.listen(3000);

​

Getting an API Key

1. Open the dashboard and connect your wallet.
2. Click Create API key and sign the message. This is an off-chain signature — no gas, no transaction.
3. The key is shown once. Copy it and set it as X402_API_KEY in your server environment.

​

Check that it works

curl -i http://localhost:3000/premium

curl -s -o /dev/null -D - http://localhost:3000/premium \
  | awk -F': ' 'tolower($1)=="payment-required"{print $2}' | tr -d '\r' | base64 -d

​

x402 on Celo

• Low fees: Gas costs under $0.001 per transaction
• Fast finality: ~1 second block times
• Stablecoin support: Native USDC and USDT for predictable pricing
• Fee abstraction: Agents can pay gas in the same stablecoins used for x402 payments — no separate CELO balance needed. See Fee Abstraction for Agents

​

Supported Payment Tokens on Celo

​

Celo Configuration

// Mainnet
const mainnetAccepts = {
  scheme: "exact",
  network: "eip155:42220",
  payTo: "0xYourSellerPayoutAddress",
  price: {
    amount: "10000", // $0.01 — USDC has 6 decimals
    asset: "0xcebA9300f2b948710d2653dD7B07f33A8B32118C", // Celo mainnet USDC
    extra: { name: "USDC", version: "2" },
  },
};

// Testnet (Celo Sepolia)
const testnetAccepts = {
  scheme: "exact",
  network: "eip155:11142220",
  payTo: "0xYourSellerPayoutAddress",
  price: {
    amount: "10000", // $0.01 — USDC has 6 decimals
    asset: "0x01C5C0122039549AD1493B8220cABEdD739BC44E", // Celo Sepolia USDC
    extra: { name: "USDC", version: "2" },
  },
};

​

Use Cases

​

AI Agent API Access

​

Pay-Per-Use AI Inference

​

Micropayments for Content

​

Trust and other facilitators

• Confirm who operates it.
• Before your server accepts a payment, check the asset, amount and payTo address against what you priced. Do not rely on the facilitator’s response alone.
• Confirm the settlement transaction on-chain before you deliver anything valuable. A facilitator cannot redirect funds, because the payer signs to and value, but a settlement claim should still be checked.
• Test against Celo Sepolia (https://api.x402.sepolia.celo.org for the Celo facilitator) before sending mainnet funds. To create a test account and fund it, see Give your agent a wallet and test funds.

​

Resources

​

Related

• ERC-8004 - Trust layer for AI agents
• x402: Get your endpoint discovered - Make the endpoint findable by agents and indexes
• MPP - Machine Payments Protocol: charge USDC per request over HTTP
• Celopedia - Celo ecosystem knowledge for coding assistants
• Fee Abstraction - Pay gas with stablecoins on Celo
• Attribution Tags - Credit on-chain activity back to your app (facilitator-side tagging of x402 settlements is not live yet)