Server Integration Guide

Pick the right route

Do not start by wrapping your whole API. Start with one endpoint whose value is obvious and whose response can be safely withheld until payment is verified. Weather examples are common in docs because the shape is easy, but production endpoints need stronger product thinking: stale data, partial failures, retries, refunds, and user support all affect whether the route is a good paid resource.

The resource description matters. Clients and agents may use it to decide whether the request is worth paying for. A vague description such as "premium data" gives automated buyers little to evaluate. A precise description such as "15-minute delayed options chain snapshot for AAPL, JSON, generated on request" is easier to price and audit.

• Start with deterministic GET endpoints before dynamic POST workloads.
• Make payment requirements stable for the same logical resource unless using a dynamic scheme or extension.
• Keep free discovery endpoints available so clients can inspect your service before paying.

Middleware shape

The current TypeScript packages split core primitives, network mechanisms, clients, and framework middleware. That modular v2 package map is important because old examples using x402-express or X-PAYMENT can still rank in search. For new server work, look for @x402/core plus a framework package such as @x402/express, @x402/hono, @x402/fastify, @x402/next, and the relevant scheme packages.

A typical route declaration names the HTTP method and path, the accepted payment options, the network, the receiving address, a price, a MIME type, and a human-readable description. You then register exact EVM, exact SVM, or other scheme handlers with the resource server and point it at a facilitator.

// Shape only: confirm exact imports against the SDK version you install.
const routes = {
  "GET /report": {
    accepts: [
      {
        scheme: "exact",
        network: "eip155:84532",
        payTo: process.env.PAY_TO_ADDRESS,
        price: "$0.01",
      }
    ],
    mimeType: "application/json",
    description: "Single paid JSON report generated on request",
  }
};

Production checklist

A production seller should test more than happy-path payment. Verify the unauthenticated 402 response, the signed retry, wrong-network failure, insufficient funds, duplicate retry, facilitator outage, idempotent client retry, and delayed settlement behavior if using a non-immediate scheme.

Do not bury payment risk in generic middleware logs. Persist enough request, payment, settlement, and response metadata to answer user support questions without storing secrets. For agent buyers, a clear PAYMENT-RESPONSE and a stable receipt model may be more valuable than a pretty human paywall.

• Use a production facilitator for mainnet, not the x402.org testnet facilitator.
• Confirm asset decimals, token address, EIP-712 name/version, and CAIP-2 network identifiers.
• Document refund policy because exact push payments are not automatically reversible.
• Rate-limit unpaid 402 probes and paid retries separately.