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.

A ramp turns money from outside into a budget's funding (the on-ramp), or pays a payee out to a bank account (the off-ramp). This release has one ramp interface and one adapter, for Circle. Ramps are off by default. In operator mode the core talks only to Circle's sandbox; in own-account mode the core holds no Circle key and only verifies the stablecoin movement on chain. The tests run against offline mocks.

Status: Preview. Operator mode with a live Circle key is Release-gated.

Two modes

own-account (default)operator
Whose Circle accountthe funding party's own, or the payee's ownthe deployment operator's
Who holds the Circle keythat party, client-side (your own code, the payee kit or a browser). Dynamo never receives itthe core, in memory
What Dynamo doesrecords the ramp only after it verifies the stablecoin movement on chain; it moves nothingsends the payout from the operator's sandbox account
Live useyour own account, your own key; release-gated (real money needs a stablecoin mode on a public chain, which the operator must allow, with Safe vault roles)release-gated: a live key refuses boot (ramp_live_key)

The release gate for operator mode. In operator mode, money passes through the operator's own Circle account on its way to someone else. With a live key that would be holding another party's money. Operator mode therefore runs on Circle's sandbox only, and stays sandbox-only until the founder's release gate opens. Until then any LIVE_API_KEY key in any variable refuses boot.

GET /owner/v1/ramps reports the mode, whether each direction is available (and if not, why), and under custody whether the core holds a key and whether live use is client-side or release-gated.

The on-ramp

The on-ramp funds an active stablecoin budget. The stablecoin goes to the budget's root funder (the address that funded the budget). A request cannot name another destination. Your own wallet then moves the stablecoin into the budget, so budget headroom grows only when your own top-up lands. Dynamo never holds your wallet key.

POST /owner/v1/ramps/quotes     {budgetId, amountMicroUsd}
  → {quoteId, mode, deliverTo, amountMicroUsd, fees, totalChargeMicroUsd, expiresAt, …}
POST /owner/v1/ramps/onramps    {quoteId, idempotencyKey (UUID v4), acceptFeeMicroUsd[, deliveryTxHash]}
GET  /owner/v1/ramps/onramps/:id

Amounts are integer micro-USD strings in whole cents. acceptFeeMicroUsd must equal the quote's fees.totalFeeMicroUsd, the fee you were shown. A quote lasts 600 seconds. Retrying with the same idempotency key and quote answers the same order (duplicate: true). The scheduler keeps advancing pending orders.

Own-account. Pay the quote from your own Circle account: send a stablecoin payout of amountMicroUsd to deliverTo on the quote's chain. Then confirm with that payout's transaction hash as deliveryTxHash. Dynamo reads the transaction and refuses it (ramp_delivery_unverified, nothing recorded) unless it holds exactly the quoted amount of the budget's stablecoin sent to the root funder. A transaction already behind another ramp record is refused (ramp_tx_reused). The order is credited once the transaction is minConfirmations blocks deep (CORE_RAMPS_MIN_CONFIRMATIONS, default 2). Circle charges its fees to your own account, so no fee passes through Dynamo and the order has no fee rows.

Operator. Confirming sends the payout from the operator's sandbox account. The order is recorded before Circle is called. It is credited only when Circle reports the payout complete, with the quoted amount and no more than the quoted fees, and each fee is then its own row. A pending, failed or mismatched order (state: "mismatch") credits nothing.

The off-ramp

The off-ramp pays a payee out. It never pays out more than the stablecoin the payee paid in. In operator mode the payout goes only to the payee's onboarded wire destination; in own-account mode your own Circle account pays out to your own bank account and Dynamo stores no wire destination. Any destination field in a request is refused (400). The payee authenticates as itself. Onboarding the wire destination and starting an off-ramp take only the payee's own Dynamo-Payee v2 proof for that request (how to sign one); a payee credential there answers 403 credential_scope. Quotes and status reads also take the payee credential.

In operator mode, first onboard the destination. It holds only Circle's bank-account id:

POST /payee/v1/destinations   {rail: "wire", bankAccountId}

Circle must report the bank account complete in the operator's account; a destination no provider has checked is never verified and no payout routes to it. In own-account mode the request answers 409 wire_own_account: your own Circle account holds your bank account, and Dynamo stores none. The wire rail is served only while ramps are on.

Own-account. Use your own Circle account and key, client-side:

  1. Get a deposit address for your own Circle wallet.
  2. Send your stablecoin there from your serviceNode's own key.
  3. Once your account shows the deposit, request a bank payout of at most that

amount to a bank account in your own Circle account (OwnAccountOffRamp.payout(payin, amount, bankAccountId) in @dynamoprotocol/payee-kit/ramps).

  1. Report it:
POST /payee/v1/offramps   {idempotencyKey, payinTxHash, depositAddress, payoutMicroUsd[, providerPayoutId]}

Dynamo checks that the chain shows your own address sending the stablecoin to depositAddress in payinTxHash, and that payoutMicroUsd is no larger than that amount (ramp_payout_exceeds_payin otherwise). It records the off-ramp once the payin is deep enough, with destination: null, and it moves nothing.

Operator (sandbox only).

POST /payee/v1/offramps/quotes   {payinMicroUsd}
  → {quoteId, destination: {rail: "wire", bankAccountId}, payinMicroUsd, fees, payoutMicroUsd, expiresAt}
POST /payee/v1/offramps          {quoteId, idempotencyKey, acceptFeeMicroUsd}
  → 202 {offrampId, depositAddress, state: "pending", …}
GET  /payee/v1/offramps/:id

Pay in payinMicroUsd from your own key to depositAddress (a Circle payment intent in the operator's account). Dynamo requests the payout of payoutMicroUsd (the payin less the fees) only after Circle reports the payin complete, and only if the payout plus the fees fits inside what Circle received. It pays only to the destination onboarded when you were quoted. Each fee is its own row.

Turn it on (operators)

VariableMeaning
CORE_RAMPSoff (default) or circle
CORE_RAMPS_MODEown-account (default) or operator
CORE_RAMPS_CIRCLE_FEESthe fee table, JSON: version, asOf, source, onrampFeeMicroUsd, offrampFeeMicroUsd, networkFeeMicroUsd. Required: an unknown fee is never guessed
CORE_RAMPS_CIRCLE_CHAINthe chain code the stablecoin moves on (default BASE)
CORE_RAMPS_MIN_CONFIRMATIONSblocks a delivery or payin must be under before it is recorded (1-64, default 2)
CORE_RAMPS_CIRCLE_API_KEYoperator mode only: a Circle sandbox key, TEST_API_KEY:<id>:<secret>. Set under own-account mode, it refuses boot
CORE_RAMPS_CIRCLE_WALLET_IDoperator mode only: the Circle Mint wallet the payouts draw on

The deployment needs the stablecoin mode: ramps move stablecoin and are checked on its chain. On the multi-tenant tier the ramp serves test-environment tenants only. A key is never logged or stored.

In the console, People and payments shows the ramp switch and its mode. Fund a budget offers "Ramp" when the on-ramp is available.

Known limits

payout plus fees pays nothing out (state: "mismatch"). So does a payout that fails after the payin, or a destination that changes in between. The payin then stays in the operator's sandbox account and is returned by hand. An overpaid payin pays out only the quoted payout.

records the payout you report, bounded by the payin it verified, but it does not confirm that the payout reached your bank.

stablecoin and credit card rails only.

Errors

ramps_off, ramp_unavailable, ramp_budget_unfundable, ramp_quote_expired, ramp_fee_not_accepted, ramp_idempotency_conflict, ramp_delivery_unverified, ramp_tx_reused, ramp_payout_exceeds_payin, ramp_destination_missing, ramp_wrong_mode.