Skip to main content

​
X402 Autonomous Payments

X402 is an open payment protocol that uses the HTTP 402 Payment Required status code to let AI agents pay for resources autonomously — no checkout page, no human click, no API key exchange. Your PayRequest page is already X402-compatible. Agents that speak the protocol can discover your payment requirements, sign an authorization off-chain, and settle USDC directly to your wallet in one round trip.
X402 requires your EVM wallet to be connected in Provider Settings. The agent pays to that address directly — PayRequest never holds the funds.

​
How it works

1

Agent discovers your payment endpoint

The agent reads your payments.txt manifest and finds your x402_payment_endpoint. Alternatively it calls the discovery JSON at x402_discovery_url to get the full payment requirements object.
2

Agent gets payment requirements (402)

The agent sends a POST to your payment endpoint without a payment header. PayRequest responds with HTTP 402 Payment Required and a JSON body describing exactly what to pay:
{
  "x402Version": 2,
  "error": "payment_required",
  "accepts": [{
    "scheme": "exact",
    "network": "eip155:8453",
    "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
    "amount": "1000",
    "payTo": "0xYourWalletAddress",
    "maxTimeoutSeconds": 30
  }]
}
amount is in USDC atomic units (6 decimals): 1000 = $0.001.
3

Agent signs the payment off-chain

The agent signs an ERC-3009 transferWithAuthorization message with its wallet — no gas, no on-chain transaction yet. This is just a cryptographic signature authorizing the USDC transfer.
4

Agent retries with X-Payment header

The agent sends the same request again, this time including:
X-Payment: base64({"x402Version":2,"payload":{"signature":"0x...","authorization":{...}},...})
5

PayRequest verifies and settles

PayRequest verifies the signature, then broadcasts transferWithAuthorization on Base — moving USDC from the agent’s wallet directly to yours. No intermediary. The transaction is final within seconds.
6

Agent receives confirmation (200)

PayRequest responds 200 OK with:
{
  "success": true,
  "onchain_tx": "0xTxHash…",
  "payer": "0xAgentWalletAddress",
  "amount_usdc": 0.001
}
Plus an X-Payment-Response header with the settlement receipt.

​
Pay a specific invoice

Agents can pay a specific outstanding invoice by hitting: 
POST /api/v1/x402/yourhandle/invoice/{invoiceId}/pay
The 402 response will include the exact invoice amount as the required payment. On success, the invoice is automatically marked as paid in PayRequest. This is the primary use case: an AI agent receives an invoice email, extracts the invoice ID, pays it autonomously via X402, and the invoice closes — all without a human touching the checkout.

​
Discovery endpoints

EndpointMethodDescription
/yourhandle/payments.txtGETHuman + machine readable manifest
/api/v1/x402/yourhandleGETJSON discovery: wallets, accepted networks, payment URL
/api/v1/x402/yourhandle/payPOSTX402 payment endpoint
/api/v1/x402/yourhandle/invoice/{id}/payPOSTPay a specific invoice

​
Supported networks

NetworkTokenChain ID
Base (mainnet)USDCeip155:8453
Base Sepolia (testnet)USDCeip155:84532
Solana (mainnet)USDCsolana:5eykt4...

​
Settlement

PayRequest settles payments by calling transferWithAuthorization on the USDC contract. This moves funds directly from the agent’s wallet to yours — PayRequest acts as a broadcast relay, not a custodian. Settlement uses the Base public RPC by default. No Coinbase CDP account is required.
You can use Base Sepolia testnet USDC to test X402 payments before going live. Set X402_TESTNET=true in your environment to switch endpoints to testnet.

​
For developers building agents

If you’re building an AI agent that needs to pay PayRequest users autonomously:
  1. Discover — GET https://payrequest.me/{handle}/payments.txt or the JSON discovery endpoint
  2. Get requirements — POST to the payment endpoint, expect a 402 response
  3. Sign — Use viem, ethers.js, or any EIP-712 library to sign TransferWithAuthorization
  4. Pay — Retry the POST with the X-Payment header
  5. Confirm — 200 response + X-Payment-Response header = settled
The full protocol specification is at:

X402 spec on GitHub

Complete request/response format, header schemas, and network reference.

​
Frequently asked questions

Yes — a tiny amount of ETH on Base (roughly $0.001 per settlement). The agent’s wallet needs ETH to pay for gas when the USDC transfer is broadcast. Base is extremely cheap.
Any EVM-compatible wallet that can sign EIP-712 typed data. Smart contract wallets (Safe, Coinbase Smart Wallet) are also supported since ERC-3009 handles those signatures.
The default per-call amount is $0.001 USDC. For invoice payments, the amount is always the invoice total. Custom minimum amounts per-user are on the roadmap.
If the signature is invalid, expired, or the amount is too low, PayRequest returns another 402 with the verification_error field explaining what went wrong. The agent can retry with a fresh signature.
Yes — PayRequest implements the open X402 spec published by Coinbase. Any agent built against that spec works with PayRequest. No Coinbase account is needed on your end.