Autoramp

An Autoramp is a standing conversion rule. Funds that arrive at the Autoramp’s deposit details are converted into the destination asset and delivered to a recipient you registered, for as long as the Autoramp is live. Create one with POST /api/autoramps and read it with GET /api/autoramps/{autoramp_id}. In the Partner Dashboard, Autoramps live on the Routes page: it’s the only place that calls them routes.

How an Autoramp works

Take a EUR Autoramp that delivers EURC on Base to your customer’s wallet:

You create it

Call POST /api/autoramps with EUR in source_currencies, EURC on Base as destination_currency, the customer’s registered wallet in recipient_account, and the customer_id. The response comes back Authorized, with kind: "Onramp" and an empty deposit_rails. See Create an Autoramp.

The bank opens the account

MoonPay Enterprise opens an IBAN in your customer’s name. The Autoramp moves to DepositAccountAdded, then Approved, and register_autoramp_status fires at each step. Once it’s Approved, deposit_rails holds the IBAN, the BIC, and the beneficiary name. See Autoramp Status.

Your customer pays in

They send €1,000 by SEPA from their bank app. MoonPay Enterprise creates a transaction for the payment and sends a transaction webhook. You don’t make any call per deposit.

It converts and delivers

The transaction moves through ConversionInProgress and PayoutInProgress to Completed, with a transaction_status webhook at each step. The EUR converts at the market rate at that moment, and the EURC lands in the wallet. transaction_hash holds the on-chain hash. See Fees and Transaction Status.

The Autoramp stays live after that. Every later payment to the same IBAN goes through the same steps, until you edit or cancel the Autoramp. An offramp runs the other way: your customer gets a deposit address, and stablecoins sent to it pay out to a registered bank account.

Autoramp kinds

Each kind matches a card on the Partner Dashboard’s Routes page:

`kind`	Routes card	What your customer gets	Guide
`Onramp`	Onramp	A named bank account. Fiat deposits settle as stablecoins in a wallet	Virtual accounts
`Offramp`	Offramp	A deposit address. Stablecoin deposits settle as fiat in a registered bank account	Payouts
`Swap`	Stable to Stable	A deposit address. One stablecoin settles as another, on the same chain or across chains	Stable to Stable Autoramp
`Mint`, `Redeem`	Mint / Redeem	Mint PYUSDx from PYUSD, or redeem it back	Mint, redeem, and swap

You don’t send kind. The API derives it from the currencies when you create the Autoramp, and it never changes afterwards:

Mint: the destination is an issuance token, such as PYUSDx
Redeem: a source is an issuance token
Onramp: the source is fiat
Offramp: the destination is fiat
Swap: crypto in, crypto out

The rules apply in that order, so a fiat source with an issuance-token destination is a Mint, not an Onramp. A fiat-to-fiat Autoramp returns 400 with "Fiat to fiat autoramps are not allowed".

Onramp Autoramp

Gives your customer a bank account in their own name, in USD, EUR, GBP, or BRL. Fiat sent to it becomes stablecoins in their wallet. See Virtual accounts for eligibility, deposit details per currency, and third-party payments.

Offramp Autoramp

Gives your customer a deposit address. Stablecoins sent to it pay out as fiat to a bank account you registered. See Payouts for bank account registration, exact-out quotes, and payout rails per currency.

Stable to Stable Autoramp

Gives your customer a deposit address that turns one stablecoin into another, on the same chain or across chains. For example, USDC sent on Solana arrives as EURC on Base. The recipient wallet must be on the destination chain. Stellar works only as an onramp destination, so it’s not available here.

Create a Stable to Stable Autoramp

curl -X POST "https://api.sandbox.iron.xyz/api/autoramps" \
  -H "Content-Type: application/json; charset=utf-8" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "X-API-Key: <your-api-key>" \
  -d '{
    "source_currencies": [{ "type": "Crypto", "token": "USDC", "blockchain": "Solana" }],
    "destination_currency": { "type": "Crypto", "token": "EURC", "blockchain": "Base" },
    "recipient_account": {
      "type": "Crypto",
      "chain": "Base",
      "address": "0xaf77d065e77c8cC2239327C5EDb3A432268e5831"
    },
    "customer_id": "123e4567-e89b-12d3-a456-426614174000"
  }'

201 Created

{
  "id": "d4e3c2b1-a9f8-7654-3210-fedcba987654",
  "customer_id": "123e4567-e89b-12d3-a456-426614174000",
  "status": "Authorized",
  "kind": "Swap",
  "source": "Standalone",
  "source_currencies": [{ "type": "Crypto", "token": "USDC", "blockchain": "Solana" }],
  "destination_currency": { "type": "Crypto", "token": "EURC", "blockchain": "Base" },
  "recipient": {
    "type": "Wallet",
    "blockchain": "Base",
    "address": "0xaf77d065e77c8cC2239327C5EDb3A432268e5831"
  },
  "is_third_party": false,
  "batch_payout": false,
  "fee_profile_id": "9b2e7c14-5f3a-4d8b-b1c6-2a4e6f8d0c12",
  "deposit_rails": [],
  "created_at": "2026-01-20T14:23:45Z"
}

The request names the chain chain inside recipient_account. The response returns the same value as blockchain inside recipient.

See Stablecoins and Blockchains for the tokens and chains you can use on each side.

Standing or quote-based

Every Autoramp is one of two types, shown in its source field.

	Standing (`Standalone`)	Quote-based (`Quote`)
Rate	Current market rate when the deposit is processed	Locked by a signed quote
Deposit amount	Any amount	Must equal a quote’s `amount_in`
Created with	Currencies and a recipient	A signed quote from `GET /api/autoramps/quote`
Later quotes	Can’t take quotes	Attach new quotes with `POST /api/autoramps/{autoramp_id}/quotes`
Best for	Deposits of unknown size, sweeping balances	Invoices, payroll, an exact payout amount

A standing Autoramp can never become quote-based. If you need locked rates later, create a quote-based Autoramp. See Quotes.

Before you create an Autoramp

The customer is Active

The customer’s status is Active: terms signed, identification approved, and nothing outstanding in GET /api/customers/{customer_id}/required-signings. Otherwise POST /api/autoramps returns 403 with "Customer is not active". See Onboarding.

The rail is Active for this customer

An Active customer can still be waiting on a specific rail. Read GET /api/customers/{customer_id}/abilities and create the Autoramp only once its rail reads Active. A rail that isn’t Active yet returns 422 with "Customer is unable to complete the action. Consult the customer abilities API". Subscribe to the customer_fiat_abilities webhook instead of polling. See Ability Status.

The recipient is registered

Register the wallet or bank account that receives the converted funds before you create the Autoramp, and pass the same details in recipient_account:

Wallet: see Crypto Addresses. An unknown wallet returns 400 with "Recipient wallet not verified for customer".
Bank account: see Fiat Addresses. It must reach Registered. An account that isn’t registered yet returns 400 with "recipient fiat account not verified".

How many Autoramps a customer can have

Onramp Autoramps: up to 10 per customer, counting every Autoramp that isn’t Cancelled or Rejected. An Autoramp waiting on an edit, or a dormant quote-based Autoramp, still counts. The 11th returns 400 with "Customer has reached the maximum number of onramps. Please cancel existing onramps before creating a new one." Contact the MoonPay Enterprise team to raise the limit for a customer. Sandbox doesn’t enforce it.
Offramp, Stable to Stable, Mint, and Redeem Autoramps: don’t count toward the limit. A Mint Autoramp with a fiat source is still refused with the same error once the customer has reached it.
BRL (PIX) onramp Autoramps: one per customer.

Check before you create with GET /api/autoramps/check-limit, passing customer_id, deposit_account_type (for example Iban, AchWire, ChapsFps, Pix, or Wallet), and is_third_party. The response is { "can_create": true } or false. A customer can hold several Autoramps for the same source asset, each with its own destination. For example, one EUR Autoramp that delivers USDC on Solana and another that delivers EURC on Base. Each gets its own virtual account or deposit address, unless you use pay by reference.

Create an Autoramp

Dashboard
API

Open Routes

Switch to the App view, pick your customer in View As, and open Operations → Routes.

Pick a card

Click the create button on the Onramp, Offramp, or Stable to Stable card.

Fill in the Autoramp

Choose the source and destination assets and the registered wallet or bank account that receives the output. The fee profile sits under Advanced options.

Copy the deposit details

Once the Autoramp is Approved, open it and click Deliver Funds to see the bank details or deposit address.

POST /api/autoramps

curl -X POST "https://api.sandbox.iron.xyz/api/autoramps" \
  -H "Content-Type: application/json; charset=utf-8" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "X-API-Key: <your-api-key>" \
  -d '{
    "source_currencies": [{ "type": "Fiat", "code": "EUR" }],
    "destination_currency": { "type": "Crypto", "token": "USDC", "blockchain": "Solana" },
    "recipient_account": {
      "type": "Crypto",
      "chain": "Solana",
      "address": "3DkNYk8xJ9xGd1WsKZz8kG3n3QNB4f4pJ3m5mYxBV4Lm"
    },
    "customer_id": "123e4567-e89b-12d3-a456-426614174000"
  }'

201 Created

{
  "id": "f8f9a8c7-d8b1-4f1a-8f15-7e6c8a1a8e50",
  "status": "Authorized",
  "kind": "Onramp",
  "source": "Standalone",
  "deposit_rails": [],
  "created_at": "2026-01-20T12:34:56Z"
}

The response is trimmed. Poll GET /api/autoramps/{autoramp_id} or listen for the register_autoramp_status webhook until status is Approved, then read deposit_rails.

POST /api/autoramps requires an Idempotency-Key header. A missing key returns 400. Only successful responses are cached, so a retry after an error runs again. See Idempotency.

Request fields

Field	Required	Description
`customer_id`	Yes	The customer who owns the Autoramp
`source_currencies`	Yes	One fiat currency, or one or more crypto currencies. Fiat and crypto can’t be mixed
`destination_currency`	Yes	The asset the Autoramp delivers
`recipient_account`	Yes	The registered wallet (`Crypto`), bank account (`Fiat`), or PIX address (`Pix`) that receives the output
`name`	No	Your label for the Autoramp
`external_id`	No	Your own ID for the Autoramp
`source_is_third_party`	No	Onramp Autoramps only. Accept deposits from senders other than the customer. See Virtual accounts
`fee_profile_id`	No	The transactional fee profile to apply. See Fees
`pay_by_reference`	No	Share one virtual account across Autoramps. See Pay by reference
`batch_payout`	No	Fiat destinations only. Pay out once a day instead of per deposit. See End of Day Settlement
`sepa_payment_reference`, `ach_payment_reference`, `fps_payment_reference`, `wire_message`, `swift_payment_reference`, `swift_purpose_code`	No	Offramp Autoramps only. The reference sent with each payout, for the recipient’s rail. See Payouts

On a quote-based Autoramp, the signed quote already carries external_id, fee_profile_id, batch_payout, pay_by_reference, swift_purpose_code, and the payout reference fields. Set them on GET /api/autoramps/quote. Adding any of them to POST /api/autoramps changes the signed payload and returns 400 with "Invalid signature".

Errors

Client errors return a plain string body. The ones partners hit most:

Status	Body	Fix
`400`	`"Recipient wallet not verified for customer"`	Register the wallet for this customer first. See Crypto Addresses
`400`	`"recipient fiat account not verified"`	The bank account must be `Registered`, not `RegistrationPending`. See Fiat Addresses
`400`	`"Missing Idempotency-Key header"`	Send an `Idempotency-Key`
`403`	`"Customer is not active"`	Finish onboarding. See Onboarding
`422`	`"Customer is unable to complete the action. Consult the customer abilities API"`	The rail isn’t `Active` for this customer yet. Check `GET /api/customers/{customer_id}/abilities`

422 Unprocessable Entity

"Customer is unable to complete the action. Consult the customer abilities API"

Lifecycle

A new Autoramp starts in Authorized while MoonPay Enterprise provisions its deposit account. It moves to DepositAccountAdded when the account is attached, and to Approved once the account is verified. Share deposit details only at Approved.

Status	What it means for you
`Authorized`	Created. Deposit account not ready, `deposit_rails` is empty
`DepositAccountAdded`	Account attached but not verified. Don’t share it yet
`Approved`	Live. Deposits convert
`EditPending`	A sensitive edit is waiting for your customer to confirm it. Deposits don’t convert
`Rejected`	Provisioning failed or a check failed. Terminal
`Cancelled`	Cancelled, or a quote-based Autoramp with no live quote

Approved is the steady state of a working Autoramp: it stays there until it’s edited or cancelled. See Autoramp Status for what triggers each status, including why an Autoramp stays at Authorized.

Pay by reference

Set pay_by_reference: true on POST /api/autoramps, with standard parameters or a signed quote, to share one virtual account across several Autoramps for the same customer. Each Autoramp returns an inbound_payment_reference of the form IR-XXXXXX. Senders must include it on every transfer so the deposit reaches the right Autoramp. Pay by reference works when all of these hold:

Kind: Onramp or Mint
Source: a fiat currency on a EUR (Iban), USD (AchWire), or GBP (ChapsFps) virtual account. BRL (Pix) Autoramps don’t support it

A pay-by-reference account only accepts deposits that carry a matching reference. A deposit without one is returned to the sender, with the USD ACH exception below. Autoramps with and without pay by reference never share an account: a new pay-by-reference Autoramp gets a fresh account or joins another pay-by-reference account for the same customer. An Autoramp that joins an existing account starts at Approved, with deposit_rails filled in.

Edit an Autoramp

PATCH /api/autoramps/{autoramp_id} changes an Approved standing Autoramp. Send the customer_id that owns it, plus any of these fields:

Field	What it changes
`recipient_account`	Where converted funds go: a registered wallet or bank account
`destination_currency`	The currency the Autoramp converts into
`fee_profile_id`	The transactional fee profile applied to each conversion

A Mint Autoramp can only change to another mint token, and a Redeem Autoramp only to another fiat currency. Everything else is fixed when you create the Autoramp: the source currencies, payment references, swift_purpose_code, pay_by_reference, source_is_third_party, and batch_payout. To change any of them, cancel the Autoramp and create a new one. To change the rate on a quote-based Autoramp, attach a new quote instead.

A standing Autoramp is also called a market Autoramp. You’ll see the term here: the operation is patchAutorampMarketById, its body is PatchAutorampMarketParameters, and a quote-based Autoramp returns "Only Autoramp market can be patched". Market means the same as source: Standalone. The optional type field on POST /api/autoramps uses it too: "market" for a standing Autoramp, "quote" for a signed quote.

Some Autoramps can’t be edited. Each case returns 400 with its own plain string body:

Autoramp	Response body
Batch payout	`"batch payout autoramps are immutable"`
Any status other than `Approved`	`"Autoramp is not approved"`
Created from a signed quote	`"Only Autoramp market can be patched"`

Email confirmation (2FA)

All three fields decide where your customer’s money goes and what it costs them, so every change to them is a sensitive edit. By default, a sensitive edit moves the Autoramp to EditPending and emails your customer a confirmation link and a 6-digit code. The code expires after 10 minutes. The change takes effect once they confirm, and the Autoramp returns to Approved.

Deposits that arrive while an Autoramp is EditPending don’t match it and are returned to the sender, the same as deposits to a cancelled Autoramp. Make edits when you don’t expect funds, or ask your customer to confirm right away.

2FA is on by default for every partner. MoonPay Enterprise can turn it off for your account after reviewing your integration, to confirm that your customers always approve fee and beneficiary changes in your product, and that you show those changes to them correctly. With 2FA off, edits apply immediately and the Autoramp stays Approved. Contact the MoonPay Enterprise team to request a review.

Confirm the code in your app

If your customer clicks the link in the email, nothing else is needed. If they enter the code in your app instead, submit it in two calls.

Get the pending code for the entity. Pass the Autoramp’s ID, not a code ID:
curl -X GET "https://api.sandbox.iron.xyz/api/authentication-codes/entity/{autoramp_id}" \ -H "X-API-Key: $API_KEY"
The response carries the code’s id, its status, attempts, and expires_at. It returns 404 when no code is pending because it expired or was already confirmed.
Submit the code against that id:
curl -X PUT "https://api.sandbox.iron.xyz/api/authentication-codes/{auth_code_id}" \ -H "Content-Type: application/json" \ -H "X-API-Key: $API_KEY" \ -d '{ "code": 123456 }'
code is an integer. A string such as "123456" fails validation. Act on the status in the response:
- Confirmed: the edit is applied.
- Pending: the code was wrong and attempts went up by one. Ask your customer to try again. After three wrong codes, the next submission returns Rejected, even with the right code.
- Rejected or Expired: the pending edit is reverted and the Autoramp keeps its previous settings. Make the edit again to send a new code.

In sandbox, the static code 123456 confirms any pending code. Both endpoints accept an optional X-SUB-PARTNER-ID header to scope the lookup to a sub-partner. POST /api/autoramps/{autoramp_id}/retry-auth always returns 404 with "This endpoint is no longer supported."

Cancel an Autoramp

DELETE /api/autoramps/{autoramp_id} returns 204 and moves the Autoramp to Cancelled. Its deposit_rails empties, and deposits sent to its old details are returned to the sender while no other Autoramp uses them. A EUR or GBP account left idle by a cancelled Autoramp can be reused for the customer’s next Autoramp in that currency, and deposits to it then convert on the new Autoramp.

Some USD accounts don’t return an ACH deposit automatically when it matches no live Autoramp. This covers a cancelled Autoramp, an Autoramp in EditPending, and a pay-by-reference deposit without a matching reference. If an ACH deposit doesn’t come back, contact the MoonPay Enterprise team to recover the funds.

Cancelling is permanent. To accept funds again, create a new Autoramp. No webhook fires for a cancel you make yourself, so update your records from the 204.

MoonPay Enterprise also cancels Autoramps on its own in three cases, and sends a register_autoramp_status webhook for each:

MoonPay Enterprise support cancels the Autoramp
The customer is archived
The Autoramp’s recipient wallet is disabled. Disabling a wallet fires no webhook of its own: only its cancelled Autoramps report it. See Disable or enable an address

Fees

Each Autoramp carries one transactional fee profile. Pass fee_profile_id when you create the Autoramp, or leave it out: the most specific profile that matches the Autoramp applies, otherwise your default profile. Change it later with PATCH, which counts as a sensitive edit. Create and manage profiles in the dashboard under Fee Profiles. Every transaction on the Autoramp reports its fees in the source currency, in fee and fee_breakdown, with a settlement method for each:

deductedImmediately: taken from the amount before payout, so the recipient receives less
settledLater: not taken from the transfer. It appears on your monthly invoice instead

See Fees and Invoices for every fee field.

Webhooks and emails

Event	When it fires
`new_autoramp`	An Autoramp is created
`deposit_address_created`	The Autoramp’s deposit account or address is attached
`register_autoramp_status`	The Autoramp is created, gets its deposit account, is approved or rejected, has an edit applied, or is cancelled by MoonPay Enterprise
`transaction`	A deposit on the Autoramp created a transaction
`transaction_status`	That transaction moved to a new status

register_autoramp_status does not fire when you cancel an Autoramp, when an Autoramp enters EditPending, when a pending edit is reverted, or when an Autoramp is rejected because the bank failed to open or closed its account. Read the Autoramp with GET /api/autoramps/{autoramp_id} after those actions. See Webhooks. Your customer receives an email when a standing Autoramp is approved, and when an Autoramp is rejected. Quote-based Autoramps don’t send the approval email. MoonPay Enterprise can turn the Autoramp email off for your account if your product shows your customer the same account details. Contact the MoonPay Enterprise team.

Virtual accounts

Onramp Autoramps: named bank accounts that settle into stablecoins

Payouts

Offramp Autoramps: stablecoins to a bank account

Quotes

Lock a rate, and attach new quotes to a running Autoramp

Autoramp Status

Every status an Autoramp moves through, and what triggers it

Getting Started

Coverage

Onboarding & Compliance

Virtual Accounts & Global Payouts

Issuance

Wallets

Webhooks & Events

Billing & Settlement

Support

How an Autoramp works

Autoramp kinds

Onramp Autoramp

Offramp Autoramp

Stable to Stable Autoramp

Standing or quote-based

Before you create an Autoramp

How many Autoramps a customer can have

Create an Autoramp

Request fields

Errors

Lifecycle

Pay by reference

Edit an Autoramp

Email confirmation (2FA)

Cancel an Autoramp

Fees

Webhooks and emails

What to read next

Virtual accounts

Payouts

Quotes

Autoramp Status

​How an Autoramp works

​Autoramp kinds

​Onramp Autoramp

​Offramp Autoramp

​Stable to Stable Autoramp

​Standing or quote-based

​Before you create an Autoramp

​How many Autoramps a customer can have

​Create an Autoramp

​Request fields

​Errors

​Lifecycle

​Pay by reference

​Edit an Autoramp

​Email confirmation (2FA)

​Cancel an Autoramp

​Fees

​Webhooks and emails

​What to read next

Virtual accounts

Payouts

Quotes

Autoramp Status

How an Autoramp works

Autoramp kinds

Onramp Autoramp

Offramp Autoramp

Stable to Stable Autoramp

Standing or quote-based

Before you create an Autoramp

How many Autoramps a customer can have

Create an Autoramp

Request fields

Errors

Lifecycle

Pay by reference

Edit an Autoramp

Email confirmation (2FA)

Cancel an Autoramp

Fees

Webhooks and emails

What to read next