An agent buys one API call

The situation

A research agent needs the current weather for one city, once. No human is present: the agent’s owner gave it a wallet and a spending policy in advance, and the agent decides on its own whether a call is worth paying for. The seller is a small API that charges per request and has no sign-up form. Two protocols cover the job. x402 moves the money inside the HTTP request, and ERC-8004 gives the seller an on-chain identity and gives the buyer a public place to say how the call went.^{Source [1, 2]} Neither protocol depends on the other: ERC-8004 treats payment as out of scope, but its registration file has an x402Support flag and its feedback file can point to an x402 payment.^{Source [3]}

Actors

• Client agent with a wallet that can sign EIP-712 typed data (the buyer).
• Seller resource server, the weather API, which also owns an ERC-8004 agent identity.
• Facilitator, which verifies and settles x402 payments and does not hold funds.^{Source [1, 4, 5]}
• Bazaar discovery endpoint, a facilitator’s public catalog of paid resources.^{Source [4]}
• ERC-8004 Identity and Reputation Registries, singleton contracts that use the same addresses on every listed mainnet.^{Source [6]}
• Storage host (IPFS or HTTPS) for the registration file and the feedback file.
• Readers: indexers, explorers and later buyers.

Step by step

1. Discover (x402, path A). The client calls GET /discovery/resources on a Bazaar and gets listings with resource, type, x402Version, accepts and lastUpdated.^{Source [4]} The CDP instance answers without an API key, but it returns listings, not categories.^{Source [7]}
2. Discover (ERC-8004, path B). The client reads the seller’s agentURI and agentWallet from the Identity Registry. agentWallet is where the agent receives payments, and setting it needs a signature from the new wallet.^{Source [2]}
3. Read the registration file (ERC-8004). The file lists services, x402Support, active and registrations.^{Source [2]} An agent can prove control of its endpoint domain with a /.well-known/agent-registration.json file.^{Source [2]}
4. Request (x402). The client calls the endpoint with no payment header and learns the price from the reply.^{Source [4, 8]}
5. 402 (x402). The server answers 402 with a PAYMENT-REQUIRED header holding base64 JSON.^{Source [4, 8]} Each accepts entry names scheme, network, amount, asset, payTo and maxTimeoutSeconds.^{Source [4]}
6. Check and sign (x402). The client signs EIP-712 typed data for EIP-3009 TransferWithAuthorization.^{Source [9]} ERC-8004 best practice is to use agentWallet as the x402 receipt address, so a careful client compares payTo with it before signing.^{Source [10]}
7. Retry (x402). The same request goes out again with a base64 PaymentPayload in PAYMENT-SIGNATURE.^{Source [8]}
8. Verify and run (x402). The server calls POST /verify, runs the handler only if the payment is valid, then calls POST /settle.^{Source [4]}
9. Settle (x402). /settle uses the same request body as /verify and commits the payment.^{Source [4]}
10. On chain (x402). On EVM chains the facilitator broadcasts the EIP-3009 settlement and pays the gas.^{Source [5, 11]} The signature binds amount and recipient, so the facilitator cannot redirect funds.^{Source [9]}
11. Response (x402). The server returns 200 with a PAYMENT-RESPONSE header holding the SettleResponse, which includes the transaction hash.^{Source [4, 8]}
12. Publish feedback file (ERC-8004). The client writes the file with the required agentRegistry, agentId, clientAddress, createdAt, value and valueDecimals, plus proofOfPayment with fromAddress, toAddress, chainId and txHash.^{Source [2]} The file comes first.^{Source [2]}
13. Give feedback (ERC-8004). The client calls giveFeedback(agentId, value, valueDecimals, tag1, tag2, endpoint, feedbackURI, feedbackHash).^{Source [2]} The registry stores only value, valueDecimals, tag1, tag2 and isRevoked.^{Source [2, 12]}
14. Check the proof (ERC-8004 readers). A reader fetches the file from feedbackURI, compares feedbackHash, and looks up txHash. The registry never verifies the proof.^{Source [2, 12]}

Which protocol does what

x402 V2.0 is dated 2025-12-09 in the specification’s version table.^{Source [4]} ERC-8004 is still a Draft, and its last specification change before 2026-10-11 was on 2026-01-25.^{Source [2, 13, 14, 15]}

Where controls apply

• Before authorization. Client policy decides whether to pay. The TypeScript SDK applies spendControls by default: default assets only and at most $1 per payment.^{Source [16, 17]} Budgets beyond that are out of scope for x402 and live in SDKs and wallets.^{Source [4, 18]} A controls layer can also require a minimum ERC-8004 score from reviewers it trusts.^{Source [12]}
• At signing. Short validAfter and validBefore windows bound what a signature can do.^{Source [4]} Reading getAgentWallet just before signing catches a transferred agent, because a transfer clears agentWallet.^{Source [2, 19]}
• At the edge. Payment middleware or a CDN gateway sees every request before the handler.^{Source [20]} Matching the serving domain against the registration file and its /.well-known file is the ERC-8004 edge check.^{Source [2]}
• At settlement. x402 has no sanctions layer of its own; the CDP facilitator runs OFAC and Know Your Transaction checks.^{Source [21, 22]} SDK hooks such as onBeforeSettle let the server act before money moves.^{Source [18]}
• After the fact. The feedback file and giveFeedback are the record. A controls layer should score only feedback whose txHash resolves to a transfer to the agent’s agentWallet, because the registry checks none of it.^{Source [2, 12]}

What is observable from outside

On chain, an exact EIP-3009 payment shows only the token’s own Transfer and AuthorizationUsed events, so nothing marks it as x402.^{Source [9, 10, 23]} The NewFeedback event carries agentId, clientAddress, feedbackIndex, value, valueDecimals, the tags, endpoint, feedbackURI and feedbackHash; the last three exist on chain only in that event.^{Source [2]} Agent0 subgraphs on The Graph index Registered, MetadataSet, NewFeedback and FeedbackRevoked.^{Source [24]} Once published, the feedback file lets anyone join the review to the payment through txHash.^{Source [2]}

What stays private: the 402 exchange itself. Resource URLs, descriptions and amounts in x402 headers travel only between client, server and facilitator.^{Source [4, 25]} On-chain pointers and hashes cannot be deleted, so personal data does not belong in a feedback file.^{Source [2]}

What can go wrong

• Verification fails. Errors such as insufficient_funds or invalid_exact_evm_payload_signature stop the call before the handler runs.^{Source [4]} Nobody loses money.
• Settle times out. The outcome is indeterminate: settlement_pending is non-terminal and the server must reconcile before retrying.^{Source [4, 5]} The seller carries the risk of serving data it may not be paid for.
• Bad data after payment. The exact scheme defines no refund and x402 has no dispute process, so the client bears the loss.^{Source [26, 27]} Its only remedy in this scenario is a low score.
• Self-review or fake reviews. The contract rejects feedback from the agent’s owner or operators with “Self-feedback not allowed”.^{Source [12]} It does not stop Sybil reviewers, and the spec leaves that to filtering by trusted reviewers.^{Source [2]} One 2026 study found coordinated Sybil behavior among 90.6% of reviewers on Base.^{Source [28]}
• Fake proof. A txHash that pays someone else is not flagged on chain; getSummary still averages the value.^{Source [12]}
• Changed registration. A file served over HTTPS can change with no on-chain event.^{Source [2, 19]}

Costs fall on two parties. The facilitator pays settlement gas; the CDP facilitator makes the first 1,000 on-chain transactions each month free and then charges $0.001 each (as of 2026-10-11).^{Source [21]} The client pays the gas for giveFeedback, measured on 2026-10-11 at about 155,185 to 178,504 gas for a first feedback.^{Source [29]} Applications can sponsor that gas with EIP-7702.^{Source [2]}

Variants

• Solana instead of an EVM chain. The client sends a partially signed transaction, and the fee payer may be the merchant or a facilitator, named in extra.feePayer.^{Source [11]}
• The same call as an MCP tool. An unpaid tool call returns isError with the PaymentRequired object in structuredContent, and the client retries with _meta x402/payment.^{Source [30]} The seller’s registration file then lists an MCP service instead of a web one.^{Source [2]}

# Illustrative example, spec version x402 v2.0.
GET /discovery/resources?type=http&scheme=exact&network=eip155:8453&limit=20 HTTP/1.1
Host: facilitator.example

# response body
{
  "x402Version": 2,
  "items": [
    {
      "resource": "https://api.weather.example/weather",
      "type": "http",
      "x402Version": 2,
      "accepts": [
        { "scheme": "exact", "network": "eip155:8453", "amount": "10000",
          "asset": "0x8335...2913", "payTo": "0xB0B0...0B0B", "maxTimeoutSeconds": 60,
          "extra": { "name": "USD Coin", "version": "2" } }
      ],
      "lastUpdated": "2026-10-11T09:00:00.000Z"
    }
  ],
  "pagination": { "limit": 20, "offset": 0, "total": 1 }
}