Skip to content

On-ramp

TL;DR - An on-ramp turns inbound USD wires into stablecoin sitting at a destination wallet. Register a wallet on the customer (Crypto Accounts → Add wallet), wait for the paired crypto virtual account to go active, then share the bank coordinates from the On Ramp card on the Operations page. The customer wires USD; the upstream provider auto-converts to USDC or USDT and forwards to the wallet.

How this differs from top-up

Top-up On-ramp
Destination Customer's USD balance (fiat VA) Customer's external crypto wallet
What lands there USD USDC or USDT
Affects USD balance? Yes (credited) No (pass-through)
Conversion? None USD → stablecoin, automatic
Setup per destination None - one fiat VA per customer Register one saved wallet per (network, token) pair

Top-up is for funding the balance you'll spend on fiat payouts. On-ramp is for moving USD into a crypto address the customer controls.

Before you start

  • A customer in active status.
  • The customer's KYC must be approved by the upstream provider - the on-ramp flow refuses to register a wallet otherwise.
  • The destination wallet address, on a supported network.

Supported networks and tokens

Network Tokens
polygon USDC, USDT
solana USDC, USDT
tron USDT

Source currency is USD only. Each customer can have one wallet per (network, token) pair - the second attempt for the same combination is rejected with a duplicate error.

Step 1 - Register the destination wallet

Open the customer's dashboard and click the Crypto Accounts tab. If the customer has none yet, you'll see a notice prompting you to add the first one. Click Add wallet to open the wizard.

1a - Pick network and token

The first screen has two dropdowns: Network (polygon / solana / tron) and Token (filtered by network). Each customer can have one wallet per (network, token) pair - the modal tells you this inline.

1b - Label and address

The recap row shows the chosen network and token as read-only badges (with a Change link if you picked wrong). Then:

Field Notes
Label A friendly name shown across the dashboard (e.g. Treasury cold wallet, Phantom hot wallet). Up to 100 characters.
Wallet address The destination address on the chosen network. Validated client-side per chain.

Click Create wallet. The new wallet appears in the Crypto Accounts tab with a Provisioning badge - the upstream provider is allocating the matching crypto virtual account (see Virtual accounts).

Provisioning takes ~1–2 minutes

The wallet is created instantly in Magma, but the paired crypto VA is asynchronous. Until it transitions to active, the bank coordinates aren't available and the on-ramp can't accept funds. Refresh the page or re-open the wallet to check.

Common errors

Error What it means
409 ALREADY_EXISTS The customer already has a wallet for this (network, token). Use it, or contact support to retire it.
KYC verification required The customer's KYC isn't approved yet. Finish onboarding before retrying.
Invalid address The address didn't pass the network-specific format check.

Step 2 - Wait for the crypto VA to activate

Click the wallet card to open the detail view. You'll see:

  • Destination wallet - the address, network, token, and the date you saved it.
  • Bank transfer instructions - empty until the VA is active. While the VA is pending, a clock-icon notice reads "This crypto account is still being provisioned. Bank transfer instructions will be available once the account becomes active."

Once the upstream provider activates the VA, the Provisioning badge disappears and the deposit coordinates appear. You can share them from the wallet detail view, or use the dedicated On Ramp flow on the Operations page (next step).

Step 3 - Share the deposit coordinates

On the left nav open Operations and click the On Ramp card (Fiat → Crypto). Pick the customer, then pick the wallet (cards list every saved wallet on the customer, with a Provisioning badge on any that aren't ready yet). The modal then shows:

  • A recap of which wallet the funds will land on, with a Change wallet link.
  • A dropdown to choose the rail the customer will use: ACH, Wire, or SWIFT.
  • The matching set of coordinates with copy buttons on every value.

What the customer needs - by rail

Rail Fields shown
ACH Bank name, routing number, account number, account type, beneficiary name.
Wire Bank name, bank address, routing number, account number, beneficiary name.
SWIFT Bank name, bank address, account number, SWIFT/BIC, beneficiary name, beneficiary address, reference / memo.

Always include the reference / memo

The reference / memo lets the upstream provider attribute the wire to the right wallet. Wires received without it may be delayed for manual reconciliation. The on-ramp modal copies the memo as part of the SWIFT block - tell the customer it is required.

Send the coordinates to the customer however you normally communicate (email, secure portal). Magma does not initiate the wire on the customer's behalf - same model as a standard top-up.

Step 4 - Conversion and settlement

Once the upstream provider receives the wire:

  1. The deposit is recorded as a deposit_crypto transaction (status pending).
  2. The USD is converted to the wallet's stablecoin (USDC or USDT) at the provider's quoted rate. The transaction status moves to processing.
  3. The provider sends the stablecoin on-chain to the destination address. The on-chain transaction hash is attached when the transfer is in transit.
  4. Status moves to completed once the crypto settles at the destination.

Timing depends on the inbound rail: minutes for ACH same-bank, same-day for domestic wires, 1–3 business days for SWIFT. The on-chain leg is usually seconds-to-minutes after conversion clears.

You can follow each step on the transactions page - filter by type deposit_crypto to see only on-ramp deposits. The customer's USD balance is not affected; on-ramp is a pass-through flow.

What happens behind the scenes

UI action Endpoint
List supported networks / tokens GET /api/v1/crypto/networks
Register a wallet (creates the crypto VA) POST /api/v1/organizations/{orgId}/wallets
List a customer's wallets GET /api/v1/organizations/{orgId}/wallets
Read a wallet (with VA + deposit coordinates) GET /api/v1/wallets/{id}

POST .../wallets body: label, address, network, token. The response nests a virtual_account object with id, kira_va_id, mode (crypto), currency (USD), status (pending / active / suspended), and deposit_coordinates. deposit_coordinates is populated only when status is active.

DELETE /api/v1/wallets/{id} is currently disabled - the upstream provider does not expose a VA deactivation endpoint in v1. Contact Magma support to retire a wallet.

What's next