Rail402

x402 payments and discovery for Stellar. Rail402 is an x402 facilitator: it verifies and settles pay-per-request payments on Stellar and pays the network fee, so buyers need no XLM. Every API or MCP tool that gets paid through it is cataloged in its Bazaar, where agents and developers can find it with filters or plain-language search.

• Works with the stock x402 packages (@x402/fetch, @x402/express, @x402/stellar); nothing Rail402-specific to install in your client or server.

• Two schemes: exact (a fixed price) and upto (the buyer signs a cap, the seller settles what the call used, through a Soroban settlement contract).

• Non-custodial: the buyer signs the payment, the seller receives it directly, Rail402 only sponsors the fee.

• Agent tools: a buyer SDK, an MCP server (rail402-mcp) and a CLI (rail402) that find and pay resources under a spending cap.

• Hosted testnet instance, free and without an API key; or run your own with one command.

• Apache-2.0.

Release state. The npm packages are at 0.5.2: the facilitator, the Bazaar and search, upto, the agent tools (@rail402.dev/sdk, @rail402.dev/mcp, @rail402.dev/cli) and their browser entries, and the transaction reader @rail402.dev/x402-index. The hosted testnet service runs 0.5.0 with exact and upto. The latest service release and container image is 0.2.1 (exact only); later versions of the service run from a checkout. The newest GitHub release, upto-contract-v1.0.0, publishes the upto settlement contract's WASM. The changelog lists what each release adds. The sections below say which release each command uses.

Documentation: docs.rail402.dev

Try it in a minute

The hosted testnet facilitator (0.5.0, exact and upto) is public:

curl https://testnet.rail402.dev/supported
curl "https://testnet.rail402.dev/discovery/search?query=weather%20forecast%20under%201%20cent"

To pay from a browser instead, open the Playground at playground.rail402.dev.

Related MCP server: paypulse

Sell an API

Point a stock x402 resource server at Rail402. With Express:

npm install express@5 @x402/express@2.29.0 @x402/core@2.29.0 @x402/stellar@2.29.0 @x402/extensions@2.29.0

import express from "express";
import { HTTPFacilitatorClient, x402ResourceServer } from "@x402/core/server";
import { paymentMiddleware } from "@x402/express";
import { bazaarResourceServerExtension, declareDiscoveryExtension } from "@x402/extensions/bazaar";
import { ExactStellarScheme } from "@x402/stellar/exact/server";

const facilitator = new HTTPFacilitatorClient({ url: "https://testnet.rail402.dev" });
const server = new x402ResourceServer(facilitator)
  .register("stellar:testnet", new ExactStellarScheme())
  .registerExtension(bazaarResourceServerExtension);

const app = express();
app.use(
  paymentMiddleware(
    {
      "GET /weather": {
        accepts: { scheme: "exact", price: "$0.01", network: "stellar:testnet", payTo: process.env.PAY_TO! },
        description: "Current weather for a city",
        extensions: declareDiscoveryExtension({ input: { city: "Ankara" } }),
      },
    },
    server,
  ),
);
app.get("/weather", (_req, res) => res.json({ temperature: 21, conditions: "sunny" }));
app.listen(4021);

Each paid request settles in testnet USDC straight to PAY_TO. Deployed on a public host, the endpoint is listed in the Bazaar after its first payment. Full walkthrough, including a receiving account with a USDC trustline: Quickstart for sellers.

Pay for one

npm install @x402/fetch@2.29.0 @x402/core@2.29.0 @x402/stellar@2.29.0

import { wrapFetchWithPaymentFromConfig } from "@x402/fetch";
import { createEd25519Signer } from "@x402/stellar";
import { ExactStellarScheme } from "@x402/stellar/exact/client";

const pay = wrapFetchWithPaymentFromConfig(fetch, {
  schemes: [
    {
      network: "stellar:testnet",
      client: new ExactStellarScheme(createEd25519Signer(process.env.BUYER_SECRET!, "stellar:testnet")),
    },
  ],
});
const response = await pay("https://demo.rail402.dev/weather?city=Ankara");
console.log(response.status, await response.json());

The buyer needs testnet USDC and no XLM for fees. Creating a funded account takes one script: Quickstart for buyers.

Run your own facilitator

With the released container image (0.2.1, exact only), a testnet facilitator is three commands. Create a fee sponsor, fund it with Friendbot, and start the service (STORE=memory keeps state in the process; use Postgres for anything that must survive a restart):

docker run --rm ghcr.io/tolgayayci/rail402:0.2.1 node -e \
  'const k = require("@stellar/stellar-sdk").Keypair.random(); console.log(k.publicKey(), k.secret())'
curl "https://friendbot.stellar.org?addr=G..."          # the public key printed above
docker run -p 8080:8080 -e STORE=memory \
  -e TESTNET_RPC_URL=https://soroban-testnet.stellar.org -e TESTNET_SPONSOR_SECRET=S... \
  ghcr.io/tolgayayci/rail402:0.2.1

curl localhost:8080/ready answers 200 once the channel accounts exist, within seconds.

For a durable setup with Postgres, one command from a clone (this builds the checked-out source, so it includes everything below); it creates a fee sponsor funded by Friendbot and waits until the service is ready:

git clone https://github.com/tolgayayci/rail402.git && cd rail402
./deploy/docker.sh  # Docker on this machine: Postgres + Rail402 on 127.0.0.1:8080

Or embed the settlement engine in your own server with npm install @rail402.dev/facilitator: In-process. Configuration, keys and operations: Configuration, Operations.

What's inside

Every rejection has a stable code and a reason: Verification rules. The upstream x402 e2e suite passes against Rail402 on the Stellar testnet (conformance runs), and search quality is measured on a public dataset with one command, pnpm eval (search evaluation).

stellar:pubnet can be configured; the hosted instance runs on testnet.

Packages

Develop

Requires Node.js 24.11 or later and pnpm 11 (corepack enable, or mise install), and Docker for the integration tests. See CONTRIBUTING.md.

pnpm install
pnpm verify                                 # format, lint, typecheck, unit tests, licence gate
docker compose --profile stellar up -d      # Postgres + a private Stellar network
pnpm test:integration

Licence

Apache-2.0. pnpm license:gate fails the build if any production dependency is not permissively licensed; see the dependency licence report.