Quickstart

This guide helps you run the RailBridge cross-chain x402 Facilitator, a sample merchant server, and a sample client end-to-end on your local machine.

1. Prerequisites

• Node.js 18+ and npm

• Access to an EVM testnet RPC (for example, Base Sepolia)

• Testnet tokens (for example, USDC on Base Sepolia) in:

  • A facilitator wallet (for paying gas and bridging)

  • A client wallet (for making payments)

2. Clone and Install

From your workspace:

git clone <your-railbridge-repo-url>
cd RailBridge\ AI/facilitator
npm install

3. Configure the Facilitator

Copy the environment template and fill in the required values:

cp env.template .env

Edit .env and set at least:

• EVM_PRIVATE_KEY – facilitator wallet private key (testnet)

• EVM_RPC_URL – RPC URL for your EVM testnet (for example, Base Sepolia)

• Optionally, DEPLOY_ERC4337_WITH_EIP6492=true if you want ERC-4337 smart wallet support

4. Start the Facilitator

From the facilitator directory:

npm run dev

This starts the RailBridge Facilitator on http://localhost:4022 with:

• POST /verify

• POST /settle

• GET /supported

• GET /health

You should see logs confirming that the EVM networks and cross-chain router are initialized.

5. Configure and Run a Merchant Server

In a new terminal, stay in the facilitator directory.

Set the environment variables for the merchant. You can either:

Option A: Use the same .env file

Ensure the following variables are present in .env:

• FACILITATOR_URL=http://localhost:4022

• MERCHANT_ADDRESS=0xYourMerchantAddressOnDestinationChain

• FACILITATOR_ADDRESS=0xFacilitatorLockAddressOnSourceChain

Then run the cross-chain merchant server:

npm run test:merchant

This starts src/merchant-server.ts on http://localhost:4021 and configures:

• Source network: Base Sepolia (eip155:84532)

• Destination network: Ethereum Sepolia (eip155:11155111)

• payTo: facilitator address on the source chain

• cross-chain extension: destination network, asset, and merchant address

Option B: Same-chain merchant (optional)

If you want to try same-chain payments first:

npm run test:merchant-same-chain

This starts src/merchant-server-same-chain.ts, where users and merchant are on the same chain and no cross-chain extension is used.

6. Configure the Client

In another terminal, again from the facilitator directory:

cp env.template .env.client

Edit .env.client and set:

• CLIENT_PRIVATE_KEY=0xYourClientPrivateKey

• EVM_RPC_URL=https://sepolia.base.org (or your Base Sepolia RPC)

• MERCHANT_URL=http://localhost:4021

The client uses this key to sign payments on the source chain.

7. Run the Client Example

Run the example client:

npm run example:client

The client will:

1. Request the protected route from the merchant at /api/premium.

2. Receive x402 payment requirements.

3. Select a suitable exact EVM requirement (for example, Base Sepolia).

4. Construct and sign a paymentPayload using @x402/evm.

5. Send the signed payload back via the merchant to the facilitator.

6. Log:

   • HTTP status and JSON response

   • Settlement details from the PAYMENT-RESPONSE header (transaction hash, network, payer)

For cross-chain mode, the facilitator will settle on the source chain and invoke the bridge service stub to simulate bridging to the destination chain.

8. Where to Look in the Code

• Facilitator server:

  • src/facilitator-implementation.ts

• Merchant servers:

  • src/merchant-server.ts (cross-chain)

  • src/merchant-server-same-chain.ts (same-chain)

• Client example:

  • src/client-example.ts

These files provide end-to-end examples of how the facilitator, merchant, and client interact using x402 and the cross-chain extension.

9. Next Steps

• Read the main README.md in the facilitator folder for a deeper architecture overview and API details.

• Explore the merchant and client integration guides to adapt RailBridge for your own application.