How x402 Makes API Payments Work Over HTTP
HTTP APIs usually assume that access has already been granted through an account, subscription, or API key. x402 changes that boundary: a server can return HTTP 402 with machine-readable payment requirements, allowing a client to pay and retry the request. For API developers, tool builders, and agent-platform teams, this makes per-request access possible within an HTTP interaction, without requiring a separate checkout page. This explainer follows the payment handshake and examines what the protocol does—and what it leaves to applications and payment infrastructure.
Why x402 Is Being Discussed
Software increasingly consumes services directly. A backend may need one weather lookup, a data pipeline may need a single enrichment result, or an AI agent may need to call a paid tool while completing a task. Traditional billing often asks the service consumer to create an account, obtain a credential, and accept a recurring plan before making those requests.
That model works well for ongoing relationships, but it can be awkward for occasional or machine-to-machine use. x402 proposes a common HTTP-level interaction for discovering a price and providing payment authorization as part of a resource request. The x402 project describes the protocol as an open, neutral standard for internet-native payments. It is receiving attention because it connects a familiar web request with a programmatic payment flow; it does not make every API free of accounts, policies, or operational dependencies.
What Is x402?
x402 is a protocol convention for requesting payment when a client asks for a resource. The service responds with the HTTP status code 402 Payment Required and structured details about the payment it accepts. A compatible client can evaluate those requirements, authorize a payment using its configured wallet or signer, and retry the request with payment information.
The IETF’s HTTP Semantics specification, RFC 9110, defines the 402 status code but reserves it for future use; it does not specify x402’s payment fields or flow. The x402 HTTP 402 documentation describes how the protocol uses that status and, in version 2, standardized headers to carry payment requirements and results.
x402 is not itself a blockchain, wallet, stablecoin, card processor, or universal billing platform. It defines a way for a client and service to negotiate payment around an HTTP request. The payment scheme, asset, network, facilitator, and business rules depend on what the service supports and what the client chooses to use.
The Problem x402 Tries to Solve
An API key identifies a caller or grants access under a service’s policy; a subscription establishes an ongoing billing relationship. Both are useful, but they can require provisioning before a client can make a single purchase. A card checkout can work for people, yet an automated program cannot reliably fill forms, complete interactive authentication, or manage a separate subscription for every endpoint it calls.
With x402, the service can disclose its accepted payment terms only when a client requests a protected resource. This creates a standard point at which a program can decide whether a call is worth paying for. It can suit metered data, one-off digital resources, or API calls purchased by a backend or an agent.
The protocol does not remove authorization or identity requirements. A paid endpoint may still require an account, enforce geographic restrictions, limit request volume, or reject a payment from an unsupported network. Payment also does not grant permission to access unrelated resources. Service operators must define the relationship between payment and access explicitly.
How the x402 Payment Flow Works
The basic interaction is a challenge followed by a payment-authorized retry:
- The client requests a resource. It sends an ordinary HTTP request to an endpoint that may require payment.
- The service responds with a payment challenge. If the request lacks acceptable payment information, the service returns
402 Payment Requiredand describes supported payment options, such as a price, destination, asset, network, and scheme. - The client evaluates the terms. A wallet or signer can prepare payment authorization. A safe client should check that the endpoint, amount, asset, and destination match its policy before signing.
- The client retries with payment information. In x402 version 2, the
PAYMENT-SIGNATUREheader carries an encoded payment payload. The payload represents authorization; it is not, by itself, proof that funds have settled. - The service verifies and settles. The server can ask a facilitator to verify the payment payload and, if valid, execute the requested work. It then requests settlement according to the supported scheme. The CDP x402 flow documentation describes this sequence for its facilitator.
- The service returns the resource and payment result. A successful response contains the requested content and may include a
PAYMENT-RESPONSEsettlement result. The exact timing of settlement depends on the payment scheme; some schemes settle during the request, while others can defer settlement.
This sequence keeps the payment interaction within the client-server exchange, but it is not a single universal transaction implementation. Clients and services must agree on protocol versions, payment schemes, networks, and supported assets.
| Dimension | API key or subscription | x402 per-request payment |
|---|---|---|
| Access setup | A provider issues credentials or provisions a plan | A service can advertise payment terms in response to a request |
| Billing unit | Often a plan, quota, or aggregated usage period | Can be tied to a particular resource request |
| Client identity | Usually linked to an account, key, or organization | Payment authorization identifies a transaction, but need not establish a user account |
| Repeated usage | Convenient for ongoing access and predictable quotas | Useful for occasional or metered access when supported by the service |
| Payment infrastructure | Provider’s billing system and configured payment methods | Compatible wallet or signer, payment scheme, network, and often a facilitator |
| Limits and policy | Credentials can be revoked or scoped by the provider | The service still needs authorization, abuse controls, and spending rules |
These approaches can coexist. An API may use an API key for customer identity and quotas while offering x402 for per-request billing. Neither the protocol nor a successful payment challenge automatically replaces rate limits, access controls, or a provider’s terms of service.
Components and Key Concepts
Buyer and client. The buyer is the person, service, or agent authorizing payment. Its client implementation interprets payment requirements and creates a payment payload using a wallet or signer. Clients should not sign arbitrary challenges automatically: they need limits on approved endpoints, maximum amounts, allowed assets, and permitted networks.
Resource server. The server decides which resources require payment, advertises accepted terms, and controls whether a request proceeds. It must validate payment information and apply its own access policy. A 402 response is a challenge, not evidence that a caller has paid.
Facilitator. A facilitator can verify and settle payment messages on behalf of a service. This reduces the need for the service to implement every payment integration itself, but introduces a dependency on the facilitator’s correctness, availability, supported networks, and operational policies. The service remains responsible for deciding what to serve and handling verification or settlement failures.
Payment scheme, network, and asset. A scheme defines the payment behavior; a network and asset describe where and in what form a payment is authorized or settled. Support is not universal. Buyers and sellers must use compatible combinations, and operators should state which combinations they actually accept.
Versioned HTTP headers. For x402 version 2, the PAYMENT-REQUIRED response header carries payment requirements, PAYMENT-SIGNATURE carries the client’s payment payload on retry, and PAYMENT-RESPONSE can report settlement results. These values encode structured data. Integrations should use a compatible library and follow the versioned documentation rather than assume header names or payload formats are identical across protocol versions.
Real-World Use Cases
- Metered data APIs: A caller can pay for an individual lookup instead of enrolling in a recurring plan, when the provider supports that pricing model.
- Digital resources: A service can offer programmatic access to a specific dataset, generated asset, or other resource behind a payment challenge.
- Agent tool calls: An agent’s application can decide whether to pay for a data source or tool during a workflow, subject to spending limits and approval rules. A2A protocol architecture covers a different boundary: how independently operated agents exchange tasks and results.
- Backend-to-backend services: A service can purchase a narrowly scoped response from another API without building a separate interactive checkout into its own workflow.
These are architectural options, not protocol guarantees. The service must still explain its price, handle failed payments, protect paid resources from abuse, and provide a way to resolve billing disputes where applicable.
Getting Started: Inspect a Paid Endpoint
Begin with a sandbox endpoint provided by the service operator. A basic request can reveal whether it returns a payment challenge without authorizing or sending funds:
export X402_TEST_URL="https://sandbox.example.org/v1/resource"
curl --include --max-time 10 "$X402_TEST_URL"
Replace the example URL with an endpoint you are authorized to test. Inspect the response status and payment requirements, then compare the required amount, destination, asset, network, and scheme with the service’s documentation. An HTTP 402 response is not a payment and should not be treated as proof of settlement.
Before enabling a buyer integration, test it in a provider-supported sandbox and confirm that it:
- refuses challenges from unapproved hosts or unsupported networks;
- applies a maximum spend per request and an aggregate budget;
- validates payment requirements before asking a wallet or signer to authorize them;
- handles declined, malformed, expired, or unverifiable payloads without releasing the resource;
- distinguishes verification from settlement and checks the final payment result;
- handles timeouts and retries without unintentionally charging twice; and
- records a request identifier and outcome without logging private keys or sensitive signing material.
On the service side, test that a free or unpaid request receives the intended challenge, invalid payment data is rejected, and successful payment only unlocks the resource covered by that challenge. Keep authorization, request quotas, and fraud controls in place; API rate-limiting practices address abuse controls that payment does not replace.
Common Misconceptions
“HTTP 402 is the payment.” The status code signals that payment is required. The client and service still need compatible payment details, a valid authorization, and a successful outcome under the selected scheme.
“x402 defines a universal payment rail.” x402 standardizes a payment interaction, not one asset, blockchain, facilitator, or settlement model. Implementations need to agree on supported schemes and networks.
“An agent can safely spend because the protocol is machine-readable.” A structured challenge makes terms easier to process; it does not decide whether a purchase is worthwhile or authorized. The application must enforce spend limits, restrict destinations, and require human approval where the potential cost or consequence warrants it.
“A facilitator removes trust and operational risk.” Delegating verification and settlement shifts implementation work but creates dependencies. Services need clear failure handling and must verify the result before returning paid content.
Related Articles
- A2A protocol architecture explains agent-to-agent task delegation.
- Model Context Protocol (MCP) describes how AI applications connect to tools and data.
- API rate-limiting implementation covers quotas and abuse controls.
- Payment processing systems explains conventional payment components and settlement.
Changelog and Last Updated
Initial publication. This explainer focuses on the HTTP payment handshake and the trust boundaries around paid API and agent requests.

