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.
| Resource | Price | Returns |
|---|---|---|
| GET /x402/demo/time | 0.001 SUSD | The server time |
| GET /x402/demo/quote | 0.002 SUSD | A random line from a fixed list |
| GET /x402/p/:id | Set by the owner | The paywall content |
1. Request the resource
curl -i https://dapp.railpay.app/x402/demo/timeWithout a valid X-PAYMENT header the response is 402 with the payment requirements:
{
"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.
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... } }'{ "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
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.