Charge for an endpoint

By the end of this page an unpaid request to your route returns a priced 402, a real payment settles on testnet, and your endpoint shows up in the Bazaar catalog after that first settled payment. No registration step and no API key. This guide uses @rail402.dev/sdk for the discovery listing and the stock @x402 packages for the paywall itself. Everything runs against the hosted facilitator at https://facilitator.rail402.dev.

Prerequisites

Node.js 20 or later (the packages target the current Node LTS), and a testnet account to receive payments (payTo). Create and fund a payTo account with the Rail402 CLI:

npx @rail402.dev/cli fund

It prints the account address (G...) and secret. The receiver must trust the asset it is paid in, so add a trustline to testnet USDC (CBIELTK6YBZJU5UP2WWQEUCYKLPU6AUNZ2BQ4WWFEIE3USCIHMXQDAMA) to that account, for example in Stellar Lab. See Stellar essentials for why the receiver needs one. (Or create and fund an account by hand with friendbot.)

You do not need any XLM in the buyer’s account. The facilitator is the transaction source and sponsors the network fee, so a buyer needs only the payment asset. See Payment loop.

1. Install

Install the SDK for the listing and the stock @x402 paywall packages, pinned to 2.20.0.

npm install @rail402.dev/sdk
npm install @x402/core@2.20.0 @x402/hono@2.20.0 @x402/stellar@2.20.0 @x402/extensions@2.20.0 hono @hono/node-server

For Express, swap @x402/hono for @x402/express@2.20.0. The route configuration object is identical.

2. Add the paywall and the listing

The middleware is stock @x402. The describeEndpoint call from @rail402.dev/sdk turns the paywalled route into a Bazaar listing by attaching discovery metadata under extensions.

Hono
Express

server.js

import { serve } from "@hono/node-server";
import { Hono } from "hono";
import { paymentMiddleware } from "@x402/hono";
import { x402ResourceServer, HTTPFacilitatorClient } from "@x402/core/server";
import { ExactStellarScheme } from "@x402/stellar/exact/server";
import { bazaarResourceServerExtension } from "@x402/extensions/bazaar";
import { describeEndpoint } from "@rail402.dev/sdk";

const USDC = "CBIELTK6YBZJU5UP2WWQEUCYKLPU6AUNZ2BQ4WWFEIE3USCIHMXQDAMA"; // testnet USDC SAC

const x402 = new x402ResourceServer([
  new HTTPFacilitatorClient({ url: "https://facilitator.rail402.dev" }),
]);
x402.register("stellar:*", new ExactStellarScheme());
x402.registerExtension(bazaarResourceServerExtension); // automatic cataloging

const app = new Hono();
app.use("*", paymentMiddleware({
  "GET /quote": {
    accepts: {
      scheme: "exact",
      network: "stellar:testnet",
      price: { amount: "500000", asset: USDC }, // "500000" stroops = 0.05 USDC
      payTo: process.env.SELLER_ADDRESS,        // G..., with a USDC trustline
      maxTimeoutSeconds: 60,                     // required on v2 requirements
    },
    description: "A price quote for a named commodity.", // the resource description lives here
    mimeType: "application/json",
    extensions: describeEndpoint({
      params: { symbol: { description: "Ticker such as XLM or BTC.", example: "XLM" } },
    }),
  },
}, x402));

// The real handler runs only after a payment settles.
app.get("/quote", (c) => c.json({ symbol: c.req.query("symbol") ?? "XLM", price: 0.1234 }));

serve({ fetch: app.fetch, port: 4023 });

server.js

import express from "express";
import { paymentMiddleware } from "@x402/express";
import { x402ResourceServer, HTTPFacilitatorClient } from "@x402/core/server";
import { ExactStellarScheme } from "@x402/stellar/exact/server";
import { bazaarResourceServerExtension } from "@x402/extensions/bazaar";
import { describeEndpoint } from "@rail402.dev/sdk";

const USDC = "CBIELTK6YBZJU5UP2WWQEUCYKLPU6AUNZ2BQ4WWFEIE3USCIHMXQDAMA"; // testnet USDC SAC

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

const app = express();
app.use(paymentMiddleware({
  "GET /quote": {
    accepts: {
      scheme: "exact",
      network: "stellar:testnet",
      price: { amount: "500000", asset: USDC }, // "500000" stroops = 0.05 USDC
      payTo: process.env.SELLER_ADDRESS,
      maxTimeoutSeconds: 60,
    },
    description: "A price quote for a named commodity.",
    mimeType: "application/json",
    extensions: describeEndpoint({
      params: { symbol: { description: "Ticker such as XLM or BTC.", example: "XLM" } },
    }),
  },
}, x402));

app.get("/quote", (req, res) => res.json({ symbol: req.query.symbol ?? "XLM", price: 0.1234 }));

app.listen(4023);

describeEndpoint returns the whole extensions value, already shaped as { bazaar: ... }. Its return type is branded, so wrapping it again as { bazaar: describeEndpoint(...) } is a compile error. That catches the most common cataloging mistake. See Get discovered.

3. Start the server

SELLER_ADDRESS=G...your-payto-address node server.js

4. See the 402

An unpaid request now returns a priced 402 with the payment terms in the response:

curl -i "http://localhost:4023/quote?symbol=XLM"
# HTTP/1.1 402 Payment Required

5. Pay it

Cataloging is settlement-gated, so make the first payment yourself. The buyer needs a funded testnet account holding testnet USDC (get testnet USDC from the Circle faucet). The command-line wallet is the shortest path. CLI amounts are decimals, so --max 0.10 is 0.10 USDC.

RAIL402_SECRET=S...your-buyer-secret \
  npx @rail402.dev/cli pay "http://localhost:4023/quote" --max 0.10 --query symbol=XLM

It prints a settled transaction hash, a 64-character hex string. Open it on the explorer to see the settlement on chain: the transfer sender is the buyer and the fee is charged to the facilitator, which proves sponsorship. Each run produces a new hash, because a settlement hash is unique to its transaction.

Prefer to pay from code? Use payAndFetch from @rail402.dev/sdk, covered in the Buyer quickstart.

6. Confirm it is cataloged

After the payment settles, search the Bazaar for words from your description:

curl -s "https://facilitator.rail402.dev/discovery/search?query=commodity%20price" | jq '.resources[].resource'

Your endpoint’s URL appears in the results. It is now discoverable to any agent.

The facilitator catalogs only endpoints reachable on a public hostname. A localhost or private-host URL is soft-dropped from the catalog even though its payment settles. To see your listing in the Bazaar, run your endpoint on a public host, or run the bundled example below, which handles this end to end.

Try the whole loop

The examples/paid-api-agent example in the Rail402 repository runs a paid API that an agent discovers and pays, against testnet, in one command. It is the fastest way to watch verify, settle, catalog, and discover happen in sequence.

Next steps

Get discovered

Write parameter descriptions an agent can act on, and learn exactly what the facilitator catalogs and when.

Meter usage with upto

Bill for actual usage against a buyer-authorized ceiling instead of a fixed price.

Self-facilitation

Run verify and settle in-process, with no external facilitator and no network hop.

Preflight and testing

Catch a missing trustline or misconfigured payTo before a stranger’s payment fails on it.

When it fails

Every rejection carries a machine-readable code and a non-null reason. A 402 that never settles, a listing that never appears, or a payment that is refused all report a code you can branch on. See Errors.

Start here

Buyers & agents

Sellers

Operators

Concepts

Reference

Support

Charge for an endpoint

Prerequisites

1. Install

2. Add the paywall and the listing

3. Start the server

4. See the 402

5. Pay it

6. Confirm it is cataloged

Try the whole loop

Next steps

Get discovered

Meter usage with upto

Self-facilitation

Preflight and testing

When it fails

​Prerequisites

​1. Install

​2. Add the paywall and the listing

​3. Start the server

​4. See the 402

​5. Pay it

​6. Confirm it is cataloged

​Try the whole loop

​Next steps

Get discovered

Meter usage with upto

Self-facilitation

Preflight and testing

​When it fails

Prerequisites

1. Install

2. Add the paywall and the listing

3. Start the server

4. See the 402

5. Pay it

6. Confirm it is cataloged

Try the whole loop

Next steps

When it fails