API Gateway
Overview
rail0 is a single immutable contract: buyer and merchant transact directly, and anyone can
call it. The rail0 API Gateway is a convenience layer on top — a REST API at
api.rail0.xyz that does the chain work a checkout would otherwise have to carry itself.
It does four things: it prepares everything a wallet has to sign, broadcasts what was signed and tracks it, confirms from the chain itself what actually happened, and notifies you. It holds no funds and no keys at any point: the gateway prepares, the wallet signs, the chain decides.
Prepare
Section titled “Prepare”The API builds whatever needs a signature, so your integration never assembles chain data itself: the EIP-3009 payload a buyer signs to authorize or charge (and a merchant signs to refund), and the unsigned transaction for every operation, with gas sized for the chain it runs on. Nothing is signed on the gateway. Signing happens in the buyer’s or the merchant’s wallet, and the gateway checks that what comes back is what it prepared.
Broadcast and track
Section titled “Broadcast and track”Hand back the signed transaction and the gateway sends it to the chain, retries transient
failures, and follows it through pending → submitting → submitted → confirmed, or
failed. A wallet that broadcasts for itself, like MetaMask, skips this step: report the
hash to POST /payments/{id}/{operation}/submitted and tracking continues from there. Every payment
carries in_flight while something is on its way, so a UI knows when to wait.
Confirm from the chain
Section titled “Confirm from the chain”The gateway does not take its own word for it. It reads the rail0 contract’s events on every
supported chain and applies an event only once its block is final by that chain’s rule
(safe, finalized, or a confirmation depth), so a payment moves to captured when the
chain says so, never before. A failed transaction records its decoded reason on the payment
and leaves the payment’s status alone, so the operation can be prepared again. A missed event
is caught up by transaction hash.
The clock runs here too: authorizations that lapse are expired, a submission that never
mined times out, and the payments.authorization_expiring notice goes out ahead of
authorization_expiry while there is still something to capture.
Notify
Section titled “Notify”Every change arrives as a webhook: signed, delivered at least once, with
retries and a per-subscription circuit breaker, and replayable from the API. Polling
GET /payments/{id} works too; the webhook is just sooner. Merchant accounts also get
sales analytics over their payments.
Who calls what
Section titled “Who calls what”| Party | Signs in as | Typical calls |
|---|---|---|
| Merchant | a wallet registered to a gateway account | create webhooks, prepare and submit capture / void / refund, read analytics |
| Buyer | any wallet — no account needed | create and sign a payment, list its own payments, open a dispute |
| Anyone | nothing | read the catalog of chains and tokens, discover a merchant’s payment methods, health |
Finality and settlement
Section titled “Finality and settlement”Confirmation time is a property of the chain, not of the gateway. GET /blockchains reports
each chain’s rule and, measured over the trailing week, the settlement percentiles from
broadcast to confirmation, so a checkout can size its wait honestly.
Supported chains
Section titled “Supported chains”The gateway serves these chains today. The waits are orders of magnitude,
from broadcast to the gateway counting the payment as settled; read GET /blockchains for
the live figures.
| Chain | Typical wait |
|---|---|
| Arc Testnet | under a second |
| Sonic Testnet | under a second |
| Polygon Amoy | about 2 seconds |
| Avalanche Fuji | about 7 seconds |
| Base Sepolia | 30 seconds to 2 minutes |
| Optimism Sepolia | about 40 seconds |
| Arbitrum Sepolia | 7 to 20 minutes |
| Ethereum Sepolia | not measured yet |
The rail0 contract is deployed on more chains than the gateway serves; see Chains for the full list.
What the gateway does not do
Section titled “What the gateway does not do”- Hold funds or keys. The contract holds the escrow; the wallets hold the keys.
- Act on its own. Every transaction that moves money is signed by the merchant or the buyer; the gateway only prepares, sends and watches.
- Mirror what it did not prepare. Every rail0 operation can also be sent to the contract directly by the party it allows. That works on-chain, but the gateway does not apply it: the payment keeps its previous status here and no webhook fires. Operate through the gateway, or not at all, per payment.
Base URL and versioning
Section titled “Base URL and versioning”Every endpoint lives at https://api.rail0.xyz; there is nothing to configure. The
unversioned routes are v1 and are frozen: a breaking change ships as a separate /v2/…
surface alongside them, so v1 clients keep working.
rail0 is a peer-to-peer protocol: buyer and merchant transact directly, with no processor, gateway, or operator in between. The contract custodies nothing outside the active escrow window, takes no fee, and routes every captured token to the merchant in full. It is immutable and permissionless — no owner, no admin, no upgrade path, no privileged roles, and no arbitration layer; recourse is purely time-based (capture, void, release, refund). No external audit has been completed yet — formal audits are underway and their reports will be published here once available. Until then, review the contract and assess your own risk before use.
