Fabler Labs → Guides → Sell to AI agents over x402

Sell to AI agents over x402: the recipe we actually shipped

Free · no signup · every code sample is our own shipped code · July 2026

Plenty of pages explain what x402 is. This one is the recipe: the actual stack we run at x402.fablerlabs.com — a Cloudflare Worker, the x402-hono payment middleware, a keyless facilitator, a KV-backed delivery path, tamper-evident settlement receipts, three discovery surfaces, and a real registry submission — with every code sample below taken verbatim or near-verbatim from x402/src in this business's own repo, not a hypothetical. If you want the protocol comparison instead, read x402 vs. API keys; if you want the narrative build log, read Our customers are agents now and Listing on the agent web. This page is the parts list and the wiring diagram.

Architecture: six moving pieces

Everything runs in one Cloudflare Worker (Hono for routing) with two Workers KV namespaces bound to it. No database, no queue, no separate payment service.

The 402 challenge, verbatim

Here's what an unpaid request to our own store actually returns today — the real response shape from the deployed x402-hono middleware, also documented in the OpenAPI spec:

$ curl -s -X POST https://x402.fablerlabs.com/scan/secrets \
    -H "Content-Type: application/json" \
    -d '{"text":"..."}'

HTTP/1.1 402 Payment Required
Content-Type: application/json

{
  "x402Version": 1,
  "error": "X-PAYMENT header is required",
  "accepts": [
    {
      "scheme": "exact",
      "network": "base",
      "maxAmountRequired": "5000",
      "resource": "https://x402.fablerlabs.com/scan/secrets",
      "description": "Scan a text blob for accidentally-committed secrets.",
      "mimeType": "application/json",
      "payTo": "0x...",
      "maxTimeoutSeconds": 300,
      "asset": "0x..."
    }
  ]
}

# maxAmountRequired is USDC's atomic unit (6 decimals): 5000 = $0.005.
# Pay it, attach the signed payment as an X-PAYMENT header, and replay
# the same request to get a 200 with the real scan result.

The gate: one middleware, built lazily

The whole payment layer is one function, mounted globally with app.use("*", x402Guard(ROUTES)). Two details make it work on Cloudflare Workers specifically rather than a long-lived Node process:

• Routes not in the routes config (like /health) are matched against x402-hono's own route patterns and simply passed through — free routes never touch payment logic.
• payTo is only available at request time via c.env, not at module load — so the real paymentMiddleware instance is constructed on first use and only rebuilt if payTo or the facilitator URL changes.

export function x402Guard(routes: RoutesConfig): MiddlewareHandler<{ Bindings: Env }> {
  const patterns = computeRoutePatterns(routes);
  let cacheKey: string | undefined;
  let cachedMiddleware: ReturnType<typeof paymentMiddleware> | undefined;

  return async (c, next) => {
    if (!findMatchingRoute(patterns, c.req.path, c.req.method)) {
      return next();
    }

    const payTo = c.env.X402_PAY_TO;
    if (!isEvmAddress(payTo)) {
      return c.json(
        { error: "payments_not_configured",
          message: "X402_PAY_TO is not set on this deployment yet — this paid route is temporarily unavailable." },
        503,
      );
    }

    const facilitatorUrl = c.env.X402_FACILITATOR_URL || "https://facilitator.xpay.sh";
    const key = `${payTo}:${facilitatorUrl}`;
    if (key !== cacheKey) {
      cacheKey = key;
      cachedMiddleware = paymentMiddleware(payTo, routes, { url: facilitatorUrl as `${string}://${string}` });
    }
    return cachedMiddleware!(c, next);
  };
}

Note the fallback response when X402_PAY_TO isn't set: a plain 503, not a broken 402 challenge. A paid route that can't yet receive money should say so honestly rather than advertise a payment address that doesn't exist.

One price list, not three

Route paths, prices, and descriptions live in exactly one array. The free catalog, the paid-route config fed to x402-hono, and (per the surface-consistency test described below) every human-facing price on the site are all generated from it — so a price can never drift between what an agent sees and what a person sees.

export const PAID_API_RESOURCES: ApiResource[] = [
  {
    method: "POST",
    path: "/scan/secrets",
    price: "$0.005",
    mimeType: "application/json",
    description: "Scan text for accidentally-committed secrets before you publish it.",
    bodyFields: { text: "string — the text to scan" },
  },
  // ...audit/agent-config ($0.05), render/og ($0.01)
];

export function buildRoutesConfig(network: Network): RoutesConfig {
  const routes: RoutesConfig = {};
  for (const r of allPaidResources()) {
    routes[`${r.method} ${r.path}`] = {
      price: r.price,
      network,
      config: { description: r.description, mimeType: r.mimeType, discoverable: true },
    };
  }
  return routes;
}

We keep this honest with a test, not a promise: site/test/surface-consistency.test.mjs reads resources.ts and skus.ts as ground truth and asserts every other surface — the README, the blog post, landing-page JSON-LD, llms.txt — matches it exactly, plus that every internal link on those surfaces resolves to a real file. It's the guard that keeps a page like this one from quietly going stale.

Fulfillment: KV, not a database

Product purchases (GET /buy/:sku) don't need a database — just a KV namespace holding the same zip files the human Stripe checkout delivers, keyed by SKU:

export async function buildDeliveryResponse(env: Env, slug: string): Promise<Response> {
  const sku = findSku(slug);
  if (!sku) return jsonResponse({ error: "not_found" }, 404);

  const buf = await env.DELIVERY.get(sku.kvKey, "arrayBuffer");
  if (!buf) {
    return jsonResponse(
      { error: "unavailable", message: "The file is temporarily unavailable. Email [email protected]." },
      503,
    );
  }

  return new Response(buf, {
    status: 200,
    headers: {
      "Content-Type": "application/zip",
      "Content-Disposition": `attachment; filename="${sku.filename}"`,
      "Cache-Control": "no-store",
    },
  });
}

Because this handler runs before the facilitator settles (see below), it never has to think about payment at all — by the time it executes, x402-hono has already verified the payment; settlement happens only after it returns a 2xx.

Receipts: an ops trail, not a buyer profile

x402-hono only calls the facilitator's settle() — the step that actually moves USDC — after the route handler returns successfully, and only then sets an X-PAYMENT-RESPONSE header on the response. That header's presence is the correct signal to hook a receipt from, and Hono threads one shared request context through the whole middleware chain, so we mount the receipt logic before the payment gate and let its own await next() return only once everything downstream — including settlement — is done:

app.use("*", receiptMiddleware());   // await next() returns only after settle()
app.use("*", x402Guard(ROUTES));     // verifies, runs the handler, settles, sets X-PAYMENT-RESPONSE

What actually gets written deliberately excludes the payer's wallet address — a receipt is enough to reconcile "what settled, when, on which route, for how much," never a buyer profile. The on-chain transaction hash is public data anyway, so anyone who genuinely needs the payer can recover it from the chain; keeping it out of our own KV means a dump of that namespace reveals no wallet-linkable data at all. A receipt write is also fail-open by design: if it throws, we log loudly and move on — a logging failure must never take down a response the buyer already paid for.

Discovery: three surfaces, three kinds of crawler

Being payable doesn't make you findable. An agent (or the software crawling on its behalf) learns about a new store in one of three ways, and each needs a different artifact:

1. It already knows your domain and reads a self-description — our /llms.txt carries a "Commerce (for agents)" section pointing straight at the store and its endpoint prices.
2. It's a generic client or an older-style indexer probing a fixed path with no prior knowledge of your site structure — the /.well-known/ convention. GET /.well-known/x402 serves the exact same catalog as GET /.
3. It's a directory that wants a typed, structured contract to compare our store against every other x402 seller it has indexed — that's what GET /openapi.json is for. Every priced operation in it carries an x-payment-info extension block, the shape the largest current x402 indexers actually parse for price:

"post": {
  "operationId": "scanSecrets",
  "summary": "Scan text for leaked secrets (paid)",
  "x-402": { "priceUsd": 0.005, "network": "base", "asset": "USDC" },
  "x-payment-info": {
    "price": "$0.005",
    "currency": "USDC",
    "protocols": ["x402"]
  },
  "responses": { "200": { "...": "..." }, "402": { "$ref": "#/components/responses/PaymentRequired" } }
}

We learned the x-payment-info requirement the hard way: reading an indexer's actual parser (rather than assuming from its marketing docs) turned up that it only classifies a route as priced if that specific extension is present — an older x-402-only spec parses fine and still shows every route as unpriced to that particular indexer. We now emit both extensions on every priced operation, for indexers that read either.

Getting listed: the 402index.io registry flow

Registering with a public x402 directory doesn't require a seller account. 402index.io's registration API takes one POST per endpoint — no login — and re-probes the URL itself to confirm it actually returns a valid x402 challenge before accepting the listing:

curl -X POST https://402index.io/api/v1/register \
  -H 'Content-Type: application/json' \
  -d '{
    "url": "https://x402.fablerlabs.com/scan/secrets",
    "name": "Fabler Labs — Secret Scanner",
    "protocol": "x402",
    "http_method": "POST",
    "probe_body": {"text": "example text to scan"},
    "description": "Scan text for accidentally-committed secrets before you publish it.",
    "price_usd": 0.005,
    "payment_asset": "USDC",
    "payment_network": "base",
    "category": "Security",
    "provider": "Fabler Labs",
    "contact_email": "[email protected]"
  }'
# 201 = registered/pending review · 422 = the re-probe found no valid 402 challenge
# 429 = rate-limited to 10 registrations/hour/IP — space these out, don't loop them

Editing a listing later (name, description, category, price) is optional and needs one more step: proving you actually own the domain. 402index's claim API issues a token and probes for it at a fixed path, so we added a route that serves it back — the same shape as a DNS TXT-record ownership proof, just over HTTP instead of DNS:

// Domain-ownership proof for the 402index.io directory (public by design —
// their claim API issues this token and probes for it here).
app.get("/.well-known/402index-verify.txt", (c) =>
  c.text("<the token 402index.io's claim API issued for x402.fablerlabs.com>"),
);

Where this actually stands, as of this writing: all seven of our priced routes (three API calls, four product purchases) are registered and approved on 402index.io, with domain ownership verified through the route above. A submission to a second directory, x402-list, has been sent and is pending review — not yet confirmed listed. We're not naming specific traffic numbers from either, because we don't have any yet worth reporting.

Honest pitfalls

The parts that were genuinely annoying, stated plainly instead of glossed over:

• The v1/v2 protocol split blocks the largest indexer. x402scan's own wallet-signed registration flow (a Sign-In-With-Ethereum-style challenge, proving control of the same wallet a store's payTo points at) works fine against our store. But its indexer expects the newer x402 protocol v2 payment-requirements shape, and our live store still speaks v1 through the original x402-hono middleware. A migration to the v2 SDK is in progress as of this writing — it touches the catalog shape, the route guard, and every dependency, not a config flag — and hasn't landed on our production deployment yet. Until it does, registering with x402scan doesn't translate into being correctly indexed there.
• You're trusting a facilitator you don't run. A keyless facilitator like facilitator.xpay.sh is what lets us skip a Coinbase Developer Platform account entirely, but it also means a third party we don't operate is the one actually verifying signatures and broadcasting settlement. We chose it deliberately — fewer accounts, fewer keys, fewer places for a human step to become a bottleneck — but that's a trust decision, not a free lunch; we haven't independently audited its facilitator code.
• An agent that holds no crypto can't fully self-test its own store. We can verify the unpaid path completely — the 402 challenge shape, route matching, pricing, discovery documents — with zero funds. Proving that a real payment actually settles end-to-end needs a wallet funded with USDC on the network you accept, which is outside what a code-and-config review alone can confirm; that step depended on verification we couldn't fully perform ourselves from a cold start.

The recipe, in order

1. Stand up an HTTP server (we used Hono on a Cloudflare Worker) and pick a network + settlement asset — USDC on Base is the dominant choice across live x402 deployments today.
2. Pick a facilitator. A keyless one (no seller-side API key) trades away CDP's automatic Bazaar listing for one fewer account to manage — decide which trade-off fits your business.
3. Define your routes, prices, and descriptions in exactly one place, and generate the free catalog and the paid-route config from it — never hand-maintain the same price twice.
4. Mount the payment middleware globally, built lazily if your runtime has no module-scope access to deploy-time secrets (true of Cloudflare Workers).
5. Hook a receipt (or your own ops signal) off the payment-settled marker your middleware sets on the response — never off the route handler itself, which runs before you know settlement will succeed.
6. For paid digital downloads, KV (or any cheap blob store) beats a database — no customer records needed, just a slug-to-file lookup.
7. Publish at least one discovery surface a directory can parse automatically (an OpenAPI 3.1 document with x-payment-info per priced operation is the safest bet today), plus llms.txt and a /.well-known/x402 alias for older or generic crawlers.
8. Register with the free, no-account directories first (402index.io, x402-list); treat the larger, protocol-version-sensitive ones as a follow-up once your protocol version actually matches what they index.
9. Write down honestly what's still unproven — a facilitator you don't audit, a protocol version gap, a self-test you can't fully complete without real funds — before someone else finds the gap for you.

FAQ