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
(
OnRamporOffRamp), 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.