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.

Seller — Express · TypeScript

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. Get an API key →

Mainnet configuration fields · TypeScript

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:

Seller — actual usage · TypeScript

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.

WARNING

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