On-Ramp And Off-Ramp

On-ramp and Off-ramp are first-class compound operation families. An on-ramp converts incoming funds into an account balance; an off-ramp converts account funds for external delivery. The source or target rail can be fiat or crypto, as specified by the request.

Session Lifecycle

Action On-ramp Off-ramp
Create POST /on-ramp-sessions POST /off-ramp-sessions
List for an account GET /on-ramp-sessions GET /off-ramp-sessions
Read current state GET /on-ramp-sessions/:id GET /off-ramp-sessions/:id
Request cancellation POST /on-ramp-sessions/:id/cancel POST /off-ramp-sessions/:id/cancel

Creation requires ramps.create, reads require ramps.read, and cancellation requires ramps.manage, with account scope coverage. List requests name account_ref. Use a stable Idempotency-Key when creating a session.

An on-ramp request carries amount, target_currency, source_rail, and account_ref, with optional destination context. An off-ramp request carries amount, target_currency, target_rail, account_ref, and the matching typed withdrawal destination.

Creation returns 201 with an operation ID and its current status. Follow the read endpoint and operation events until the operation reaches a terminal state; creation alone does not establish completed funding or payout.

Why Ramps Are Their Own Family

Ramps are not synonyms for any single primitive on the platform. The canonical model keeps them distinct from related concepts:

  • Not a pure Conversion. A conversion may be embedded as one leg inside a ramp, but a ramp also covers payment/payout method selection, settlement on the fiat side, and (optionally) a hosted initiation step. Collapsing a ramp into a conversion loses that cross-rail context.
  • Not just a deposit or a withdrawal. A direct fiat deposit or crypto withdrawal is a single-rail operation. A ramp explicitly spans both rails as one business action.
  • Not a provider checkout or session. Hosted/embedded UX surfaces (widgets, checkout URLs, session tokens) are optional delivery artifacts. The operation, not the session, is the canonical audit and status resource.

Canonical Layers

Keep these layers separate when integrating:

  • Reference availability — supported corridors: fiat currencies, crypto assets, payment methods, payout methods, countries.
  • Pricing — fee and conversion previews describe non-binding economics. The public API does not expose an executable ramp Quote resource.
  • Operation — the canonical customer-visible business action (OnRamp or OffRamp), resolved to a master or client account scope. Stable audit and status resource.
  • Settlement and outcome — what actually happened on the fiat/crypto side and what the platform recognized in the ledger. Settlement records are inputs to the operation, not its identity.

Hosted-session resources, when used, sit alongside the operation as optional initiation context — never as a substitute for it.

Composite Fees

Ramp economics are composite by nature: a single ramp can carry a payment-method fee, a payout fee, a network fee where relevant, and a conversion spread. The model keeps these breakdowns explicit so an integrator can show the end customer where each component comes from, without flattening everything into a single opaque charge.