> For the complete documentation index, see [llms.txt](https://docs.railbridge.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.railbridge.ai/documentation/welcome/welcome-to-railbridge.md). # Welcome to Railbridge ## Welcome Welcome! You've found the documentation for **Railbridge.** Railbridge helps merchants accept USDC payments from supported EVM chains using x402. Today the product is made up of two layers: * **Merchant OS**: the merchant-facing control plane for onboarding, API keys, products, balances, settlements, payouts, and webhooks * **Facilitator**: the payment plane that verifies x402 payments, settles them on-chain, and handles same-chain or cross-chain routing ### What is RailBridge? RailBridge is no longer just a raw cross-chain facilitator. The current integration model is: 1. Merchants define paid products and routes in Merchant OS. 2. Merchant backends protect those routes with `@railbridgeai/merchant-sdk`. 3. Buyers pay with the standard x402 `exact` flow on a supported source chain. 4. The facilitator verifies and settles the payment, then handles routing if funds need to move across chains. 5. Merchant OS tracks the lifecycle and can deliver signed webhook events back to the merchant. In the normal hosted flow, merchants should not manually call facilitator `/verify` or `/settle`; the SDK and payment middleware handle that wiring. ### Why RailBridge? In today's multi-chain world, users often hold assets on different blockchains. Traditional payment systems require users to bridge tokens themselves, pay gas on multiple chains, and navigate complex DeFi protocols. RailBridge solves this by: * **Seamless Cross-Chain Payments**: Users pay on their preferred chain, merchants receive on theirs * **Client Transparency**: Clients don't need to know anything about cross-chain mechanics; they just pay * **Merchant Control**: Merchants specify where they want to receive payments via simple configuration * **Secure**: Built on battle-tested x402 protocol with Coinbase's security standards * **Easy Integration**: Standard REST APIs that work with any x402-compatible client ### Why Teams Use RailBridge * **SDK-first integration**: Protect paid routes without mixing payment logic into business handlers * **USDC-first simplicity**: Current merchant-facing flows are centered on USDC across supported networks * **Same-chain and cross-chain support**: Accept payments where buyers already have funds and settle according to merchant routing needs * **Merchant-facing operations**: Manage products, balances, settlements, payouts, API keys, and webhooks in one place * **x402 compatibility**: Buyers still use normal x402 flows; cross-chain complexity stays behind the scenes ### How It Works 1. A merchant creates a paid product or route in Merchant OS. 2. The merchant backend mounts RailBridge route protection with the merchant SDK. 3. An unpaid request receives a standard `402 Payment Required` response. 4. The buyer retries with a signed x402 payment. 5. RailBridge verifies and settles the payment through the facilitator. 6. Merchant OS records lifecycle events and can notify the merchant via webhooks. ### Who This Documentation Is For * **Merchant teams** adding paid routes to APIs or agent backends * **Platform engineers** who want x402 payments without building chain-specific infrastructure * **Buyer/client developers** paying RailBridge-protected routes from supported EVM wallets * **Operators** running or evaluating the facilitator and testnet stack ### Getting Started Ready to dive in? Here's where to start: 1. **New to RailBridge?**: Start with the Quickstart Guide to see it in action 2. **Building a merchant?**: Check out the Merchant Integration Guide 3. **Building a client?**: See the Client Integration Guide 4. **Want to understand the architecture?**: Read the Architecture Overview ### Key Concepts * **Merchant OS**: the merchant control plane and merchant-facing API surface * **Facilitator**: the x402 payment plane for verification, settlement, and routing * **Merchant SDK**: the preferred merchant integration surface for route protection and webhook verification * **x402 `exact` scheme**: the current buyer payment flow used by RailBridge integrations * **Same-chain settlement**: funds stay on the network where the buyer paid * **Cross-chain settlement**: funds are routed toward the merchant's preferred destination network ### Need Help? * Check the Common Issues section for troubleshooting * Review the API Reference for detailed endpoint documentation * Explore the Example Implementations to see working code *** **Ready to get started?** Head over to the Quickstart Guide and have RailBridge running in minutes! --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.railbridge.ai/documentation/welcome/welcome-to-railbridge.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.