Technical architecture

Rail402 is a production x402 facilitator, a Stellar-native Bazaar discovery layer, and the agent tooling around them. This section documents how it is built and how it integrates with Stellar, component by component. Every significant claim links to a live endpoint, a settled transaction on chain, or a file in the source tree. It runs on stellar:testnet today at facilitator.rail402.dev, free and with no API key.

​

The system at a glance

The facilitator and the Bazaar are the same Node process. A resource is cataloged only from inside the facilitator’s own /verify and /settle handlers, so a listing always corresponds to a real payment path. The MCP server and the SDK/CLI are separate surfaces that speak to it. The Explorer watches the ledger independently and classifies x402 settlements across every facilitator, not only Rail402’s.

​

The Stellar integration

Rail402 is not x402 that happens to target Stellar. Every component is built on a specific Stellar primitive. This table lists each piece, the exact Stellar mechanism it uses, and the on-chain proof it works. The deep pages expand each row.

​

The map

This section is organized the way a payment moves, from the settlement path out to discovery, then to the conformance and operations that keep it correct.

​

See it live

Rail402 is deployed, not described. These are the fastest checks to run.

​

Built on @x402/stellar

Settlement on Stellar is largely solved, so Rail402 builds on the Apache-2.0 @x402/stellar package rather than reimplementing it. @x402/stellar provides the exact scheme mechanics and @x402/core provides the facilitator registry and the /supported shape. On top of that base, Rail402 adds:

• an error-enrichment layer that gives every exact rejection a non-null human reason the package otherwise leaves empty (Settlement);
• an entire second scheme, upto, written from scratch with its own Soroban contract (upto);
• the Bazaar, meaning cataloging, integrity, and search, which the base package does not provide (Discovery);
• the MCP interface, the SDK and CLI helpers, the conformance harness, and the Explorer.

The dividing line matters for audit scope: the cryptographic settlement path is the reviewed upstream package, while Rail402’s own code is configuration, validation, discovery, and one small non-custodial Soroban contract.

​

What is proven, and what remains

Stated plainly, because an honest boundary is more useful than an unqualified claim. All of this is on stellar:testnet. Proven on chain today:

• exact and upto settling from both classic (G…) keypairs and __check_auth (C…) smart accounts, across ten published transaction hashes (Verify it yourself).
• Fee sponsorship and the non-custodial invariant, visible on ledger: the fee is charged to the facilitator, and the transfer from is never the transaction source.
• Automatic cataloging bound to settlement, and natural-language search, live on the deployed Bazaar.
• Interoperability with unmodified stock x402 clients, including two settlements in real testnet USDC driven by the upstream test suite (Conformance).

Work that remains:

• A third-party security review. Shipping a Soroban contract for upto widens the review scope beyond a pure off-chain service (Deployment), and that review has not yet run.
• Full coverage of the upstream x402 end-to-end suite. Two of four scenarios pass against real testnet USDC, and the other two fail for a diagnosed defect in the upstream harness rather than in Rail402 (Conformance).

​

Next steps