Skip to main content
Rails moves value through a small number of explicit settlement steps. The point is to make every transition observable and easy to debug.

​
Lifecycle

  1. A B2B integrator requests access.
  2. Rails issues an API key manually.
  3. The integrator creates an offramp order.
  4. Rails settles the value on Sui.
  5. The configured payout route completes local fiat payout.

​
First principles

  • Stablecoins enter the system.
  • Settlement is executed on Sui, or directly on an EVM chain.
  • Route A is the configured B2B route.
  • Local fiat payout completes through the selected route.

​
Two settlement paths

Rails supports two kinds of source network, chosen by the order you create:
  • Sui — Rails’ own full Gateway layer. Rails settles the deposit and drives the lifecycle. Use Create Order.
  • EVM & Starknet (base, polygon, arbitrum-one, starknet, …) — settled directly against the settlement aggregator’s on-chain Gateway. Rails is non-custodial: it never holds keys or funds. It assembles the createOrder parameters, your wallet submits the transaction, and Rails polls status and webhooks you. Use Create Order — EVM & Starknet then Submit On-chain Order.
The network you pass to POST /v1/sender/orders selects the path — one endpoint for all chains.

​
Non-custodial (EVM / Starknet) order lifecycle

  1. POST /v1/sender/orders with an EVM/Starknet network → Rails returns unsigned createOrder params and an orderRef.
  2. Your wallet approve()s the Gateway and calls createOrder(...).
  3. POST /v1/sender/orders/{id}/submitted with the on-chain orderId.
  4. Rails polls the settlement aggregator and webhooks you on settled / refunded / expired.
Refunds always return to the returnAddress that created the order.

​
Failure modes

  • Quote expires before payment
  • Fiat payout does not complete
  • Route times out
  • A retry must be issued

​
What to expect from the app layer

Your application should treat settlement as a state machine, not a single request/response call. That means you should handle:
  • pending
  • quoted
  • created
  • settling
  • settled
  • failed
  • expired