AgentSmith Facilitator

The AgentSmith Facilitator implements the open-source x402 v2 protocol for fee-sponsored payments on Stellar Testnet. It verifies buyer-signed Soroban authorization entries, builds and submits the transaction, waits for confirmation, and returns the settlement result to the resource server. It never holds the buyer's payment funds.

The default exact payment path is built with the official @x402/core and @x402/stellar packages and follows the normative requirements of the x402 v2 protocol and the official Stellar exact scheme. The optional upto path is an experimental AgentSmith extension and is identified separately below.

Supported capabilities

Endpoints

Both POST endpoints accept an x402 v2 body containing x402Version, paymentPayload and paymentRequirements. The resource server calls these endpoints; the buyer does not call the Facilitator directly.

Exact and upto

exact is the default path. The buyer authorizes one SEP-41 transfer(from, to, amount), and the Facilitator cannot change its asset, recipient or amount without invalidating the authorization.

upto is an experimental AgentSmith scheme backed by a Soroban settlement Kernel. The buyer authorizes a maximum and the resource server settles an actual amount at or below that cap, including zero. It is advertised only when the Facilitator is configured with the current Kernel contract and is not yet an upstream x402 scheme.

Current service behavior

These are the defaults enforced by the AgentSmith-operated Facilitator. Sellers should build payment requirements around them, and buyers should use the requirements exactly as returned in the 402 response.

Payment flow

The buyer first requests the protected resource and receives a 402 Payment Required response with the payment terms. After the buyer signs and retries, the resource server asks the Facilitator to verify the authorization without moving funds. If verification succeeds, the server runs the protected resource and then asks the Facilitator to settle the payment. The Facilitator sponsors the XLM network fee, submits the transaction to Stellar Testnet, waits for confirmation, and returns the settlement result to the resource server.

Integrate the Facilitator

This guide is for a Seller connecting its Resource Server to an already deployed instance of the AgentSmith Facilitator from this repository. It follows the same integration pattern as the AgentSmith Weather service and end-to-end tests: keep the Facilitator behind the Resource Server, pass its URL through an environment variable, and let the x402 middleware call it. Buyers call only the Seller's paid endpoint; they never call the Facilitator directly. The complete Seller and Buyer reference implementation is available in weather-x402 on GitHub.

Use the official Stellar exact scheme for fixed-price payments. The deployed Facilitator can also advertise AgentSmith's experimental upto scheme for usage-based settlement through /supported. upto has not been adopted by the upstream x402 specification; see Exact and upto. The example below uses the standard exact path.

1. Install the server packages

Install the official server packages from the x402 GitHub repository.

pnpm add @x402/core @x402/express @x402/stellar

2. Configure the integration

The only Facilitator-specific environment variable the Resource Server needs is X402_FACILITATOR_URL. Use the public AgentSmith Facilitator base URL below. The x402 client appends /supported, /verify and /settle as needed.

X402_FACILITATOR_URL=https://agentsmith.xyz/facilitator

3. Connect the protected route

Create an x402 Resource Server with the configured Facilitator URL, register the Stellar scheme, and pass that Resource Server to the payment middleware. Keep the route definitions and payment terms in your existing Seller configuration. Initialize the Resource Server during startup so an unreachable or incompatible Facilitator fails before the app serves traffic.

import { paymentMiddleware } from '@x402/express';
import { HTTPFacilitatorClient, x402ResourceServer } from '@x402/core/server';
import { ExactStellarScheme } from '@x402/stellar/exact/server';

const facilitatorUrl = process.env.X402_FACILITATOR_URL;
if (!facilitatorUrl) throw new Error('X402_FACILITATOR_URL is required');

const facilitator = new HTTPFacilitatorClient({ url: facilitatorUrl });
const resourceServer = new x402ResourceServer(facilitator)
  .register('stellar:testnet', new ExactStellarScheme());

// Check /supported once during startup.
await resourceServer.initialize();

// sellerRoutes contains your payTo, price and resource URL.
app.use(paymentMiddleware(sellerRoutes, resourceServer));

Compare this with the runnable demo's minimal Seller example and complete payment configuration.

Add upto settlement (experimental)

Use upto only when the Facilitator advertises it through /supported. Unlike exact, the server adapter is not exported by an official x402 package. Add the AgentSmith UptoStellarServer implementation to your project:

import type {
  Network,
  PaymentRequirements,
  SchemeNetworkServer,
  SupportedKind,
} from '@x402/core/types';
import { ExactStellarScheme as ExactServerScheme } from '@x402/stellar/exact/server';

/** Resource Server adapter for AgentSmith's experimental Stellar upto scheme. */
export class UptoStellarServer implements SchemeNetworkServer {
  readonly scheme = 'upto';
  readonly defaultAssetTransferMethod = 'default';
  readonly paymentFlows = {
    default: { supported: ['authorization'] as const, default: 'authorization' as const },
  };
  private readonly delegate = new ExactServerScheme();

  parsePrice = this.delegate.parsePrice.bind(this.delegate);
  getAssetDecimals = this.delegate.getAssetDecimals.bind(this.delegate);
  enhancePaymentRequirements = async (
    requirements: PaymentRequirements,
    supported: SupportedKind,
    extensions: string[],
  ) => this.delegate.enhancePaymentRequirements(requirements, supported, extensions);
  getExtra = (_network: Network) => ({ areFeesSponsored: true });
}

Register that adapter on the same Resource Server before calling initialize() or mounting the middleware. Use the Kernel contract and Facilitator signing address published for that deployment. The adapter is an AgentSmith extension and is not part of the official x402 packages or specification.

import { setSettlementOverrides } from '@x402/express';
import { UptoStellarServer } from './upto.js';

// Run this before resourceServer.initialize().
resourceServer.register('stellar:testnet', new UptoStellarServer());

const uptoPaymentOption = {
  scheme: 'upto',
  network: 'stellar:testnet',
  price: { asset: usdc, amount: maximumAmountAtomic },
  payTo,
  extra: {
    settlementContract: uptoTerms.settlementContract,
    facilitator: uptoTerms.facilitator,
  },
};

// Add this option to sellerRoutes before mounting paymentMiddleware.
sellerRoutes['POST /v1/resource'].accepts.push(uptoPaymentOption);

// After the protected resource succeeds, charge its actual cost.
// selectedPaymentScheme reads the option chosen in the signed payment payload.
if (selectedPaymentScheme(req) === 'upto') {
  const actualAmountAtomic = calculateActualAmount(result);
  setSettlementOverrides(res, { amount: actualAmountAtomic });
}

Mount the middleware before the protected route. It returns the initial 402, forwards the paid retry to the Facilitator for verification and settlement, and attaches the x402 payment response after a successful settlement.

Complete a payment as a Buyer

A Buyer interacts only with the Seller's protected endpoint. It makes the initial request, reads the payment requirements from the 402 response, signs the selected requirement locally and retries the same request with the signed x402 payload. The Seller's Resource Server handles verification and settlement through the Facilitator.

1. Connect the wallet

Connect Freighter, confirm that it is on Stellar Testnet, construct the official Stellar exact client, sign the Soroban authorization entry locally, and retry the same request. The private key never leaves Freighter.

Create the exact client

import {
  requestAccess,
  getNetwork,
  signAuthEntry,
  signTransaction,
} from '@stellar/freighter-api';
import { ExactStellarScheme } from '@x402/stellar/exact/client';

const access = await requestAccess();
if (access.error || !access.address) {
  throw new Error('Freighter access was not granted');
}

const network = await getNetwork();
if (network.error || !/TESTNET/i.test(network.network || '')) {
  throw new Error('Switch Freighter to Stellar Testnet');
}

const signer = {
  address: access.address,
  signAuthEntry,
  signTransaction,
};
const exact = new ExactStellarScheme(signer, { url: rpcUrl });

2. Handle 402, sign and retry

The initial request returns payment requirements. The official exact client builds and simulates the SEP-41 transfer, invokes Freighter's signAuthEntry, and produces the payload sent in PAYMENT-SIGNATURE.

let response = await fetch(url, request);
if (response.status !== 402) return response;

const paymentRequired = fromBase64(
  response.headers.get('payment-required'),
);
const requirements = paymentRequired.accepts.find(
  option => option.scheme === 'exact',
);

const { x402Version, payload } =
  await exact.createPaymentPayload(2, requirements);

response = await fetch(url, {
  ...request,
  headers: {
    ...request.headers,
    'payment-signature': toBase64({
      x402Version,
      resource: paymentRequired.resource,
      accepted: requirements,
      payload,
    }),
  },
});

Bazaar Coming soon

Bazaar discovery and registration are still under active development and are not part of the current supported Facilitator integration. Do not build a production dependency on Bazaar endpoints yet. This documentation will publish the supported discovery workflow when it is ready.