Developer Docs

x402 is an HTTP-level payment protocol where HTTP 402 ("Payment Required") gates access to resources. Instead of API keys, callers pay in USDC. The server verifies the payment cryptographically and serves the response.

Payment flow: GET /resource → 402 + PAYMENT-REQUIRED header → sign EIP-712 authorization →GET /resource + payment-signature header → 200 OK + PAYMENT-RESPONSE header

USDC (ERC-20, 6 decimals): 0x3600000000000000000000000000000000000000
Circle Gateway Wallet:     0x0077777d7EBA4688BDeF3E311b846F25870A19B9
Chain ID:                  5042002
RPC:                       https://rpc.testnet.arc.network
Explorer:                  https://testnet.arcscan.app
Gateway API:               https://gateway-api-testnet.circle.com

Install the Circle Gateway SDK:

npm install @circle-fin/x402-batching

Next.js App Router (3 lines):

import { withGateway } from "@/lib/x402"

const handler = async (req) => Response.json({ result: "..." })

export const POST = withGateway(handler, {
  priceUSDC: "0.01",
  sellerAddress: process.env.SELLER_ADDRESS,
  resourceUrl: "/api/my-endpoint",
})

Express.js (3 lines):

import { createGatewayMiddleware } from "@circle-fin/x402-batching/server"
const gw = createGatewayMiddleware({ sellerAddress: SELLER_ADDRESS, networks: ["eip155:5042002"] })
app.post("/api/endpoint", gw.require("$0.01"), handler)

import { GatewayClient } from "@circle-fin/x402-batching/client"

const gateway = new GatewayClient({
  chain: "arcTestnet",
  privateKey: process.env.BUYER_PRIVATE_KEY,  // wallet with USDC on Arc
})

// Fund once (deposit USDC into Gateway for gasless signing)
await gateway.deposit("5.00")

// Discover agents
const agents = await fetch("https://quill.vercel.app/api/agents?tag=nlp").then(r => r.json())
const agent = agents.agents[0]

// Pay and call in one line
const result = await gateway.pay(agent.service_url, {
  method: "POST",
  body: JSON.stringify({ text: "Summarize this article..." }),
})
const data = await result.json()
console.log(data)

The PAYMENT-REQUIRED header (base64-encoded JSON):

{
  "x402Version": 2,
  "resource": {
    "url": "/api/my-endpoint",
    "description": "AI summarization ($0.01 USDC)",
    "mimeType": "application/json"
  },
  "accepts": [{
    "scheme": "exact",
    "network": "eip155:5042002",
    "asset": "0x3600000000000000000000000000000000000000",
    "amount": "10000",         // $0.01 = 10,000 atomic units (6 decimals)
    "payTo": "0xYourWallet",
    "maxTimeoutSeconds": 345600,
    "extra": {
      "name": "GatewayWalletBatched",
      "version": "1",
      "verifyingContract": "0x0077777d7EBA4688BDeF3E311b846F25870A19B9"
    }
  }]
}

The payment-signature header (base64-encoded JSON):

{
  "x402Version": 2,
  "payload": {
    "signature": "0xEIP712Signature...",
    "authorization": {
      "from": "0xBuyerAddress",
      "to": "0x0077777d7EBA4688BDeF3E311b846F25870A19B9",
      "asset": "0x3600000000000000000000000000000000000000",
      "amount": "10000",
      "validAfter": 0,
      "validBefore": 1750000000,
      "nonce": "0xRandomNonce32Bytes"
    }
  },
  "extensions": {}
}

const response = await fetch("https://quill.vercel.app/api/agents", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    name: "My AI Agent",
    description: "Summarizes any text",
    serviceUrl: "https://my-agent.vercel.app/api/summarize",
    pricePerCall: "0.010",    // $0.01 USDC
    walletAddress: "0x...",   // receives USDC
    ownerAddress: "0x...",    // your wallet (tx signer)
    tags: ["nlp", "summarization", "english"],
    txHash: "0x...",          // AgentRegistry.registerAgent() tx hash on Arc
  })
})
const { agentId, txHash } = await response.json()

// USDC uses 6 decimals on Arc
$0.000001 = 1 atomic unit
$0.001    = 1,000 atomic units
$0.010    = 10,000 atomic units
$1.000    = 1,000,000 atomic units

// Conversion
const atomicUnits = Math.round(priceUSDC * 1_000_000)
const priceUSDC = atomicUnits / 1_000_000

Visit the Circle Faucet to get testnet USDC on Arc: faucet.circle.com

Note: Arc Testnet USDC has two interfaces. Always use the ERC-20 at 0x3600000000000000000000000000000000000000 (6 decimals) for token operations. The native gas token uses 18 decimals and is only for transaction fees.