x402 Protocol: Implementing HTTP 402 Payments for APIs and AI Agents

What the x402 protocol actually standardizes

The x402 protocol is an open, neutral specification for internet-native payments built on top of the long-dormant HTTP 402 Payment Required status code. Instead of redirecting a client to a checkout page, an x402-enabled server answers an unpaid request with a 402 response whose body contains machine-readable payment instructions: how much to pay, to whom, on which network, and under which payment scheme. The client constructs a payment payload, resubmits the request with an authorization header, and a facilitator verifies and settles the payment before the server releases the resource.

The important design property is that payment negotiation happens inside ordinary HTTP. There is no separate session, account creation, or API-key provisioning step in the base flow. That makes x402 a natural fit for API monetization and for AI agents that need to buy small units of data or compute without a human completing a signup form. The specification is deliberately network-agnostic: it aims to support multiple chains and forms of value, with individual schemes defining the exact payload format.

This guide treats the protocol as documented behavior plus implementation choices you must test. It does not claim specific throughput, fee, or finality numbers for any chain or provider; those depend on the rail you select and must be measured on your own deployment.

• Documented: the 402 challenge/response shape, payment instructions in the response body, and facilitator-based verification and settlement.
• Your decision: which network and scheme to accept, which facilitator to trust, and how much latency your use case tolerates.
• Your measurement: end-to-end paid-request latency, settlement confirmation time, and failure rates under load.

Assumptions and prerequisites before you build

The walkthrough below assumes you have a Node.js service (Express-style middleware is the most commonly documented integration), a funded client wallet on a test network, and access to an x402 facilitator endpoint. It also assumes you can reach a reliable RPC endpoint for the settlement network, because both the facilitator and your own verification logic need to read chain state.

Keep secrets out of source control: load PRIVATE_KEY and any facilitator credentials from environment variables. Use a dedicated test wallet, never a production key. If you are still choosing a settlement network or an RPC provider, the multi-chain RPC endpoints guide explains how endpoint quality affects confirmation visibility, and the RPC endpoint guide covers the basics of authenticated endpoints.

• Node.js 18+ and a package manager.
• An x402 server SDK or middleware package compatible with your framework.
• A test-network wallet with a small balance of the accepted asset.
• A facilitator URL and an RPC_URL for the settlement network.
• A staging environment where failed payments cannot affect real customers.

The x402 request lifecycle as a mental model

Think of x402 as a four-step handshake that can complete inside a single client retry. First, the client requests a protected resource without payment. Second, the server responds with 402 Payment Required and a body describing acceptable payment options. Third, the client selects an option, authorizes a payment, and retries the original request with a payment header. Fourth, a facilitator verifies the payload and settles it, and the server returns the resource.

Two details matter for debugging. The 402 response is not an error in the traditional sense—it is a structured offer, so its body must be parseable and stable. And settlement is asynchronous relative to verification in many implementations: the facilitator may confirm validity before final on-chain settlement, which means your server should decide explicitly whether to release the resource on verification or on settlement. Document that choice, because it determines your exposure to failed or reversed payments.

• Challenge: unpaid request receives 402 plus payment requirements.
• Authorization: client signs or constructs a payment payload and retries.
• Verification: facilitator checks the payload against the declared requirements.
• Settlement: value moves on the chosen rail; server releases the resource.

Gating an API endpoint with payment middleware

The smallest useful integration declares which routes require payment and what the server accepts. The configuration below is illustrative: replace the placeholder network, asset, pay-to address, and facilitator URL with values from your own facilitator documentation. The shape—route map plus an accepts array—is the part that generalizes across SDKs.

Notice that the middleware does not contain business logic. It intercepts unpaid requests, emits the 402 challenge, and delegates verification. Your handler runs only after the payment path succeeds, which keeps monetization concerns separate from data concerns.

import express from "express";
import { paymentMiddleware } from "@x402/express";

const app = express();

app.use(
  paymentMiddleware(
    {
      "GET /v1/weather": {
        accepts: [
          {
            scheme: "exact",
            network: "base-sepolia",
            maxAmountRequired: "10000",
            resource: "https://api.example.com/v1/weather",
            payTo: process.env.PAY_TO_ADDRESS,
            asset: process.env.SETTLEMENT_ASSET,
            maxTimeoutSeconds: 60
          }
        ],
        description: "Current weather data"
      }
    },
    {
      facilitatorUrl: process.env.FACILITATOR_URL,
      rpcUrl: process.env.RPC_URL
    }
  )
);

app.get("/v1/weather", (req, res) => {
  res.json({ temperatureC: 21, condition: "clear" });
});

app.listen(3000, () => console.log("listening on :3000"));

Inspecting the 402 challenge with curl

Before writing a client, confirm the server emits a well-formed challenge. An unpaid request should return status 402 and a JSON body you can parse. The exact field names depend on the scheme version your SDK implements, so treat the output below as a template to compare against your facilitator's specification rather than a fixed contract.

If you receive a 200 instead of a 402, the middleware is not matching the route—check the method and path string, including trailing slashes. If you receive a 500, the middleware is failing before it can build the challenge, which usually means a missing environment variable or an unreachable facilitator.

curl -i https://api.example.com/v1/weather

# Expected shape (fields vary by scheme version):
# HTTP/1.1 402 Payment Required
# Content-Type: application/json
#
# {
#   "x402Version": 1,
#   "accepts": [
#     {
#       "scheme": "exact",
#       "network": "base-sepolia",
#       "maxAmountRequired": "10000",
#       "payTo": "0xYourAddress",
#       "asset": "0xAssetAddress",
#       "resource": "https://api.example.com/v1/weather"
#     }
#   ]
# }

Building a paying client and confirming access

A paying client must parse the 402 body, choose an acceptable option, construct the payment payload with its wallet, and retry the original request with the payment header. The client below uses placeholders for the wallet key and facilitator; the control flow—request, parse, pay, retry—is what you should reproduce in your own language.

The verification result you are looking for is simple: the retried request returns 200 with the resource body, and the facilitator reports a settled or verified payment for that payload. Log the payment identifier returned by the facilitator alongside your request ID so you can reconcile the two later.

import { createWalletClient, http } from "viem";
import { privateKeyToAccount } from "viem/accounts";
import { baseSepolia } from "viem/chains";

const account = privateKeyToAccount(process.env.PRIVATE_KEY);
const wallet = createWalletClient({ account, chain: baseSepolia, transport: http(process.env.RPC_URL) });

const url = "https://api.example.com/v1/weather";

const first = await fetch(url);
if (first.status !== 402) throw new Error(`expected 402, got ${first.status}`);

const challenge = await first.json();
const option = challenge.accepts[0];
console.log("paying", option.maxAmountRequired, "to", option.payTo, "on", option.network);

// Build the payment payload using your x402 client SDK, then retry:
// const payload = await buildPaymentPayload({ wallet, option });
// const paid = await fetch(url, { headers: { "X-PAYMENT": payload } });
// console.log(paid.status, await paid.text());

A reproducible latency and success-rate measurement

Protocol correctness and protocol performance are separate questions. To measure the latter, run a fixed number of paid requests against staging and record four timestamps per request: challenge received, payment submitted, resource returned, and settlement confirmed. Compute the median and 95th percentile for each interval rather than reporting a single average, because payment flows have long tails.

Record results in a table like the one below, filling in your own numbers. Do not copy values from documentation or other deployments—fees, finality, and facilitator behavior differ by network and load. Run at least three sessions at different times of day and report the spread.

• | Metric | Session 1 | Session 2 | Session 3 | Notes |
• | --- | --- | --- | --- | --- |
• | Requests attempted | | | | fixed N, e.g. 200 |
• | 402 challenges received | | | | should equal attempts |
• | Paid requests returning 200 | | | | success rate |
• | Median challenge-to-resource (ms) | | | | client-side clock |
• | p95 challenge-to-resource (ms) | | | | tail behavior |
• | Median submit-to-settlement (ms) | | | | facilitator-reported |
• | Failed or expired payments | | | | categorize causes |

Troubleshooting the failures you will actually see

Most x402 integration problems fall into four buckets: the challenge never appears, the client cannot construct a valid payload, the facilitator rejects the payment, or the resource is released but settlement later fails. Work through them in that order, because each stage depends on the previous one.

For chain-level symptoms—timeouts reading settlement state, stale nonces, or inconsistent confirmations—the problem may be your RPC endpoint rather than the protocol. The blockchain nonce explainer helps diagnose stuck or duplicated transactions, and if you need a dedicated connection for settlement monitoring, review dedicated node options.

• No 402 returned: route mismatch, middleware ordering, or a proxy stripping the status code.
• Malformed payload: scheme or version mismatch between server challenge and client SDK.
• Facilitator rejection: expired maxTimeoutSeconds, wrong payTo, or unsupported network.
• Settlement failure after release: you chose verify-then-release; add reconciliation or switch to settle-then-release.
• Intermittent timeouts: check RPC health and facilitator reachability before changing protocol code.

Tradeoffs: what x402 does not solve for you

x402 removes account provisioning from the payment path, but it does not remove operational responsibility. You still own key management, replay protection, idempotency for retried requests, and the policy decision of when to release a resource. You also inherit the finality and fee characteristics of whichever rail you accept, and those characteristics should drive your timeout and retry settings.

There is also a UX tradeoff. Human users may find wallet-based payment unfamiliar, so many teams run x402 alongside conventional billing rather than replacing it. And because the standard is network-agnostic, accepting multiple options increases flexibility but multiplies the verification paths you must test. Start with one scheme on one test network, measure it, then expand.

Finally, facilitator choice is a trust decision. A facilitator that verifies but does not settle, or settles slowly, changes your risk profile. Read its documentation, confirm which steps it performs, and monitor settlement independently rather than relying solely on its API responses.

Next steps: from staging to a monitored deployment

Once a single endpoint passes the verification procedure above, promote it behind a feature flag and add observability before increasing traffic. Emit structured logs for challenge issuance, payment verification, settlement confirmation, and resource release, all correlated by request ID. Alert on the ratio of challenges to successful payments, because a sudden drop usually indicates a client or facilitator regression rather than a demand change.

If your settlement monitoring depends on chain reads, choose an endpoint you can reason about. The RPC pricing page explains how plans map to request volume, and OnFinality's API service describes managed access across supported networks. For the concrete question of which endpoint or provider fits your settlement network, use RPC Assistant rather than guessing—it is built for exactly that short recommendation. Browse supported networks to confirm your target chain is covered before you commit to a scheme.

• Ship one paid route behind a flag; keep the unpaid path available for comparison.
• Add idempotency keys so client retries cannot double-charge.
• Reconcile facilitator payment IDs against your own request logs daily.
• Re-run the latency table after any facilitator, SDK, or RPC change.