@rail402.dev/sdk

The SDK for building x402 payments and discovery on Stellar. One install gives you both sides of the flow: a buyer/agent that can find and pay for Stellar services, and a seller that can make an endpoint paid and discoverable.

x402 turns an HTTP 402 response into a machine-payable flow: a client requests a resource, the server answers 402 with payment terms, the client signs a payment and retries, and a facilitator verifies and settles it on-chain before the resource is returned. On Stellar the buyer signs a Soroban authorization entry and the facilitator submits it and sponsors the network fee, so a payment costs a fraction of a cent and the buyer needs no XLM.

This package is a thin umbrella over three packages, re-exported verbatim (no extra behaviour, no private protocol):

| Re-exports | Role | |---|---| | @rail402.dev/agent-helpers | buyer: search the Bazaar, pay under a spend cap | | @rail402.dev/seller-helpers | seller: declare discovery metadata, preflight | | @rail402.dev/errors | the shared machine-readable error registry |

When to use it

• You are an agent or app that pays for Stellar x402 services and want the discover then pay loop in a few lines, with a mandatory spend cap.
• You are a seller who wants your paid endpoint to show up in the Bazaar so agents can find it with no prior integration.
• You want one dependency to install and one place to import from. If you only need one side, install the individual package instead, or import the narrower entry point (see below).

What you need

• Node.js 20+.
• Testnet only. Every default in this SDK targets stellar:testnet.
• To pay: a Stellar account secret seed (S...), funded, holding the payment asset with a trustline. On testnet, fund XLM from friendbot and get USDC from the Circle faucet. Keep the secret in an environment variable.
• To only search: nothing but a Bazaar URL. Omit the secret.
• A facilitator URL. Defaults to the hosted testnet facilitator at https://facilitator.rail402.dev; point it at your own by changing bazaarUrl.

Install

npm install @rail402.dev/sdk

Buyer: discover and pay

import { searchBazaar, payAndFetch, discoverAndPay } from "@rail402.dev/sdk";

const config = {
  bazaarUrl: "https://facilitator.rail402.dev", // the Bazaar is served at the facilitator's base URL
  stellarSecret: process.env.RAIL402_SECRET,    // omit for search-only
  network: "stellar:testnet",
};

// Search the Bazaar in natural language.
const found = await searchBazaar(config, "fx quote for a currency pair");
if (found.ok) console.log(found.data); // resources with price, asset and input schema

// Pay a known resource URL, under a required cap (atomic units, as a string).
const paid = await payAndFetch(config, "https://api.example.com/quote", {
  maxAmount: "100000", // 0.01 USDC at 7 decimals
});
if (paid.ok) console.log(paid.data.body); // the resource response, after settlement

// Or do both: discover the cheapest match and pay it, still capped.
const out = await discoverAndPay(config, "fx quote for a currency pair", { maxAmount: "100000" });
if (out.ok) console.log(out.data.body);

maxAmount is required and has no default. It is the ceiling for a single call, in the asset's atomic units as a string (7 decimals for USDC, so "100000" is 0.01). The cap is checked against the real paid quote, not only the unpaid probe.

Seller: make an endpoint discoverable

describeEndpoint builds the discovery metadata you attach to your x402 paywall route. The facilitator catalogs your endpoint, with these parameter descriptions, on the first settled payment. There is no separate registration step.

import { describeEndpoint } from "@rail402.dev/sdk";

const extensions = describeEndpoint({
  params: {
    base: { description: "Base currency or asset, such as XLM or BTC.", example: "XLM" },
    quote: { description: "Quote currency, such as USD.", required: false, example: "USD" },
  },
  outputExample: { base: "XLM", quote: "USD", price: 0.1234 },
});

// Attach `extensions` to your paywall route (here with @x402/hono):
//   "GET /quote": {
//     accepts: { scheme: "exact", network: "stellar:testnet", price: { amount: "100000", asset: "C..." }, payTo: "G..." },
//     description: "Live FX and crypto spot quote for a currency or asset pair.",
//     extensions,
//   }

Handling results

Buyer calls never throw a string. They return a Result you branch on:

type Result<T> =
  | { ok: true; data: T }
  | { ok: false; error: { code: string; reason: string; retryable: boolean } };

const paid = await payAndFetch(config, url, { maxAmount: "100000" });
if (!paid.ok) {
  console.error(paid.error.code, paid.error.reason, paid.error.retryable);
}

code is a stable identifier, reason is always a non-null sentence, and retryable tells an agent whether trying again could help. Codes come from @rail402.dev/errors.

Import only one role

Every symbol is on the package root. To pull in only one side, import a narrower entry point:

import { discoverAndPay }  from "@rail402.dev/sdk/buyer";   // = @rail402.dev/agent-helpers
import { describeEndpoint } from "@rail402.dev/sdk/seller";  // = @rail402.dev/seller-helpers
import { X402Error }        from "@rail402.dev/sdk/errors";  // = @rail402.dev/errors

Related packages

• @rail402.dev/cli (rail402) drives this same flow from a terminal or an AI agent.
• @rail402.dev/facilitator runs the facilitator, or lets you verify and settle in-process.
• @rail402.dev/scheme-upto-stellar adds the upto scheme for metered billing.

Testnet-first. Part of Rail402. Apache-2.0.