Seller course

Seller Track: Monetize an API with x402

The seller job is not only adding middleware. It is defining a paid resource that agents can understand, test, and trust.

Start with the route contract

Pick one endpoint before you touch middleware. A good first x402 resource has a stable response, an obvious value proposition, and a price that can be tested repeatedly without drama. Do not start with an endpoint that has side effects such as booking, deleting, transferring, or sending messages. Start with read access.

Route contract worksheet
GET /weather

Audience: agents and apps that need a fresh weather report.
Paid value: one JSON report per request.
Price: $0.001 while testing.
Network: eip155:84532 during Base Sepolia testing.
Receiver: EVM receive address owned by the seller.

The route description matters because buyers and agents use it to decide what they are paying for. Write it as a literal description of the returned resource, not marketing copy. "Weather data" is better than "Premium intelligence layer" because an agent can map the words to the response.

Declare payment requirements

The official seller quickstart shows an accepts array. That array is the seller's negotiation surface. It can offer one or more payment options across schemes and networks. For a first build, keep the surface narrow: one route, one scheme, one network, one small test price, and one receiving address.

Payment requirement shape
{
  "GET /weather": {
    "accepts": [{
      "scheme": "exact",
      "price": "$0.001",
      "network": "eip155:84532",
      "payTo": "0xYourReceiveAddress"
    }],
    "description": "Weather data",
    "mimeType": "application/json"
  }
}
"This quickstart begins with testnet configuration for safe testing."
Primary source: x402 docs: Quickstart for Sellers

The payTo field is a receiving address, not a server private key. The server should not need the buyer's private key or the seller's spending key to describe what payment it accepts. Keep private signing material out of the seller route.

Test every response path

A seller route has more states than "works" and "does not work." You need proof for unpaid access, valid payment, invalid payment, settlement failure, and handler failure. The official Next.js seller docs call out a useful distinction: an API wrapper can settle only after a successful handler response. That pattern prevents charging for a route that then fails.

For each path, capture the HTTP status, the response body shape, and whether the paid resource was actually returned. A failed verification should return payment-required behavior, not a partial paid payload. A handler exception should not be hidden as a payment problem.

Production review checklist

Before production
[ ] Route returns the same paid payload shape on every successful paid request.
[ ] Unpaid requests return 402 payment requirements.
[ ] Failed verification never serves the paid resource.
[ ] Logs include route, network, scheme, payment status, and correlation ID.
[ ] Prices and receive addresses come from environment or deployment config.
[ ] A retry/idempotency plan exists before agents run unattended.

Add a retry and idempotency plan before agents use the endpoint unattended. The x402 payment-identifier extension exists for safely retrying logical requests without duplicate payment processing when the server declares support. If you do not implement idempotency, document that clients should treat network failures conservatively.

When this track is complete, move to the buyer agent track and pay your own endpoint from a controlled client.

Sources used

  1. x402 docs: Quickstart for Sellers

    Official seller setup, package installation, testnet defaults, and payment middleware examples.

  2. x402 docs: Facilitator

    Defines facilitator responsibilities for payment verification and settlement.

  3. x402 docs: Networks and Token Support

    Documents CAIP-2 network identifiers and supported network namespaces.

  4. x402 docs: Payment-Identifier extension

    Documents idempotency support for retries without duplicate payment processing.

  5. x402 Foundation GitHub repository

    Open-source SDKs, examples, and the typical x402 request/payment/settlement flow.