API reference
API reference
The rail0 Gateway API (v1) is a REST API over HTTPS, JSON in and out. Every endpoint below comes with a request in curl, TypeScript, Ruby and Go — pick a language once and every page follows it.
Setup
The samples call https://api.rail0.xyz directly; there is nothing to configure. Endpoints
that need a session read the JWT from RAIL0_TOKEN; see
Authentication.
Request amounts are human decimals ("10.50"), response amounts are token base units
("10500000"); errors always carry code, title and
detail. See Conventions & errors.
Endpoints
| Section | Endpoints | About |
|---|---|---|
| Health | 1 | Liveness/readiness. |
| Authentication | 4 | SIWE nonce + JWT issuance. |
| Blockchains & tokens | 2 | The public catalog of supported chains and the stablecoins each accepts, with each chain's rail0 deployment and measured settlement time. |
| Payment methods | 1 | Public discovery of a merchant's accepted wallet/token combinations. |
| Payments | 18 | Payment lifecycle: create, sign, prepare/submit per operation. |
| Disputes | 1 | Account-level dispute list (open and closed) across the caller's payments. |
| Accounts | 4 | Merchant accounts. Reads and updates are owner-scoped; listing and creating accounts is operator-only. |
| Wallets | 10 | Account-scoped wallet and wallet-token management. |
| Webhooks | 11 | Outgoing webhook subscriptions and delivery attempts. |
| Analytics | 3 | Merchant-account sales analytics over the account's payments (as payee). Amounts are token base units. |
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.
