FAQ
x402 FAQ for Developers
Short answers for the questions developers hit while turning the x402 flow into code.
Basics
If a term in these answers is unfamiliar, keep the glossary open in another tab. The main trick is remembering that x402 is still HTTP: requests, responses, status codes, headers, and resource handlers remain visible and testable.
"The 402 (Payment Required) status code is reserved for future use."
What is x402 in practical terms?
x402 is an HTTP payment pattern for paid resources. A client requests a resource, the server responds with HTTP 402 and payment requirements, the client retries with a signed payment payload, and the server serves the resource after verification and settlement.
Is HTTP 402 a normal standardized payment flow?
No. RFC 9110 says the 402 Payment Required status code is reserved for future use. x402 builds a concrete protocol around that reserved status code for programmatic payments.
Should I start on mainnet?
No. The official seller quickstart begins with testnet configuration. Use testnet settings while learning route behavior, wallet setup, facilitator behavior, and failure states.
Roles
x402 becomes easier when you separate the three roles. Sellers protect and serve resources. Buyers or buyer agents decide whether to pay. Facilitators help verify and settle. Some teams will own more than one role, but the responsibilities should still be reviewed separately.
What does a seller need to define?
A seller defines a paid route, accepted payment requirements, price, network, receiving address, description, and content type. The seller also owns logs, failure behavior, and whether the paid resource is served.
What does a buyer agent need before it can pay?
It needs a funded wallet for the selected network, a registered x402 client scheme, payment-aware HTTP client handling, and a policy that limits hosts, networks, prices, and budgets.
What is a facilitator?
A facilitator is an optional service that helps verify payment payloads and settle payments onchain for a resource server. It reduces operational complexity but does not replace seller-side product and safety decisions.
Does the facilitator custody funds?
The x402 facilitator docs describe the facilitator as verifying and executing transactions based on signed payloads; it does not act as a custodian in that model.
Which networks does x402 support?
The official network docs describe support across EVM, Solana, TON, Algorand, Stellar, Aptos, Hedera, Keeta, and Concordium namespaces, using CAIP-2 style network identifiers.
Safety and production readiness
Production readiness is not just "the paid request works." You need failure paths, idempotent retry behavior where possible, route-level logs, wallet budget limits for agents, and a source-of-truth checklist for current SDK and network behavior.
What is the safest first project?
A read-only JSON endpoint on testnet. Confirm unpaid requests return 402, paid requests return the resource, and invalid payments do not leak the resource.
How should agents handle retries?
Use the payment-identifier extension where the server declares support, persist one logical payment ID across retries, and avoid blind retries when the payment outcome is unknown.
Is x402 Academy a replacement for docs.x402.org?
No. x402 Academy is a tutorial site. Use the official docs and SDK repository for current package names, signatures, supported networks, and production instructions.
Sources used
- x402 docs: Introduction
Defines x402 as an open payment standard for charging APIs and content directly over HTTP.
- x402 docs: HTTP 402
Explains how x402 uses HTTP 402 to communicate payment requirements.
- x402 docs: Quickstart for Sellers
Official seller setup, package installation, testnet defaults, and payment middleware examples.
- x402 docs: Quickstart for Buyers
Official buyer setup, client package installation, and fetch/axios payment wrappers.
- x402 docs: Facilitator
Defines facilitator responsibilities for payment verification and settlement.
- x402 docs: Networks and Token Support
Documents CAIP-2 network identifiers and supported network namespaces.
- x402 docs: Payment-Identifier extension
Documents idempotency support for retries without duplicate payment processing.
- RFC 9110: HTTP Semantics, section 15.5.3
The HTTP specification reserves status code 402 for future use.