AgentSmith Facilitator

The AgentSmith Facilitator implements the open-source x402 v2 protocol for fee-sponsored payments on Stellar Testnet and Mainnet. 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, covered under Schemes below.

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 the selected Stellar network, waits for confirmation, and returns the settlement result to the resource server.

For a complete end-to-end example, see the weather-x402 reference — an x402-gated weather service settled through the Facilitator, including a browser wallet flow.

Facilitator environments

Choose the same network in the Seller, Buyer and token configuration. The Resource Server calls the Facilitator; Buyers call the Seller only.

On mainnet, every request carries Authorization: Bearer <API_KEY>. The key authenticates the Seller to the Facilitator; never expose it in browser code.

Schemes

The Facilitator accepts a fixed-price exact payment and an experimental metered upto payment. Pick the one that matches how the price is known.

Getting an API key

Register a Resource Server through POST /credentials/register with a name, domain and email. The domain must be unique; a second registration for the same domain is rejected. The response returns a resourceServerId and the API key. The key is shown only once, so store it in backend secret storage immediately.

Rotate on a schedule or when a key may be compromised, and revoke a key you no longer use; rotation and revocation authenticate with the current key. Keys are per environment — a testnet deployment does not require one, so these routes apply to mainnet. The full request and response shapes are in the Credentials endpoints below.

Use GET /supported to check the selected deployment's advertised capabilities. Each environment has a separate deployment; an endpoint error does not establish supported payment capabilities.

Supported capabilities

Endpoints

The resource server calls these endpoints; the buyer never calls the Facilitator directly. On mainnet every request carries Authorization: Bearer <API_KEY>. Bodies follow the x402 v2 specification.

Status and advertised capabilities.

Verify and settle a buyer's signed payment. Both take the same x402 v2 body.

Mainnet only. Register a Resource Server, then rotate or revoke its key.

AgentSmith payment SDK

Install agentsmith-x402-sdk for Seller payment middleware and Node Buyer paid fetch. Requires Node.js 24+ and ES modules ("type": "module"). Reuses official x402 packages for exact payments and includes local experimental upto adapters; no copied adapter or dependency patch is required.

npm install agentsmith-x402-sdk
# Sellers using Express (including NestJS with the Express adapter):
npm install express @x402/express@2.23.0

Seller: protect an API route

Set the recipient and SEP-41 token contract for your selected network in backend configuration. Prices are atomic integer strings: a seven-decimal token uses 10000000 units per token. The SDK does not infer arbitrary token precision or convert USD prices for explicit asset/amount quotes.

import express, { type Request, type Response } from 'express';
import { createPaymentMiddleware } from 'agentsmith-x402-sdk/seller/express';

const asset = process.env.TOKEN_CONTRACT;
const payTo = process.env.SELLER_ADDRESS;
if (!asset || !payTo) throw new Error('Set TOKEN_CONTRACT and SELLER_ADDRESS');

const app = express();
app.use(await createPaymentMiddleware({
  network: 'stellar:testnet',
  facilitator: { url: 'https://testnet.agentsmith.xyz/facilitator' },
  routes: {
    'GET /price': {
      accepts: {
        scheme: 'exact',
        payTo,
        price: { asset, amount: '40000' },
      },
    },
  },
}));
app.get('/price', (_req: Request, res: Response) => res.json({ result: 'data' }));
app.listen(3000);

The helper fetches Facilitator capabilities at initialization, registers the selected schemes and returns native payment middleware. Unpaid requests receive 402 before the handler runs. The framework verifies authorization, runs the handler and then settles; application handlers do not call /verify or /settle manually. NestJS applications using Express can mount this middleware in bootstrap; route patterns must include any global prefix.

Connect the Seller to mainnet

Replace the testnet network and Facilitator configuration with the following fields in createPaymentMiddleware. Configure a mainnet recipient and token contract. The SDK sends the API key as a Bearer token; keep it in backend secret storage.

network: 'stellar:pubnet',
facilitator: {
  url: 'https://mainnet.agentsmith.xyz/facilitator',
  apiKey: process.env.FACILITATOR_API_KEY,
},

Metered payments with upto

Choose scheme: 'upto' in the route accepts configuration and quote the maximum authorized amount. The built-in adapter reads the advertised Kernel and authorization signer from the selected Facilitator. In every successful metered handler, set the actual atomic usage before responding:

import { setSettlementOverrides } from 'agentsmith-x402-sdk/seller/express';
import type { Request, Response } from 'express';

// Configure the metered route with scheme: 'upto' and its maximum price.
app.get('/metered', (_req: Request, res: Response) => {
  setSettlementOverrides(res, { amount: '20000' });
  res.json({ result: 'data' });
});

Actual usage must be positive and no greater than the Buyer-authorized maximum. Missing, zero, malformed or over-cap amounts reject settlement. The SDK never substitutes the ceiling. upto remains experimental and requires a compatible deployed Kernel.

Business side effects cannot be rolled back by failed or uncertain settlement. Applications own idempotency, handler deadlines, CORS and recovery.

Buyer: Node paid fetch

The Buyer calls the Seller, receives a 402 challenge, signs locally and resends through the native x402 fetch flow. It does not need the Seller's Facilitator API key. Keep the signing seed in application-owned secret storage; never embed it in browser JavaScript.

import { createBuyerFetch } from 'agentsmith-x402-sdk/buyer';

const secret = process.env.STELLAR_SECRET;
if (!secret) throw new Error('Set STELLAR_SECRET');

const paidFetch = createBuyerFetch({
  secret,
  network: 'stellar:testnet',
  schemes: ['exact'],
});
const response = await paidFetch('http://localhost:3000/price');
if (!response.ok) throw new Error(`Paid request failed: ${response.status}`);
const data = await response.json();

Approve a payment before signing

Add the following hook to createBuyerFetch to apply your own approval policy. Omit the hook for automatic agent signing. The approval function is supplied by your application.

onBeforePaymentCreation: async ({ selectedRequirements }) => {
  const approved: boolean = await approvePayment(selectedRequirements); // your application policy/UI
  if (!approved) return { abort: true, reason: 'Payment declined' };
},

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.