x402 Protocol Guide: Payment Challenges, Settlement and Delivery

Start with a paid request, not an unsolicited transfer

Suppose a research agent requests a company report from a seller API. In this worked example the report costs an illustrative $0.05. The buyer wants one report for one company, with a predictable output format. The seller needs a way to describe the payment it accepts and to associate the payment exchange with that request.

The first request establishes what the buyer wants. A payment-required response describes acceptable terms. The client must evaluate those terms before asking its signer to act. Sending money to an address found elsewhere is not a substitute for completing the resource's documented payment exchange.

This guide uses the HTTP transport and V2 terminology checked on October 8, 2026. It explains the exchange and operating decisions without providing an untested package-install command. For executable integration code, use the official buyer or seller quickstart matching your pinned SDK and payment implementation. [2]

Read the current payment requirements

In V2, the server communicates a payment-required object using PAYMENT-REQUIRED. The client supplies its payment payload using PAYMENT-SIGNATURE, and the server reports a settlement result using PAYMENT-RESPONSE. These headers carry Base64-encoded JSON objects; Base64 is an encoding, not encryption or a reason to trust the contents. [2]

The buyer should inspect the advertised resource and accepted payment option. In the company-report example, confirm the seller endpoint, accepted scheme, network, asset, amount and recipient. Your application must also understand the asset's units before showing a human-readable price. A string containing an amount is insufficient to establish its value in dollars.

The payment client needs an implementation matching the selected scheme and network. An agent that can sign one kind of operation cannot automatically satisfy every entry the seller advertises. If no allowed option matches, return a clear unsupported-payment result rather than asking the model to improvise a transfer.

Keep the resource identity with the offer. If a redirect, changed host or modified endpoint changes the purchase scope, evaluate the new terms before signing. This is recommended buyer policy. It should not be presented as an extra protocol field invented by this guide.

Trace the default authorization flow

The current scheme documentation separates payment semantics from payment flow. In the default authorization flow, verification occurs before the resource handler, and settlement follows the handler. An upfront flow settles before the handler; an escrow flow has its own stages. Do not draw every x402 exchange as settlement first, work second. [3]

For our report example, the client first receives the offer and checks authority. It submits the supported payment payload with the resource request. The seller's payment layer verifies the authorization, the handler prepares the report, and the configured settlement stage runs before the final outcome is returned. This diagram is explicitly the default authorization path, not a universal order for every supported scheme.

Verification and settlement need separate states in the buyer's records. Verification means the configured checker accepted the relevant payment authorization. Settlement describes the selected method's financial result. A seller handler running between them does not mean the buyer has already received a response or that funds have necessarily reached a final state.

The final HTTP response also needs inspection. A successful status code is useful evidence of the interaction, but the buyer should parse the documented payment response and check the report body. A page that says payment received is not the company report the agent requested.

Understand scheme and network compatibility

A scheme describes payment semantics. The current overview distinguishes fixed-price exact payments, bounded usage through upto, accumulated authorizations through batch-settlement and auth-capture for an escrow-oriented lifecycle. A network implementation defines how those semantics are represented for that network. Actual SDK support must be checked separately. [3]

For a fixed-price report, a supported exact path is a natural starting point. That is a design choice for this example, not a requirement to use exact for every resource. A metered service may need another scheme and a clearer definition of maximum authorized cost versus final charge.

Do not copy a network or token from a documentation example into a real purchase without checking the current offer. Test networks, real networks and assets with similar names are distinct configurations. The source of truth for a particular purchase is the validated seller terms plus the supported capabilities of the buyer and facilitator being used.

A compatibility record should identify protocol version, transport, scheme, network, asset and relevant extensions. Keep that record next to the SDK versions. It is a practical way to investigate why two components displaying the same x402 logo cannot complete the same exchange.

Assign the facilitator and seller responsibilities

Coinbase's facilitator documentation describes a hosted service that validates signed payments, performs screening, submits settlement and returns a result to the resource server. Those are payment functions. The seller remains responsible for its endpoint and the report it promises. [4]

In the report workflow, identify which component decides that verification succeeded, which one runs the handler and which one interprets the settlement result. A failure at the facilitator should not appear as a fabricated successful report response. A failure in the report generator should not be described as proof that the payment provider failed.

Your seller agreement should also identify who handles refunds or result recovery where applicable. A facilitator performing settlement does not automatically create a dispute process for the report's contents. The buyer needs a documented contact or recovery route for a paid purchase that produces the wrong information.

Keep credentials for a hosted facilitator in the authorized server component. The purchasing model does not need those server credentials to understand the offer. Separate what the agent may request from what the backend must possess to process that request.

Bind permission to the purchase before signing

The buyer's policy for this example permits one report from the chosen seller up to $0.05. That permission is synthetic application policy, not an x402 guarantee. The protocol exchange describes payment; your organization still needs to establish who may approve a purchase and what spending is allowed.

Check the recipient, asset, network and amount together. A permitted amount sent to a different recipient is a different purchase. A permitted asset on an unsupported network may be unusable. Reject changed terms or request fresh approval according to your actual policy, rather than letting the agent decide that they are probably equivalent.

If several requests share one budget, reserve the intended cost at the policy boundary. A model prompt saying spend at most one dollar cannot by itself coordinate concurrent requests. The spending-limits guide covers the accounting decisions around reservations, confirmations and releases.

Recover from retries without guessing

A network timeout can occur after the server receives a request but before the buyer receives a response. The buyer should record the attempt as unresolved and investigate its state. Repeating the entire purchase with a new authorization could create another financial action, even when the buyer never saw the first result.

Keep a stable application purchase identifier and record the selected implementation's own identifiers. The application identifier is not a made-up x402 wire field. If you use a protocol extension for payment identifiers or idempotency, check its current specification and actual server support. Merely adding an identifier to a local log does not enforce anything at the seller.

A controlled retry should explain what it reuses and what it changes. Re-fetching an existing result, resubmitting a recognized attempt and creating a new paid purchase are different actions. Your retry policy should not allow a general agent recovery loop to switch between them silently.

For the report example, the safe recovery decision follows evidence. If the seller can return the already purchased report, use that route. If the payment is rejected definitively, a new authorized attempt may be appropriate. If payment status remains unknown, escalate or continue status resolution instead of spending again.

Handle changed terms and denied payments

If the offer expires or the seller returns different terms, retrieve the current offer and evaluate it again. Do not reuse an old approval for a different purchase unless the actual policy covers the change. The agent should tell the user which term changed and what decision is now needed.

A denied payment needs a reason category your application can act on. Unsupported scheme, policy rejection, insufficient funds and an unavailable provider require different remedies. Repeatedly trying the same denied request can waste work and obscure the original cause.

Keep errors understandable without revealing sensitive credentials. A reviewer needs the purchase reference, stage, relevant terms and available status evidence. They do not need private signing material copied into the incident record or generated article.

Verify delivery as a separate acceptance check

The company report must contain the requested company identifier and expected data structure. Reject an empty response or a report for another company before using it in the research task. The payment result can be correct while the resource result is wrong.

Record the delivered reference together with the confirmed purchase. If the report contains sensitive information, store only the evidence needed for the permitted workflow. A generic agent transcript may retain more content than a purchase log needs; choose that boundary deliberately.

Your acceptance checklist should include an ordinary purchase, denied authority, changed terms, an unsupported option and a timeout after submission. Describe the observed environment and outcome when you test. This article's synthetic example is not evidence that we completed a live purchase or measured provider reliability.

Choose the buyer or seller implementation next

If your agent buys reports, follow the buyer integration matching its wallet or signer. If you sell reports, implement the payment layer around the resource handler and define its recovery behavior. These routes share an exchange but have different responsibilities and secrets.

X402 Hub is an affiliated product for x402 paid-resource discovery and payment integration. MagicPay connects agents to user-authorized purchase workflows with approval and budget controls. Their links are relevant to the financial workflow, and the affiliation is disclosed. Neither recommendation replaces checking the seller's actual accepted method and delivery contract.

Before expanding beyond one report endpoint, save the compatibility record and failure decisions. Future maintainers should see which V2 headers, payment flow and implementation were used. That is more useful than an integration note saying only that x402 works.