← All guides · Selling to AI agents

How to Accept x402 Stablecoin Payments: A Seller Implementation Guide

Part 4 of Selling to AI agents · 1,616 words · published 2026-07-31 · updated 2026-08-19 · Markdown variant

A build guide for sellers who have already decided x402 is the right rail: the 402 response shape, the wallet/facilitator/network choices, the verify-then-settle retry flow, exact vs. upto pricing, and how to ship it dormant until you are ready to go live.

Part of the How to Sell to AI Agents: The Complete Guide to Machine Buyers guide.

This picks up exactly where ACP vs. AP2 vs. x402 leaves off. If you have not yet decided x402 is the right rail — if you are not sure your buyer is software spending its own wallet, rather than a human's shopping agent — start there first; this article assumes that decision is already made and covers only the build.

It is also the seller-implementation layer of selling to AI agents, which names x402 as one of four live payment rails at the checkout stage of the machine purchase funnel without going into how to build it. Selling to agents lays out x402 as one of four charging options at a glance; this article is the deeper "how do I actually build this" pass on that one option — the choices you have to make, the request/response contract you have to implement, and a launch pattern for shipping it safely before you are ready to take real money.

The 402 response: an accepts array, not a single price

An x402 seller endpoint answers an unpaid request with 402 Payment Required and a JSON body carrying x402Version and an accepts array of PaymentRequirements objects — not a bare price string. Each entry in that array describes one way to pay: which scheme, which network, how much, and where to send it. A minimal seller only ever returns one entry; the array shape exists so a seller can, in principle, offer more than one acceptable network or asset in a single response and let the client pick.

A schematic PaymentRequirements object, matching the field set and order a seller endpoint builds (illustrative values only):

{
  "x402Version": 1,
  "error": "X-PAYMENT header required",
  "accepts": [
    {
      "scheme": "exact",
      "network": "base",
      "maxAmountRequired": "50000",
      "resource": "https://example.com/api/x402/some-slug",
      "description": "Example premium resource",
      "mimeType": "text/markdown",
      "payTo": "0xExampleSellerWalletAddress",
      "maxTimeoutSeconds": 60,
      "asset": "0xExampleUSDCContractAddress"
    }
  ]
}

An optional trailing extra: { name, version } object can carry EIP-712 token metadata when a seller wants to name the asset explicitly (e.g. "USDC", version "2"); it is only present when the operator has configured it, not on every response. Full protocol mechanics — the CAIP-2 network list, the eleven supported chain families, the facilitator model — are documented in agentic payment protocols; this section covers only what the response has to contain for a client to act on it.

Four decisions before you write any settlement code

Building the endpoint is the easy part; the decisions that go into x402Requirements are the ones that matter, and they are operator decisions, not code:

• Wallet (payTo). An address you control that can receive stablecoin transfers on your chosen network. This is where every settled payment lands — treat it with the same care as a bank account number, because a typo here sends real money to an address you do not control.
• Facilitator. A third-party service that verifies signed payment authorizations and settles them on-chain so you never have to run node infrastructure yourself. Coinbase runs a public facilitator at x402.org and a fee-free CDP-hosted facilitator for USDC on Base; the protocol does not mandate Coinbase infrastructure, so a third-party facilitator is a legitimate substitute if you vet its trustworthiness first.
• Network and asset. Which chain and which token you settle in. USDC is the ecosystem's dominant stablecoin, and the spec formally supports eleven CAIP-2 network families — any EVM chain, Solana, TON, Algorand, Stellar, Aptos, Hedera, Keeta, NEAR, Concordium, and XRPL — but your facilitator has to actually support whichever pair you pick.
• Price, in atomic units. maxAmountRequired is a string in the asset's smallest unit, not a decimal dollar amount. USDC has 6 decimal places, so a five-cent price is the string "50000", not "0.05". Get this wrong and you either give the resource away or price it a thousand times too high.

Authenticating to your facilitator is a fifth, smaller decision: some facilitators (Coinbase's CDP-hosted one, notably) require a per-request signed JWT from a CDP API key rather than a static bearer token, because a static credential cannot satisfy that authentication scheme. Confirm which your facilitator expects before you build the calling code, not after.

The retry flow: X-PAYMENT, then two facilitator calls

A client that receives your 402 signs a transfer authorization against one of your accepts entries and retries the same request with a base64-encoded X-PAYMENT header. Your server does not settle anything itself — it hands that header to your facilitator in a two-call round trip:

1. Client retries:  GET /priced-thing
                    X-PAYMENT: <base64-encoded signed PaymentPayload JSON>

2. Server -> facilitator:  POST <facilitator-url>/verify
                           { x402Version, paymentPayload, paymentRequirements }
   Facilitator -> server:  { "isValid": true }   (or a rejection with an invalidReason)

3. Server -> facilitator:  POST <facilitator-url>/settle
                           { x402Version, paymentPayload, paymentRequirements }
   Facilitator -> server:  { "success": true, ... }   (or a rejection with an errorReason)

4. Server -> client:  HTTP/1.1 200 OK
                      X-PAYMENT-RESPONSE: <base64-encoded settlement receipt JSON>
                      <resource body>

Only a success on both calls earns the 200. A design worth copying regardless of which facilitator you use: distinguish your failure modes so a client's retry logic can tell them apart — a /verify rejection is a bad or insufficient payment (retryable with a corrected authorization), a /settle rejection is a settlement failure after the payment looked valid, and a facilitator that will not respond at all (network error, malformed JSON) is an infrastructure problem on your side, not the buyer's. Returning three different error shapes for those three different causes is more useful to an agent than collapsing them into one generic "payment failed."

exact vs. upto: fixed price or metered ceiling

x402 defines two payment schemes, and picking the wrong one either overcharges you in code complexity or undercharges you in practice:

• exact authorizes a fixed amount known upfront. This is the right shape for anything with a flat, posted price — a document, a single API call, a fixed-cost resource fetch.
• upto authorizes a ceiling and charges actual usage at completion, via a deposit-and-refund mechanism. This is the shape to reach for when the true cost of a request is not known until it finishes — Apify uses upto for its variable-cost Actor runs, where a scrape might take one page or a hundred.

Be precise about which one you are actually implementing: ChangeGamer's own x402 endpoint implements only exact. Every request it builds carries "scheme": "exact", because every premium resource on this site is a fixed-price fetch — there is no metered, variable-cost work behind the gate that would justify the deposit-and-refund complexity upto requires. If your resource is a flat document or API call, exact is not a limitation to work around; it is the correct scheme and the simpler one to build.

Discovery is not a separate step

The x402 Bazaar — Coinbase's discovery catalog — auto-lists a seller endpoint the first time its facilitator settles a real payment for it, with no listing form, review queue, or separate registration step; the mechanism itself is covered in full in agentic payment protocols and selling to agents. The practical implication for a seller shipping the dormant pattern above: there is nothing to configure for discovery before you go live. The catalog entry follows automatically from your first settlement, not from anything you build or submit separately.

Ship it dormant: a fail-closed launch pattern worth copying

You do not have to have a wallet, a facilitator contract, and a signed-off price ready on day one to start writing the endpoint. A safer sequence is to build the full request/response contract first and gate it behind a single hard check that fails closed until every operator setting exists — then wire up the wallet and facilitator later, on your own schedule, without a code deploy in between.

ChangeGamer runs exactly this pattern, and as of July 2026 it is in the "built but not yet turned on" state, not a live example of settlement. Its /api/x402/<slug> endpoint requires all five of X402_FACILITATOR_URL, X402_PAY_TO, X402_NETWORK, X402_ASSET, and X402_MAX_AMOUNT to be set — if even one is missing, every request short-circuits to 503 x402_not_configured before any PaymentRequirements object is even built, regardless of whether the caller sent an X-PAYMENT header. The check also runs per-resource, not site-wide: a request for a slug that is not, as of July 2026, in the premium set gets 400 resource_is_free instead, because there is nothing to sell at that URL. Only a request for an actual premium resource, on a server with all five settings present, reaches the 402-or-settle logic at all. Which resources are actually in that premium set, and what each costs as of July 2026, is not repeated here — it is kept current in one place, access and pricing, rather than duplicated across every article that mentions the gate.

The reason this is worth copying rather than just noting: it lets you write, test, and even deploy the entire facilitator-calling code path with zero risk of a malformed payment requirement reaching a real client, or a misconfigured payTo address receiving funds you cannot recover, because the whole path is provably unreachable until an operator deliberately flips five specific switches. As of 31 July 2026, ChangeGamer has not flipped them — the endpoint is real code, live in the sense that it answers requests, and dormant in the sense that it has never settled a payment. That is a stated design choice, not an outage.

For the buyer-side half of this same loop — what a client library does with your accepts array, how it manages a funded wallet, and why upto matters more to a buyer than a seller — see agent wallets: paying per run with x402.

#payments #x402 #agents #monetization #402 #stablecoins