x402 Seller and Agent Guide

import express from "express";
import { HTTPFacilitatorClient, x402ResourceServer } from "@x402/core/server";
import { paymentMiddleware } from "@x402/express";
import {
  bazaarResourceServerExtension,
  declareDiscoveryExtension,
} from "@x402/extensions/bazaar";
import { ExactStellarScheme } from "@x402/stellar/exact/server";

const NETWORK = process.env.NETWORK ?? "stellar:testnet"; // or "stellar:pubnet"
const PAY_TO = process.env.PAY_TO; // the account that receives the payments
const facilitator = new HTTPFacilitatorClient({
  url: process.env.FACILITATOR_URL,
});

const resourceServer = new x402ResourceServer(facilitator)
  .register(NETWORK, new ExactStellarScheme())
  .registerExtension(bazaarResourceServerExtension);

const app = express();
app.use(
  paymentMiddleware(
    {
      "GET /weather": {
        accepts: {
          scheme: "exact",
          price: "$0.01",
          network: NETWORK,
          payTo: PAY_TO,
        },
        description: "Current weather for a city",
        mimeType: "application/json",
        extensions: declareDiscoveryExtension({
          input: { city: "Lisbon" },
          inputSchema: {
            properties: { city: { type: "string", description: "City name" } },
            required: ["city"],
          },
          output: {
            example: { city: "Lisbon", temperature: 21, conditions: "sunny" },
          },
        }),
      },
    },
    resourceServer,
  ),
);
app.get("/weather", (req, res) => {
  res.json({
    city: String(req.query.city ?? "Lisbon"),
    temperature: 21,
    conditions: "sunny",
  });
});
app.listen(4021, () =>
  console.log("listening on http://localhost:4021/weather"),
);

import { HTTPFacilitatorClient } from "@x402/core/server";
import { withBazaar } from "@x402/extensions/bazaar";
import {
  decodePaymentResponseHeader,
  wrapFetchWithPaymentFromConfig,
} from "@x402/fetch";
import { createEd25519Signer } from "@x402/stellar";
import { ExactStellarScheme } from "@x402/stellar/exact/client";

const NETWORK = "stellar:testnet";
const MAX_AMOUNT = 500_000n; // 0.05 USDC in base units (7 decimals)

// 1. Discover: search a facilitator's Bazaar for a resource that is paid on this network.
const discovery = withBazaar(
  new HTTPFacilitatorClient({ url: process.env.DISCOVERY_URL }),
);
const { resources } = await discovery.extensions.bazaar.search({
  query: process.argv[2] ?? "current weather for a city",
  network: NETWORK,
  type: "http",
});
const match = resources.find((item) =>
  item.accepts.some(
    (option) =>
      option.network === NETWORK &&
      option.scheme === "exact" &&
      BigInt(option.amount) <= MAX_AMOUNT,
  ),
);
if (match === undefined) throw new Error("no affordable resource found");

// 2. Build the request from the listing's own example input.
const info = match.extensions?.bazaar?.info;
const url = new URL(match.resource);
for (const [key, value] of Object.entries(info?.input?.queryParams ?? {}))
  url.searchParams.set(key, value);
console.log(`paying for ${url} (${match.description ?? "no description"})`);

// 3. Pay with the stock client, capped per payment.
const fetchWithPayment = wrapFetchWithPaymentFromConfig(fetch, {
  schemes: [
    {
      network: NETWORK,
      client: new ExactStellarScheme(
        createEd25519Signer(process.env.BUYER_SECRET, NETWORK),
      ),
    },
  ],
  spendControls: { maxAmountPerPayment: "$0.05" },
});
const response = await fetchWithPayment(url);
console.log(response.status, await response.json());
const receipt = response.headers.get("PAYMENT-RESPONSE");
if (receipt !== null) console.log(decodePaymentResponseHeader(receipt));