x402 Seller Tools: Architect the Request Path Behind Paid Agent Services

The minimum x402 seller tools are a versioned offer resolver, payment middleware, a resource server, a verification and settlement path, a fulfillment admission layer, durable transaction records, and reconciliation. Sellers also need observability, idempotency, secret management, and a remedy path for requests that are paid but not delivered.

Those components should not all block the AI agent's request. The synchronous path should do only what is necessary to quote the resource, validate payment, apply acceptance policy, reserve one fulfillment, and return a result or durable job receipt. Catalog editing, analytics, balance reporting, reconciliation, and most support operations belong outside the latency-sensitive path.

That separation is the practical difference between adding x402 middleware and building seller-side payment infrastructure.

Divide The Seller Stack Into Four Planes

A seller can model the system as four connected planes rather than one payment service.

                         policy + observability
                                  |
Agent -> request plane -> delivery plane -> result or job receipt
              |                |
              v                v
      settlement plane <-> commercial control plane

                         policy + observability
                                  |
Agent -> request plane -> delivery plane -> result or job receipt
              |                |
              v                v
      settlement plane <-> commercial control plane

                         policy + observability
                                  |
Agent -> request plane -> delivery plane -> result or job receipt
              |                |
              v                v
      settlement plane <-> commercial control plane

The request plane receives the API request or MCP call, resolves an offer, emits 402 Payment Required, validates a returned payment payload, and decides whether the request may proceed.

The delivery plane reserves work, executes the API, model, data query, or tool, persists the outcome, and makes retries idempotent.

The settlement plane connects to a facilitator or direct chain integration, records verification and settlement evidence, and reconciles uncertain or delayed states.

The commercial control plane owns products, price versions, merchant configuration, credentials, order references, support state, reporting, and remedies.

Policy and observability cross all four. Policy rejects unacceptable payment terms, resources, or requests. Observability lets an operator trace one agent request across challenge, verification, settlement, execution, and delivery.

This topology prevents a common architecture error: turning the facilitator into the center of the entire seller system. A facilitator has a specific payment role. It does not need to know how a report is generated, whether a model output passed validation, or how a merchant grants a service credit.

Keep The Synchronous Path Narrow

The seller's critical path can be expressed as a sequence of contracts:

Every blocking dependency consumes the seller's latency and availability budget. A remote pricing database, policy API, facilitator, order service, and fulfillment backend can each fail independently. The architecture should cache stable offer data, apply short timeouts, use explicit fallbacks, and fail closed when payment or resource binding cannot be established.

Do not call analytics, send webhooks, update dashboards, or run accounting exports inline. Persist an event to a durable queue or log, return the customer response, and process those concerns asynchronously.

Make The Offer Resolver A Runtime Component

The first seller tool is not the payment middleware. It is the component that decides what is for sale.

An offer should bind:

• resource identifier and version;

• HTTP method and route or MCP tool name;

• fixed amount or maximum authorization;

• payment scheme;

• network in an unambiguous identifier format;

• asset and recipient;

• expiration;

• description and response type;

• fulfillment terms;

• policy version.

The official x402 seller configuration includes fields for scheme, price, network, recipient, description, MIME type, and optional extensions. That is enough to express a route-level payment requirement, but the seller still needs to decide where those values come from.

Hard-coded route pricing is reasonable for an initial fixed-price endpoint. It is fast, reviewable, and easy to deploy. Dynamic pricing requires a versioned offer resolver. Never calculate one price for the challenge and then reconstruct a potentially different price when the paid request returns.

Persist or cryptographically bind the accepted terms. A stable offer_id or terms hash should connect:

resource + version + scheme + amount + network + asset
+ recipient + expiry + policy version

resource + version + scheme + amount + network + asset
+ recipient + expiry + policy version

resource + version + scheme + amount + network + asset
+ recipient + expiry + policy version

Agents need deterministic terms. If price, recipient, or asset changes between the first request and retry, return a new challenge rather than silently accepting a different commercial contract.

Extensions can add discovery metadata, but discovery and charging solve different problems. A discoverable service still needs a trustworthy offer and a deliverable resource. Keep descriptions factual and avoid putting sensitive request data into public or payment-visible metadata.

Wire The Resource Server And Payment Middleware

Official x402 SDKs provide seller integrations for common TypeScript, Go, and Python frameworks. The framework adapter is the edge enforcement point; the resource server and registered payment schemes provide the protocol behavior behind it.

A simplified TypeScript shape looks like this:

import {
  paymentMiddleware,
  x402ResourceServer,
} from "@x402/express";
import { HTTPFacilitatorClient } from "@x402/core/server";
import { ExactEvmScheme } from "@x402/evm/exact/server";

const facilitator = new HTTPFacilitatorClient({
  url: process.env.X402_FACILITATOR_URL!,
});

const resourceServer = new x402ResourceServer(facilitator);
resourceServer.register(
  "eip155:84532",
  new ExactEvmScheme(),
);

app.use(
  paymentMiddleware(
    {
      "POST /v1/risk-score": {
        accepts: [
          {
            scheme: "exact",
            price: "$0.02",
            network: "eip155:84532",
            payTo: process.env.MERCHANT_ADDRESS!,
          },
        ],
        description: "One risk-score computation",
        mimeType: "application/json",
      },
    },
    resourceServer,
  ),
);

app.post("/v1/risk-score", async (req, res) => {
  const result = await runIdempotentRiskScore(req.body, req);
  res.json(result);
});

import {
  paymentMiddleware,
  x402ResourceServer,
} from "@x402/express";
import { HTTPFacilitatorClient } from "@x402/core/server";
import { ExactEvmScheme } from "@x402/evm/exact/server";

const facilitator = new HTTPFacilitatorClient({
  url: process.env.X402_FACILITATOR_URL!,
});

const resourceServer = new x402ResourceServer(facilitator);
resourceServer.register(
  "eip155:84532",
  new ExactEvmScheme(),
);

app.use(
  paymentMiddleware(
    {
      "POST /v1/risk-score": {
        accepts: [
          {
            scheme: "exact",
            price: "$0.02",
            network: "eip155:84532",
            payTo: process.env.MERCHANT_ADDRESS!,
          },
        ],
        description: "One risk-score computation",
        mimeType: "application/json",
      },
    },
    resourceServer,
  ),
);

app.post("/v1/risk-score", async (req, res) => {
  const result = await runIdempotentRiskScore(req.body, req);
  res.json(result);
});

import {
  paymentMiddleware,
  x402ResourceServer,
} from "@x402/express";
import { HTTPFacilitatorClient } from "@x402/core/server";
import { ExactEvmScheme } from "@x402/evm/exact/server";

const facilitator = new HTTPFacilitatorClient({
  url: process.env.X402_FACILITATOR_URL!,
});

const resourceServer = new x402ResourceServer(facilitator);
resourceServer.register(
  "eip155:84532",
  new ExactEvmScheme(),
);

app.use(
  paymentMiddleware(
    {
      "POST /v1/risk-score": {
        accepts: [
          {
            scheme: "exact",
            price: "$0.02",
            network: "eip155:84532",
            payTo: process.env.MERCHANT_ADDRESS!,
          },
        ],
        description: "One risk-score computation",
        mimeType: "application/json",
      },
    },
    resourceServer,
  ),
);

app.post("/v1/risk-score", async (req, res) => {
  const result = await runIdempotentRiskScore(req.body, req);
  res.json(result);
});

Treat this as an architectural skeleton and verify the exact signatures against the installed SDK version. Package APIs and supported schemes evolve.

The middleware should sit after basic request normalization and abuse controls but before expensive execution. Input validation may need two phases:

1. A cheap pre-payment check confirms that the route exists and the request can be priced.

2. A full post-payment check protects the fulfillment service from malformed or unsupported work.

Do not charge for a request the server could have rejected cheaply before presenting terms. Conversely, do not perform expensive model inference merely to discover what price to quote.

The resource server also needs an explicit failure policy. If offer resolution fails, no challenge should be issued. If verification is unavailable, do not guess. If the paid request cannot be bound to the original terms, reject it with fresh requirements or a machine-readable error.

Isolate Facilitator Availability From Business Logic

The x402 facilitator is optional but recommended. It verifies that a payment payload satisfies declared requirements and handles settlement for supported schemes and networks. A seller can instead implement verification and settlement locally, but then owns chain connectivity, scheme correctness, transaction submission, confirmation handling, and relevant duplicate protection.

The integration boundary should be narrow:

verify(payment_payload, payment_requirements)
  -> valid | invalid | unavailable

settle(payment_payload, payment_requirements)
  -> settled | pending | failed | unknown

verify(payment_payload, payment_requirements)
  -> valid | invalid | unavailable

settle(payment_payload, payment_requirements)
  -> settled | pending | failed | unknown

verify(payment_payload, payment_requirements)
  -> valid | invalid | unavailable

settle(payment_payload, payment_requirements)
  -> settled | pending | failed | unknown

Do not let a provider-specific response leak through the entire application. Normalize it into seller-owned states while retaining the native response for investigation.

Set separate timeouts for verification and settlement. A timeout is not the same as a rejection. When the result is unknown, persist the payment reference and query authoritative status before retrying settlement or admitting another fulfillment.

Duplicate handling is not theoretical. Official x402 documentation describes a Solana race in which repeated settlement submissions may receive successful RPC responses even though the network deduplicates the transaction. Standard facilitator helpers include protections for supported paths; direct-settlement sellers need equivalent safeguards where applicable.

The broader rule is network-independent: one payment authorization must not unlock multiple paid resources unless the commercial terms explicitly permit it. Use uniqueness constraints on payment evidence, resource binding, and fulfillment reservation.

Choose a facilitator by supported schemes, networks, assets, authentication, latency, availability, status visibility, data handling, rate limits, incident process, and migration path. A short quickstart is useful, but production fit depends on failure behavior.

Admit Fulfillment Only Once

Payment validation answers whether the evidence meets the offer. The seller still needs to decide what work that payment unlocks.

Introduce a fulfillment admission record:

{
  "fulfillmentId": "ful_01K...",
  "resource": "risk-score:v3",
  "argumentsHash": "sha256:...",
  "offerId": "off_01K...",
  "paymentReference": "pay_...",
  "state": "reserved"
}

{
  "fulfillmentId": "ful_01K...",
  "resource": "risk-score:v3",
  "argumentsHash": "sha256:...",
  "offerId": "off_01K...",
  "paymentReference": "pay_...",
  "state": "reserved"
}

{
  "fulfillmentId": "ful_01K...",
  "resource": "risk-score:v3",
  "argumentsHash": "sha256:...",
  "offerId": "off_01K...",
  "paymentReference": "pay_...",
  "state": "reserved"
}

Create it under a uniqueness constraint before starting expensive or side-effecting work. The key can combine seller request ID, payment reference, resource version, and normalized input hash. A repeated paid request should return the existing result or job receipt.

For synchronous endpoints, persist the result before returning it. If the network connection drops after execution, the agent can retry and receive the same response without paying again or repeating work.

For asynchronous services, return a receipt immediately after admission:

{
  "fulfillmentId": "ful_01K...",
  "state": "queued",
  "statusResource": "report-status",
  "expiresAt": "2026-07-28T12:00:00Z"
}

{
  "fulfillmentId": "ful_01K...",
  "state": "queued",
  "statusResource": "report-status",
  "expiresAt": "2026-07-28T12:00:00Z"
}

{
  "fulfillmentId": "ful_01K...",
  "state": "queued",
  "statusResource": "report-status",
  "expiresAt": "2026-07-28T12:00:00Z"
}

The seller must define whether payment buys admission, consumed compute, or a completed result. That distinction drives remedies. An expensive search may charge for attempted work; a downloadable product may promise successful delivery. The protocol does not choose the product contract.

Keep the delivery plane separate from settlement state. Useful combined states include:

payment_verified + fulfillment_reserved
settlement_pending + execution_running
settled + delivery_succeeded
settled + delivery_failed
settlement_unknown + fulfillment_held

payment_verified + fulfillment_reserved
settlement_pending + execution_running
settled + delivery_succeeded
settled + delivery_failed
settlement_unknown + fulfillment_held

payment_verified + fulfillment_reserved
settlement_pending + execution_running
settled + delivery_succeeded
settled + delivery_failed
settlement_unknown + fulfillment_held

The seller should never collapse those into one success flag.

Build Durable State Around A Stateless Exchange

x402 can make the buyer-server payment interaction stateless at the HTTP layer. The seller business still needs durable records.

The goal is not to build a large portal before the first paid call. It is to retain enough evidence to answer five questions:

1. What resource and terms did the seller offer?

2. What payment evidence did the buyer present?

3. What verification and settlement outcomes were observed?

4. What fulfillment was admitted and delivered?

5. What remedy remains open?

A compact seller schema can start with:

offers
payment_attempts
fulfillments
settlement_observations
remedies

offers
payment_attempts
fulfillments
settlement_observations
remedies

offers
payment_attempts
fulfillments
settlement_observations
remedies

Store native provider references alongside seller-owned IDs. Use append-only observations for payment and settlement events rather than overwriting history. Record timestamps and the source of each state transition.

The commercial control plane can later add merchant users, credentials, catalog administration, balance views, webhooks, exports, and support workflows. Those are important, but they should read from or write through stable domain contracts rather than reaching directly into middleware internals.

This is where seller tools differ from a payer wallet. The buyer needs to inspect terms, authorize, sign, and track a payment. The seller needs to price a resource, validate evidence, admit delivery, reconcile value, and resolve failures. Installing a buyer SDK on an agent does not create the seller control plane.

Reconcile From Authoritative State

Webhooks and request responses provide timely signals. Neither should be the only source of truth.

Run a reconciliation worker that scans:

• payment attempts stuck in submitted or unknown states;

• settlement operations past their expected window;

• verified payments without fulfillment reservations;

• settled payments without completed delivery;

• completed deliveries without closed commercial records;

• duplicate payment references or fulfillment IDs;

• remedies that exceed their service target.

The worker should query the authoritative payment or settlement source, apply idempotent transitions, and emit alerts for states it cannot close.

Build one correlation envelope and pass it through every component:

trace_id
seller_request_id
offer_id
payment_reference
fulfillment_id
settlement_reference

trace_id
seller_request_id
offer_id
payment_reference
fulfillment_id
settlement_reference

trace_id
seller_request_id
offer_id
payment_reference
fulfillment_id
settlement_reference

Metrics should measure more than payment volume. Track challenge-to-paid conversion, verification latency, settlement latency, rejected terms, duplicate attempts, fulfillment admission latency, delivery failure after payment, unknown-state age, and remedy backlog.

Logs must avoid private keys, authorization payloads that should remain secret, full payment headers, and unnecessary agent inputs. Observability should make the system explainable without creating a second security problem.

Choose The Payment Scheme From Workload Shape

The official seller path currently distinguishes several scheme types. The seller tools required around them are different.

Start with exact when the resource is bounded. Input caps, execution timeouts, caching, and product tiers can keep cost predictable.

Use upto only when the meter is reproducible and the buyer can understand the maximum before authorization. Record model tokens, bytes, compute time, or another measurable unit under the same fulfillment ID. Internal retries caused by seller failures should not silently increase the buyer's bill.

Batch settlement can improve economics for repeated small requests, but it changes the seller's state model. Per-request authorization, accumulated value, settlement timing, channel funding, and final redemption all need monitoring. Do not choose it only because "micropayments" appears in the product description.

Scheme support varies by SDK, language, network, facilitator, and release. Verify the current matrix before committing a production architecture.

Place GOAT Components By Responsibility

GOAT Network is relevant when a seller wants x402 payment operations alongside agent runtime and programmable execution, but its components should still be mapped to explicit responsibilities.

GOAT's documented x402 API covers order creation, order status, proof retrieval, cancellation, and callback-signature operations. Those surfaces fit the settlement and commercial control planes. AgentKit's merchant-side x402 plugin exposes a broader set of actions across authentication, orders, balances, webhooks, API keys, and related portal functions. Those belong mainly in the control plane, not inline in every resource request.

AgentKit also documents runtime configuration for idempotency and metrics. These controls cross the request and delivery planes. The payer-side x402 plugin is separate and serves agents making payments; it should not be confused with seller tooling.

GOAT also distinguishes direct paid-service flows from more specialized payment-triggered execution paths. Restricted callback-oriented modes introduce additional authorization, contract, eligibility, and compliance requirements. Sellers should confirm current availability and configuration rather than assuming every integration mode is open or equivalent.

This makes GOAT a relevant full-stack context when sellers need more than generic route middleware. It does not make GOAT the exclusive x402 implementation, eliminate the need for seller-owned delivery logic, or mean every x402 payment settles directly on Bitcoin L1.

Use the same component test applied to any provider: identify which plane it owns, which state is authoritative, what blocks the customer request, how data can be exported, and what happens when the component is unavailable.

Build In Three Deliberate Stages

Avoid launching every seller tool at once.

Stage One: Prove One Paid Resource

Protect one bounded endpoint with fixed exact pricing on a test network. Use a supported facilitator, one network, one asset, and one recipient. Add an offer ID, seller request ID, payment reference, and idempotent fulfillment record.

The exit condition is not one successful payment. It is a full retry test: payment succeeds, the response is lost, and the agent recovers the same result without a second charge or duplicate execution.

Stage Two: Make Failure Operable

Add durable settlement observations, reconciliation, machine-readable errors, alerting, and one remedy path. Test facilitator timeout, invalid evidence, duplicate submission, handler failure after payment, and unknown settlement state.

The exit condition is that an operator can explain and resolve every injected failure from stored records.

Stage Three: Add Commercial Scale

Introduce catalog administration, environment-specific credentials, webhooks, support views, balance reporting, exports, additional products, and only then more schemes or networks.

Add usage pricing or batch settlement only when request volume and cost variability justify their extra state. Scale the architecture from observed pressure, not from a desire to implement every protocol feature.

FAQ

What are the minimum x402 seller tools?

At minimum, a seller needs an offer resolver, x402-compatible resource server or middleware, verification and settlement integration, acceptance policy, idempotent fulfillment admission, durable payment and delivery records, reconciliation, and observability.

Is an x402 facilitator required?

No. A seller can verify and settle payments directly. A facilitator is optional but recommended because it reduces scheme-specific verification, chain connectivity, and settlement work. Direct operation transfers those responsibilities to the seller.

Does x402 middleware create orders and refunds?

Not necessarily. Middleware enforces payment requirements at the request boundary. Durable orders, fulfillment records, credits, refunds, accounting, and support are separate seller responsibilities unless a broader merchant platform provides them.

Which x402 payment scheme should a seller start with?

For a bounded resource with a known price, start with exact. Consider upto for reproducibly metered usage and batch settlement for sustained high-frequency payment traffic after the seller can operate the additional state.

How should sellers handle an agent retry after payment?

Bind payment evidence, offer terms, resource version, normalized inputs, and a seller request ID to one fulfillment record. A valid retry should recover that record or its stored result, not create another charge or repeat the work.

How does GOAT Network relate to x402 seller tools?

GOAT documents x402 APIs, merchant-side AgentKit actions, order and proof operations, webhooks, API credentials, idempotency, metrics, and programmable execution paths. These can cover parts of the seller control, settlement, and runtime planes, while the seller still owns product and delivery semantics.

Design The Critical Path Before Choosing A Platform

Seller-side x402 infrastructure is not one SDK and not one portal. It is a set of cooperating components that turn payment evidence into one authorized, delivered, and reconciled service outcome.

Keep offer resolution, verification, acceptance policy, and fulfillment admission on a narrow synchronous path. Move catalog management, analytics, reconciliation, reporting, and most remedies to durable asynchronous systems. Preserve separate payment, settlement, execution, and delivery states.

Once those boundaries are clear, sellers can evaluate reference middleware, hosted facilitators, GOAT Network tooling, or a self-managed combination by responsibility rather than feature count. The right x402 seller tools are the ones that keep the paid request fast while making every failure explainable and recoverable.