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
| Mode | Who holds the provider account | Status |
|---|---|---|
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 credit | Preview |
operator | the deployment's own provider account, sandbox only | Release-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
- An on-ramp funds only a stablecoin budget and delivers only to that
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.
- An off-ramp pays only the payee's onboarded bank destination, never one
named in a request, and a payout plus its fees never exceeds what the payee paid in.
Routes
GET /owner/v1/ramps- the switch state, mode and fee tablePOST /owner/v1/ramps/quotes- the fees for an on-ramp, before anything
is confirmed
POST /owner/v1/ramps/onramps- confirm a quoteGET /owner/v1/ramps/onramps/{id}- one on-rampPOST /payee/v1/offramps/quotes,POST /payee/v1/offramps,
GET /payee/v1/offramps/{id} - the payee's off-ramp
Switches
| Switch | Default | Notes |
|---|---|---|
CORE_RAMPS | off | circle turns ramps on; needs the stablecoin mode |
CORE_RAMPS_MODE | own-account | or operator |
CORE_RAMPS_CIRCLE_FEES | none | required: the fee table |
CORE_RAMPS_CIRCLE_CHAIN | BASE | the chain the provider delivers on |
CORE_RAMPS_MIN_CONFIRMATIONS | 2 | 1 to 64 blocks |
CORE_RAMPS_CIRCLE_API_KEY, CORE_RAMPS_CIRCLE_WALLET_ID | none | operator 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
make test-rampsgreen with the adapter.- Every provider call idempotent.
- An unknown fee refused; a payout above its pay-in refused.
- A live key refused at start.