# Rail402

> x402 facilitator, Bazaar discovery, and agent tooling on Stellar.

> ## Agent Instructions
> Rail402 is an x402 payment facilitator, Stellar-native Bazaar discovery layer, and agent tooling for the Stellar network. It currently targets stellar:testnet.
> The live testnet facilitator is https://facilitator.rail402.dev with endpoints /verify, /settle, /supported, /health, and /discovery/*.
> Payment amounts use 7-decimal SEP-41 integer (stroop) arithmetic. Never use floating-point math for amounts.
> Every rejection returns a machine-readable error code and a non-null human-readable reason. When explaining a failure, surface both.

## Docs

- [Rail402](https://docs.rail402.dev/index.md): Settle pay-per-request x402 payments on Stellar, publish services that agents can find, and pay for them from code, the terminal, or an agent runtime.
- [How Rail402 works](https://docs.rail402.dev/start/how-it-works.md): The x402 payment loop on Stellar, the four addresses in play, and the difference between the exact and upto schemes, in one page.
- [Install and first payment](https://docs.rail402.dev/start/quickstart.md): See the live facilitator respond with no setup, then make your first real testnet payment from the command line and verify it on the explorer.
- [Pay for a resource](https://docs.rail402.dev/buyers/quickstart.md): Settle one real testnet payment for an x402 resource on Stellar with the Rail402 SDK, capped so it can never spend more than you allow.
- [Sign and pay](https://docs.rail402.dev/buyers/sign-and-pay.md): How an x402 payment works on Stellar step by step: the 402 challenge, signing a Soroban authorization entry, the retry, and the Result you read back.
- [Discover services](https://docs.rail402.dev/buyers/discover.md): Search the Stellar Bazaar with searchBazaar, read a listing's price, asset identity, trustline state, and input schema, then pay the best match with discoverAndPay.
- [Spend controls and budgets](https://docs.rail402.dev/buyers/spend-controls.md): How Rail402 caps buyer spending: the mandatory per-call maxAmount, the maxAmountCeiling hard limit, atomic-unit amounts, and where enforcement actually happens.
- [Smart-account buyers](https://docs.rail402.dev/buyers/smart-accounts.md): Pay from an OpenZeppelin __check_auth contract account with a session key and an on-ledger spending policy, and how it composes with the upto scheme's reserve-then-reconcile.
- [Pay over MCP](https://docs.rail402.dev/buyers/mcp.md): Give an agent runtime two Model Context Protocol tools: search the Stellar Bazaar and make a paid call under a mandatory spend cap, over stdio or the hosted HTTP server.
- [The rail402 CLI](https://docs.rail402.dev/buyers/cli.md): A command-line x402 wallet and agent tool for Stellar: fund a testnet account, search the Bazaar, pay under a spend cap, and verify settlements, with a JSON mode for agents and a bundled Claude skill.
- [Charge for an endpoint](https://docs.rail402.dev/sellers/quickstart.md): Put an x402 paywall on an HTTP route so it answers unpaid requests with a priced 402, settles a payment in testnet USDC, and appears in the Bazaar after its first settled payment.
- [Get discovered](https://docs.rail402.dev/sellers/get-discovered.md): Write discovery metadata with describeEndpoint so an agent can read, choose, and correctly call your endpoint, and understand exactly what the facilitator catalogs and when.
- [Charge for an MCP tool](https://docs.rail402.dev/sellers/mcp-tool.md): List a paid MCP tool as a first-class Bazaar resource with describeTool, keyed on the resource URL and tool name.
- [Meter usage with upto](https://docs.rail402.dev/sellers/upto.md): Charge for actual usage with the upto scheme: the buyer authorizes a ceiling, and only the amount you actually use settles on chain.
- [Self-facilitation](https://docs.rail402.dev/sellers/self-facilitation.md): Run verify and settle in-process inside your resource server, with no external facilitator and no network hop, using buildFacilitator from @rail402.dev/facilitator.
- [Preflight and testing](https://docs.rail402.dev/sellers/preflight.md): Check your payTo and asset with preflight before a buyer's payment fails on them, and run the whole loop locally against a facilitator you control.
- [Run the facilitator](https://docs.rail402.dev/operators/run.md): Serve verify, settle, and the Bazaar on stellar:testnet, hosted or self-hosted, in one command.
- [Configuration](https://docs.rail402.dev/operators/configuration.md): Every meaningful facilitator environment variable, the fee ceiling, and the fee model, with the caveats that bite you first.
- [Bazaar operations](https://docs.rail402.dev/operators/bazaar.md): The catalog runs inside the facilitator. Make it durable, understand the cataloging lifecycle, and read its health.
- [Run the MCP discovery server](https://docs.rail402.dev/operators/mcp-server.md): Serve the agent-facing search and paid-call tools over Streamable HTTP, or use the hosted testnet instance.
- [Monitoring and runbook](https://docs.rail402.dev/operators/operations.md): Watch the facilitator with /health and /metrics, hold the uptime target, and know what a caller sees when settlement or indexing is degraded.
- [Security and trust boundaries](https://docs.rail402.dev/operators/security.md): The facilitator is a trust boundary and non-custodial. What it validates, and how it resists poisoning, SSRF, and replay.
- [The payment loop](https://docs.rail402.dev/concepts/payment-loop.md): x402 in one sentence, the request-to-resource loop step by step, the facilitator's three endpoints, and the roles every other page assumes.
- [The exact scheme](https://docs.rail402.dev/concepts/exact.md): Fixed-price settlement on Stellar: the buyer signs a Soroban authorization entry for one exact amount, valid for a bounded number of ledgers, and the facilitator sponsors the fee.
- [The upto scheme](https://docs.rail402.dev/concepts/upto.md): Metered settlement on Stellar: the buyer authorizes a ceiling, and a Soroban contract settles only the actual usage, once, never above the ceiling.
- [Bazaar: metadata, cataloging and trust](https://docs.rail402.dev/concepts/bazaar.md): What a Bazaar listing is, how it enters the catalog through settlement, the seven discovery filters, and why the facilitator treats client-supplied metadata as untrusted.
- [How search works](https://docs.rail402.dev/concepts/search.md): Natural-language Bazaar search: a BM25 and static-embedding hybrid fused with RRF, in-process with no external engine, plus the response-key asymmetry and the honest limits.
- [Stellar essentials](https://docs.rail402.dev/concepts/stellar.md): A one-page primer on the Stellar mechanics x402 relies on: trustlines, SEP-41 tokens and stroop math, fee sponsorship, authorization entries, and smart accounts.
- [Packages](https://docs.rail402.dev/reference/packages.md): The @rail402.dev npm packages, what each one is for, and which two or three you actually install.
- [@rail402.dev/sdk](https://docs.rail402.dev/reference/sdk.md): The SDK surface: buyer functions, seller functions, the config object, the Result type, and the subpath exports.
- [CLI reference](https://docs.rail402.dev/reference/cli.md): Every rail402 command and flag, the --json envelope, and the config precedence order.
- [Error registry](https://docs.rail402.dev/reference/errors.md): Every rejection carries a machine-readable code, a non-null reason, and a retryable flag. How to read them and how to handle them.
- [Conformance](https://docs.rail402.dev/reference/conformance.md): Wire-test a Rail402 deployment against the upstream x402 e2e suite, and read the dual-run verdict.
- [FAQ](https://docs.rail402.dev/support/faq.md): Short answers to the questions that come up first: cost, packages, XLM, trustlines, interop, schemes, custody, and network.
- [Troubleshooting](https://docs.rail402.dev/support/troubleshooting.md): Common failure states framed as symptom, cause, and fix, each linked to its error code.
- [Technical architecture](https://docs.rail402.dev/architecture/overview.md): How Rail402 implements an x402 facilitator, a Bazaar discovery layer, and agent tooling on Stellar: the settlement path, the upto Soroban contract, the discovery trust boundary, wire-level conformance, and the live endpoints that prove it works.
- [Verify it yourself](https://docs.rail402.dev/architecture/proofs.md): Copy-paste curl commands against the live testnet facilitator, the settled transaction for every scheme and payer type, the deployed Soroban contracts, and the upstream contributions. Every claim in this section is checkable in a terminal.
- [The settlement path](https://docs.rail402.dev/architecture/settlement.md): How Rail402 verifies and settles a payment on Stellar: the buyer signs a Soroban authorization entry, the facilitator builds and submits the invocation, and the non-custodial invariant holds because the facilitator is never a party to the transfer.
- [Fee sponsorship and fee ceilings](https://docs.rail402.dev/architecture/fees.md): How Rail402 pays the Stellar network fee so a buyer needs no XLM, why areFeesSponsored is computed truthfully rather than declared, and how MAX_TRANSACTION_FEE_STROOPS bounds what the facilitator will sign for both exact and upto.
- [Expiration, replay, and front-running](https://docs.rail402.dev/architecture/expiration-replay.md): How a Stellar authorization is bounded in time by signatureExpirationLedger, how Rail402 handles the race where an entry expires between verify and settle, and why a settlement resists replay and front-running by construction.
- [Stellar-specific engineering](https://docs.rail402.dev/architecture/stellar-engineering.md): The Stellar mechanics behind the facilitator: SEP-41 seven-decimal stroop arithmetic, provable SAC asset identity, trustline pre-flight, Soroban resource limits and simulation, and channel-account throughput under bursty agent traffic.
- [The upto scheme and its Soroban contract](https://docs.rail402.dev/architecture/upto.md): Metered settlement on Stellar: why upto ships a Soroban contract, the two-node authorization tree that leaves the actual amount unsigned, and the on-ledger guarantees (single-use nonce, ledger-bounded expiration, zero-amount handling, and a settlement hook), with the deployed contract as proof.
- [Smart accounts and spending policies](https://docs.rail402.dev/architecture/smart-accounts.md): How Rail402 settles from __check_auth contract accounts as well as classic keypairs, and how the upto settlement hook composes with an OpenZeppelin smart-account spending policy to keep an agent inside an on-ledger budget through a reserve-then-reconcile pattern.
- [The discovery trust boundary](https://docs.rail402.dev/architecture/discovery.md): How the Bazaar catalogs a resource automatically through settlement, why the facilitator treats every client-supplied field as untrusted, how routeTemplate traversal and listing takeover are prevented, and how Stellar listings interoperate with the wider x402 ecosystem.
- [The agent-facing MCP interface](https://docs.rail402.dev/architecture/mcp.md): An MCP server that lets an agent search the Stellar Bazaar and make a paid call from inside its runtime, with strict structured schemas in both directions, a spend cap enforced at the moment of signing, and a non-null reason on every rejection.
- [Retrieval architecture](https://docs.rail402.dev/architecture/retrieval.md): How Bazaar search ranks the catalog: a weighted-field BM25 arm fused with an in-process static-embedding arm via Reciprocal Rank Fusion, why it runs in-process, and how ranking stays abuse-resistant.
- [Evaluation methodology and results](https://docs.rail402.dev/architecture/evaluation.md): How Rail402 measures Bazaar search quality: blind graded human judgments over real captured listings, a tunable dev slice and a measured-once locked slice, standard IR metrics with Wilson confidence intervals and CI regression floors, and results across 20, 2,000, and 18,450 documents.
- [Reproduce the numbers](https://docs.rail402.dev/architecture/reproduce.md): The exact commands that regenerate every Bazaar search figure, the provenance and license hygiene of the 18,450-document eval pack, and how the ranking stays current as the discovery spec moves.
- [Wire-level conformance](https://docs.rail402.dev/architecture/conformance.md): Conformance with the x402 specification is verified at the wire with stock clients, not asserted. The properties Rail402 conforms to, the on-chain proof of each, and an honest account of the upstream e2e suite.
- [Deployment, reliability, and licensing](https://docs.rail402.dev/architecture/deployment.md): How Rail402 runs as a managed service and as a codebase anyone can fork, the durable catalog and its degraded-mode behavior, the fail-closed permissive-license gate that keeps AGPL out of the dependency path, and the audit posture.
- [List supported schemes and networks](https://docs.rail402.dev/api-reference/facilitator/info/list-supported-schemes-and-networks.md): The ground truth for what this facilitator can do. Lists the payment kinds, the extensions it serves, and its settlement signer addresses.
- [Health and catalog storage status](https://docs.rail402.dev/api-reference/facilitator/info/health-and-catalog-storage-status.md)
- [Prometheus metrics](https://docs.rail402.dev/api-reference/facilitator/info/prometheus-metrics.md)
- [Verify a payment authorization](https://docs.rail402.dev/api-reference/facilitator/payments/verify-a-payment-authorization.md): Checks that a payment authorization is valid without submitting it. The stock `@x402/stellar` client builds the `paymentPayload`; you do not assemble it by hand.
- [Settle a payment on chain](https://docs.rail402.dev/api-reference/facilitator/payments/settle-a-payment-on-chain.md): Submits the payment on chain and returns the transaction hash. On a scheme rejection, `success` is `false` and the reason is in `errorMessage`, the field a stock resource server reads.
- [Browse the catalog](https://docs.rail402.dev/api-reference/facilitator/discovery/browse-the-catalog.md): Paginated, filterable catalog. The result array is `items`, paginated by offset.
- [Search the catalog](https://docs.rail402.dev/api-reference/facilitator/discovery/search-the-catalog.md): Natural-language ranking over the catalog. The result array is `resources` (not `items`), paginated by opaque cursor. A missing or empty `query` returns `400 invalid_payload`.
- [Payment stream, newest first](https://docs.rail402.dev/api-reference/explorer/payments/payment-stream-newest-first.md): Keyset-paginated stream of classified x402 payments. Filters combine with AND. Follow `nextCursor` for the next page; its absence means the last page. A cursor is bound to its ordering only — changing filters with an old cursor is safe but pages may overlap.
- [One payment with its raw on-chain transaction](https://docs.rail402.dev/api-reference/explorer/payments/one-payment-with-its-raw-on-chain-transaction.md): The same projection as `/feed` plus `raw` — the complete Soroban `getTransaction` JSON (envelope, auth entries, events) the classification was made from, so every claim is independently checkable against the ledger.
- [Headline numbers](https://docs.rail402.dev/api-reference/explorer/payments/headline-numbers.md)
- [The analytics snapshot for a live dashboard](https://docs.rail402.dev/api-reference/explorer/payments/the-analytics-snapshot-for-a-live-dashboard.md): All-time totals, trailing 24h/7d/30d activity windows (with new-participant counts), facilitator market share, and the most active sellers of the last 30 days — one poll-friendly response, cached ~15s server-side. `coverage` states which SAC transfers this deployment's tail watches ("all" on testnet…
- [Bucketed activity series for charts](https://docs.rail402.dev/api-reference/explorer/payments/bucketed-activity-series-for-charts.md): UTC day- or hour-bucketed payment activity, zero-filled so a chart axis is continuous, ending at the in-progress bucket (render the last point as "so far", not a drop). Cached ~30s server-side.
- [The seller / API directory (on-chain sellers ∪ Bazaar-registered)](https://docs.rail402.dev/api-reference/explorer/entities/the-seller-api-directory-on-chain-sellers-∪-bazaar-registered.md): A directory of sellers, ranked by on-chain activity. It is the UNION of two sources, so it is complete in both directions:   - every address that has been PAID on-chain (any facilitator, registered or not), with     payment count, unique buyers and settled volume; and   - every seller REGISTERED in…
- [A seller's identity, stats and payments](https://docs.rail402.dev/api-reference/explorer/entities/a-sellers-identity-stats-and-payments.md)
- [The facilitator registry with per-facilitator stats](https://docs.rail402.dev/api-reference/explorer/entities/the-facilitator-registry-with-per-facilitator-stats.md)
- [One facilitator with stats and recent payments](https://docs.rail402.dev/api-reference/explorer/entities/one-facilitator-with-stats-and-recent-payments.md)
- [One asset's page — stats, trailing windows, recent payments](https://docs.rail402.dev/api-reference/explorer/entities/one-assets-page-—-stats-trailing-windows-recent-payments.md): Keyed by the SAC contract address (the stable asset key — never the code string). `stats` is the /stats aggregate shape scoped to this asset plus its own volume (`total`/`totalDecimal`); `windows` carries trailing 24h/7d/30d activity; `payments` is a /feed-projected page with `nextCursor` (continue…
- [Self-register a facilitator (no auth needed — by design)](https://docs.rail402.dev/api-reference/explorer/registry/self-register-a-facilitator-no-auth-needed-—-by-design.md): Any x402 facilitator can announce its base URL. The explorer validates the URL (https, publicly routable), probes `GET {baseUrl}/supported` ITSELF, and registers only what it verified: the signer set and any advertised upto contract. From then on the facilitator's settlements are attributed to it an…
- [Service health](https://docs.rail402.dev/api-reference/explorer/ops/service-health.md)
- [Prometheus metrics (text/plain)](https://docs.rail402.dev/api-reference/explorer/ops/prometheus-metrics-textplain.md): Series: `x402_explorer_payments_total`, `x402_explorer_facilitators`, `x402_explorer_payments_by_scheme{scheme}`, `x402_explorer_payments_by_confidence{confidence}`, `x402_explorer_polls_total`, `x402_explorer_events_seen_total`, `x402_explorer_transactions_fetched_total`, `x402_explorer_payments_in…

## OpenAPI Specs

- [facilitator.openapi](https://docs.rail402.dev/api-reference/facilitator.openapi.yaml)
- [explorer.openapi](https://docs.rail402.dev/api-reference/explorer.openapi.yaml)

## Optional

- [Rail402 GitHub](https://github.com/tolgayayci/rail402)
- [Rail402 Explorer](https://explorer.rail402.dev)
- [Rail402 Playground](https://playground.rail402.dev)