@rail402.dev/seller-helpers

Declare the discovery metadata for a paid Stellar x402 endpoint, including the per-parameter descriptions an agent reads to call it, and preflight your setup before your first buyer.

What you need

Node.js 20+, testnet only. A receiving Stellar account (payTo) and the SEP-41 token contract (SAC) you price in. For payments to succeed, payTo needs a trustline to that asset; preflight checks this for you.

Install

npm install @rail402.dev/seller-helpers

Describe an HTTP endpoint

describeEndpoint builds the discovery extension you attach to your x402 paywall route:

import { describeEndpoint } from "@rail402.dev/seller-helpers";

const extensions = describeEndpoint({
  params: {
    url: {
      description: "The page to summarize, as an absolute https URL.",
      example: "https://example.com",
    },
  },
  outputExample: { summary: "…", bullets: ["…", "…"] },
});

// Attach `extensions` to your paywall route (here with @x402/hono's paymentMiddleware):
//   "GET /summarize": {
//     accepts: { scheme: "exact", network: "stellar:testnet", price: { amount: "100000", asset: "C..." }, payTo: "G..." },
//     description: "Summarize a web page into bullet points.",
//     extensions,
//   }

The facilitator catalogs the endpoint, with these parameter descriptions, on the first settled payment. There is no separate registration step.

Describe a paid MCP tool

import { describeTool } from "@rail402.dev/seller-helpers";

const extensions = describeTool({
  toolName: "summarize",
  description: "Summarize the text at a URL.",
  params: { url: { description: "The page to summarize." } },
});

Preflight

Check the mistakes that otherwise only surface when a payment is attempted (a missing trustline, a payTo that cannot receive the asset). Findings are coded, each with a non-null reason.

import { preflight } from "@rail402.dev/seller-helpers";

const { ok, findings } = await preflight({
  facilitatorUrl: "https://facilitator.rail402.dev",
  network: "stellar:testnet",
  payTo: "G...", // your receiving account
  asset: "C...", // the SEP-41 token contract (SAC) you price in
});

Exports: describeEndpoint, describeTool, mcpToolResource, preflight, preflightAndReport.

Part of Rail402. Apache-2.0.