Skip to main content
An onramp converts fiat held in a customer’s virtual account into a crypto asset. It uses POST /v2/orders. The source is always a virtual account. The direction is inferred from the asset types, so you do not send a type.
Test this flow in sandbox. See ONRAMP orders (sandbox) for the simulated happy path, failure controls and webhooks.

​
Prerequisites

  • An active customer with a virtual account that holds the fiat to convert (Add virtual accounts).
  • For a Conduit wallet destination, an active wallet for the asset and chain you want (Add a crypto wallet). For an external wallet, nothing: the customer needs no Conduit wallet and signs nothing.
  • A customer outside the United States. On live, an onramp for a customer in the United States returns 403 CAPABILITY_SUSPENDED; sandbox does not apply this refusal (Customers in the United States).
  • Your API key.

​
Choose the destination

​
Send to a Conduit wallet

​
Send to a wallet outside Conduit

  • recipient is the crypto recipient of POST /v2/payouts. recipient.chain must equal asset.chain.
  • attestation.custody is required. Use self when the customer owns and controls the wallet. An account the customer holds at an exchange or custodian is not self: see Send to or fund from an account at a custodian. For a wallet that belongs to someone else, use third_party and add the owner’s identity: type, plus firstName, lastName and countryOfCitizenship, or legalName and countryOfRegistration.
  • purpose and documents follow the same rules as a payout (Transact). A purpose of intercompany or personal_transfer_of_funds needs the address registered first (Registered Addresses).
  • autoPayout and sourceAsset are refused with an external_wallet destination.
  • To see the recipient fields before you build the request, call GET /v2/orders/requirements with recipientRail=crypto and the destination asset and chain.
The order creates two transactions: an onramp transaction, then a withdrawal to the address, linked to the order by linkedOrderId. The withdrawal is screened like any crypto payout and cannot be cancelled once it exists.

​
How much the order debits

On a source-locked order, totalDebit equals amount: the fees come out of it, and the rest converts. On a destination-locked order, amount is what the customer receives, and totalDebit is the principal plus fees (How much an order debits). To convert a deposit in full, lock the source side and set amount to the deposit’s destination.assetAmount. That is the amount credited to the virtual account, after any deposit fee, and not the amount the sender wired. An order sized at the wired amount is short once a deposit fee applies, so it never executes (Charge a fee on a deposit).

​
Conversion partners

Some onramps settle through a conversion partner. The partner converts at its rate when the USD arrives, so the order’s destination amount is an estimate. The USDC reaches the customer’s wallet as a deposit transaction with the exact amount. A partner delivers to the customer’s own wallet, or to an external_wallet whose recipient.attestation.custody is self. An onramp to an external_wallet that a third party holds converts on Conduit. See Convert for the partner’s fees and your margin.

​
Track the order

The order stays pending until it reaches succeeded, failed or cancelled. Watch the order.* and transaction.* webhooks (Webhooks). With an external_wallet destination, the order stays pending after the conversion settles. Conduit then sends the crypto to the address, and the order becomes succeeded only when that send is final on chain, usually a few minutes later. executedAt is set and order.succeeded fires at that time. payoutTxHash on the order, and on order.succeeded, carries the on-chain hash of the send. When a conversion partner delivers to the address, it is the hash of the partner’s transfer. It is null until delivery and on every other order. txHash keeps its meaning: the hash of the conversion’s chain leg. If Conduit cannot make the send and returns the crypto, the order becomes failed and order.failed fires. Use autoExecute: false to lock a rate and read the quote without committing, and cancel before execution with POST /v2/orders/{orderId}/cancel.

​
See also