Accept AI Agent Payments for Your API with x402

Define the resource your buyer purchases

Suppose you sell one structured supplier report through an API. In this synthetic example the advertised price is $0.05. The request identifies a supplier; the response contains that same identifier, a source date and the report. Define this purchase unit before adding payment middleware.

The buyer needs to know whether the price covers one response, a reusable result or metered work. State input requirements and the output promise plainly. A description such as AI financial intelligence does not tell an agent how to build a valid request or recognize delivery.

Define failures before charging. Invalid input, unavailable data and report-generation errors should have understandable outcomes. Payment handling needs to fit the resource contract rather than hiding every application error behind payment required.

The minimal server below adapts the official seller quickstart checked 8 October 2026, using a development network and synthetic report. It has not been executed for this article. The illustrated curl exchange is an expected transcript, not an observed payment. Pin actual package versions in your project before running an integration. [2]

Pin the payment implementation and receiving details

Coinbase's current seller quickstart describes payment middleware around selected HTTP routes and a configured receiving destination. It distinguishes server authentication for the facilitator from the address receiving funds. Your integration needs both responsibilities assigned correctly. [2]

Record the protocol and SDK revisions you use. Actual imports, configuration shapes and supported networks belong to those versions. A sample from another revision can look plausible while producing different behavior. Keep the working reference with the project rather than treating an isolated code fragment as permanent documentation.

Choose a scheme and network your intended buyers and payment implementation support. Each advertised option needs a configured server implementation and a receiving destination matching it. Do not advertise every theoretical combination merely because the protocol is extensible.

Separate test configuration from real spending. Record which environment produced each result and verify production receiving details explicitly. A response on a test network does not establish receipt of a real asset or satisfaction of every production condition.

Place payment handling around the resource handler

The server identifies the protected route and constructs its payment requirements. When an appropriate payload arrives, the payment layer evaluates it and handles the selected lifecycle. The report handler runs within that lifecycle rather than deciding payment validity itself.

Current x402 scheme documentation distinguishes default authorization, upfront and escrow flows. The default authorization path verifies before the resource handler and settles after it. Name the chosen flow in your architecture rather than asserting that every x402 payment settles before work starts. [3]

Our fixed report example uses that default path. The diagram shows request validation, verification, preparation and settlement. A differently configured flow needs its own ordering and failure decisions. A generic arrow labeled paid cannot express those differences.

Preparing a report, establishing the financial outcome and sending a response are separate events. The payment layer should not claim that the buyer received the report merely because the handler generated it in memory. Preserve evidence for both the payment and the delivery stage.

Expose usable requirements and output information

The buyer needs the current resource and supported option. Its client selects a compatible scheme and network, then evaluates amount and recipient. Publish those terms through the documented schema instead of inventing extra fields that appear authoritative.

Keep the report description aligned with the endpoint. If a required identifier changes or an output field disappears, update the resource documentation and discovery metadata. A payment challenge that still parses does not prove the buyer can use the response.

Return understandable errors for malformed or unsupported requests. The buyer should know whether to correct input, choose another supported payment option or stop. Avoid success messages that leave an agent guessing whether it purchased access, submitted money or received a report.

The code panel uses documented createX402Server and Express middleware interfaces. Its receiving address and facilitator credentials come from your environment; no credential belongs in an article or browser script. The synthetic response demonstrates structure only. Follow the current official quickstart for prerequisites, package versions and a complete implementation, then inspect the exchange in your own environment. [2]

import express from "express";
import { paymentMiddlewareFromHTTPServer as gate } from "@x402/express";
import { createX402Server as configure } from "@coinbase/cdp-sdk/x402";

const receiver = process.env.X402_PAY_TO;
if (!receiver) throw Error("A testnet receiving address is required");
const api = express();
const payment = await configure({
  environment: "development",
  payToConfig: { type: "address", evm: receiver as `0x${string}` },
  routes: {
    "GET /report": {
      networks: ["eip155:84532"],
      price: "$0.05",
      description: "Synthetic supplier report for SUPPLIER-42"
    }
  }
});
api.use(gate(payment));
api.get("/report", (_request, response) => response.json({
  supplier_id: "SUPPLIER-42",
  source_date: "2026-10-08",
  report: "Synthetic teaching data; no real supplier assessment."
}));
api.listen(8402);

// Expected unpaid transcript; not executed:
// curl -i http://localhost:8402/report
// HTTP/1.1 402 Payment Required
// PAYMENT-REQUIRED: <base64-encoded PaymentRequired object>
// No payment signature is supplied by this curl command.

Validate the paid resource separately from payment

Check the supplier identifier and required arguments before using them in a report generator. Payment does not prove that input is valid or that the buyer should access every internal dataset. The public contract needs a defined resource scope.

Separate this route from administrative functions. A buyer paying for one report should not gain permission to change prices, alter receiving destinations or retrieve another customer's purchase record. Keep the operation exposed to the agent narrow enough to match the actual product being sold.

If the report depends on external data, define expected freshness and unavailable-data behavior. Do not invent a universal accuracy claim. The result should provide the evidence the buyer needs to assess suitability for its finance task.

A fixed price can cover varying content, but acceptance still needs to be meaningful. An empty response or report for the wrong supplier fails the resource promise. Otherwise payment success becomes the only observable result while the actual purchased service remains undefined.

Record financial outcome and delivery independently

Connect accepted terms, the payment attempt, its authoritative outcome and the report reference. Use actual protocol or provider references where available and an application purchase record for your own bookkeeping. A local record is not a substitute for financial evidence.

If preparation succeeds but settlement fails in the selected flow, preserve both facts and use the documented response behavior. If settlement succeeds but the connection drops, preserve the generated result so recovery can address the existing purchase rather than creating another charge.

Keep private credentials out of general logs. An operations record needs enough information to explain and resolve the purchase, but should not become an uncontrolled archive of signing authority or sensitive supplier data. Define which records operators can inspect.

Also define retention for purchased results. The protocol does not decide how long you owe retrieval or how a buyer proves it owns an earlier purchase. Those obligations belong in the seller contract and application behavior, with a recovery route the buyer can understand.

• Local purchase record: supplier, accepted offer, chosen scheme/network/asset and amount.
• Payment evidence: actual provider/protocol outcome and transaction reference when available, kept alongside the returned PAYMENT-RESPONSE.
• Delivery evidence: report reference and supplier/structure validation result. These local fields are not a replacement for the settlement-response schema.

Handle retries as one logical purchase

A buyer can lose a response after submitting a valid payload. Define recognized retries and result recovery. Running the paid handler again without that policy can create duplicate computation, another financial action or confusion about which result belongs to which purchase.

The x402 payment-identifier extension describes advertised server support and deduplication tied to an identifier and request binding. Verify the behavior of the actual implementation. An application ID written into a local log does not create the protocol capability. [4]

Bind retry evidence to the relevant resource scope. Reusing an identifier for another supplier or amount should not return an unrelated cached report. Define how conflicts are handled and how long recognized-attempt state remains available.

Multiple server processes also need consistent evidence. An in-memory record in one process does not prove another process recognizes the attempt. Use the required shared or durable mechanism and test its failure behavior. An identifier does not guarantee one outcome forever when the state enforcing it is absent.

Publish accurate discovery metadata

The current Bazaar seller guide describes making paid resources discoverable through metadata. Describe the actual request method, required inputs, expected output and relevant payment terms. Discovery is separate from evidence that a buyer successfully purchased the resource. [5]

For the supplier report, explain the identifier format and returned source date. These details help an agent construct a useful request. A description filled with generic AI keywords does less for the buyer than a clear input schema and output example.

Inspect cataloging evidence using the documented feedback. A configured extension does not establish that every catalog lists the endpoint or that it has a high rank. Do not invent listing counts or expected traffic to justify the integration.

When service terms change, update discovery and endpoint documentation together. A buyer should not have to pay to learn that the advertised interface no longer matches the live resource. Assign ownership of those updates alongside the paid-route configuration.

Test the payment and the report outcomes

Start with an unpaid request returning the intended requirements. Then perform a permitted test purchase through the chosen buyer implementation. Inspect the actual financial outcome and report. Record the environment so test evidence is not described as real-money production activity.

Add invalid input, rejected payment, unavailable verification, handler failure and a lost response after submission. Each case needs an understandable state and recovery action. A correct rejection belongs in acceptance rather than being concealed behind a demonstration containing only successful requests.

Verify the receiving destination independently for the actual asset and network. Server authentication and payment destination have different purposes. A successful call to a facilitator does not establish that funds reach the address your business intends.

Validate the report from the buyer's perspective. It should contain the requested supplier identifier and agreed structure. If an agent uses the report in a financial assessment, it needs the promised source evidence too. Complete payment integration connects an authorized financial outcome to a useful delivered resource.

• Unpaid request: expect current requirements, not a delivered paid report.
• Invalid supplier input: reject according to the resource contract before generating the report.
• Rejected authorization: no successful paid resource response.
• Verification unavailable: preserve the failure reason and do not guess approval.
• Handler failure: retain processing stage and apply the configured flow’s failure behavior.
• Lost final response: investigate the original attempt before a new paid request.
• Same retry ID with changed supplier or amount: exercise the documented conflict path.

Connect the resource to the relevant product workflow

X402 Hub provides x402 paid-resource discovery and payment integration. Agentify Commerce lets merchants publish digital offers, accept supported USDC/x402 payments directly to their wallet and connect order, payment and delivery references. Both are affiliated with this publisher. For an API report, choose the actual paid-resource route; use the merchant catalog route where the report is packaged as a supported digital offer. [6] [7]

Choose a product route from the actual resource and buyer journey. A paid API response, a merchant checkout and a catalog listing have different integration needs. Use the seller contract and supported interface to determine where each component belongs instead of inserting the same recommendation at every stage.

Keep a handoff record containing the priced route, implementation revisions, configured payment flow, receiving destination, delivery promise and recovery decisions. Another engineer should be able to explain why a request is charged and what happens when only part of the purchase succeeds.

The seller's objective is a purchase that both sides understand. The buyer receives the promised report, the seller receives the configured financial outcome, and unresolved cases preserve enough evidence for recovery. That gives the agent a dependable contract to use while leaving future products and payment routes as explicit integration choices.