RailPayDocs
Sandbox. No real funds move and nothing settles on a chain yet. What this means

Guides

x402 payments

Request, get a price, pay, retry. All over HTTP.

The sandbox serves two demo resources and any paywall you create. All of them answer with HTTP 402 until paid.

ResourcePriceReturns
GET /x402/demo/time0.001 SUSDThe server time
GET /x402/demo/quote0.002 SUSDA random line from a fixed list
GET /x402/p/:idSet by the ownerThe paywall content

1. Request the resource

bash
curl -i https://dapp.railpay.app/x402/demo/time

Without a valid X-PAYMENT header the response is 402 with the payment requirements:

402 Payment Required
{
  "x402Version": 1,
  "error": "payment_required",
  "accepts": [{
    "scheme": "exact",
    "network": "railpay-sandbox",
    "maxAmountRequired": "1000",
    "asset": "SUSD",
    "payTo": "<account id>",
    "resource": "<url>",
    "description": "...",
    "mimeType": "application/json",
    "maxTimeoutSeconds": 60
  }]
}

2. Pay with the agent key

Send one item of accepts to POST /v1/agent/pay. RailPay checks the agent's policy, writes an x402 ledger entry and returns a payment token.

bash
curl -X POST https://dapp.railpay.app/v1/agent/pay \
  -H "Authorization: Bearer $RAILPAY_AGENT_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "requirement": { ...one item of accepts... } }'
json
{ "payment": "<base64 token>" }

The token is an HMAC-signed receipt { entry_id, resource, amount, payTo, exp }. It is valid for 5 minutes, for that resource only, and can be used once.

3. Retry with the token

bash
curl -i https://dapp.railpay.app/x402/demo/time \
  -H "X-PAYMENT: <token>"

The response is 200 with the resource and an X-PAYMENT-RESPONSE header: base64 of { entry_id, success: true }.

When a payment is blocked

If the policy says no, /v1/agent/pay fails with the block reason (for example over_per_request or host_not_allowed) and the attempt is logged in the agent's events.

Try it in the browser

The x402 Playground page in the app runs this flow live with one of your agent keys.

The RailPay app runs in Sandbox mode. Balances are in Sandbox USD (SUSD). No real funds move and nothing settles on a chain. Chains, stablecoins, card issuing, ramps, fees and yield are TBD.

© 2026 RailPay. Built as practical payment infrastructure, not a token or fundraising project.