On-ramps and off-ramps

Not in the preview yet. This feature is built in the repository but is off in the v2.2.6 preview (test mode). Do not treat this page as available on a preview core. See ../preview.md and the release notes.

Status: Preview on a mock. Operator mode on a real account is Release-gated.

A ramp moves value between bank money and stablecoin. An on-ramp funds a stablecoin budget; an off-ramp pays a payee out to its own bank account. Circle is the only ramp adapter built.

Two modes

ModeWho holds the provider accountStatus
own-account (default)each party uses its own provider account, client-side; the core holds no provider key and checks every movement on chain before it records a creditPreview
operatorthe deployment's own provider account, sandbox onlyRelease-gated for live use

The interface

A ramp adapter quotes fees from a fee table (no network call), and runs on-ramps, pay-ins and off-ramps, each under an idempotency key so a retry never makes a second transfer. The fee table carries a version, an as-of date and a source; an unknown fee is refused, never guessed.

Behaviour

budget's root funder. A pending, failed or mismatched order credits nothing. The core never moves the delivered stablecoin into escrow: the funder's own key does.

named in a request, and a payout plus its fees never exceeds what the payee paid in.

Routes

is confirmed

GET /payee/v1/offramps/{id} - the payee's off-ramp

Switches

SwitchDefaultNotes
CORE_RAMPSoffcircle turns ramps on; needs the stablecoin mode
CORE_RAMPS_MODEown-accountor operator
CORE_RAMPS_CIRCLE_FEESnonerequired: the fee table
CORE_RAMPS_CIRCLE_CHAINBASEthe chain the provider delivers on
CORE_RAMPS_MIN_CONFIRMATIONS21 to 64 blocks
CORE_RAMPS_CIRCLE_API_KEY, CORE_RAMPS_CIRCLE_WALLET_IDnoneoperator mode only, sandbox key only; refused in own-account mode

A live Circle key in any variable refuses to start the core (ramp_live_key), whether ramps are on or off.

Test suite

make test-ramps - off by default, live keys refused, both modes on an offline Circle Mint mock with a local chain, credit only on completion, one fee row per fee, the bank destination rule and the payout bound, tenants isolated.

Mocks today, partner access later

Circle runs on an offline mock. Operator mode against Circle's sandbox needs a sandbox account; live use waits for the release gate.

Certification steps

  1. make test-ramps green with the adapter.
  2. Every provider call idempotent.
  3. An unknown fee refused; a payout above its pay-in refused.
  4. A live key refused at start.