Skip to main content
Onramps are transactions that convert fiat currencies to stablecoins in HIFI wallets. The available onramp methods vary by region due to local payment infrastructure and regulatory requirements.

​
How Onramps Work

Onramps follow a simple three-step process:
  1. Create an onramp – Initiate a payment from an Account into a Wallet
  2. Review quote – Examine the exchange rate, fees, and quote validity period
  3. Send money – Transfer the fiat currency to the provided bank account using the reference ID

​
Quote Validity

Quotes are time-sensitive and typically expire within 24 hours. This ensures you get current market rates and prevents stale pricing. If a quote expires before you deposit funds, you’ll need to create a new onramp request to get updated pricing.

​
Transaction Structure

When you create an onramp, the API response includes detailed information about the transaction: 
{
  "transferType": "ONRAMP",
  "transferDetails": {
    "id": "b26927e6-2771-423c-af44-a3c7a3e815c5",
    "requestId": "e1047def-6942-4fd7-be04-e62eb41813b6",
    "createdAt": "2025-02-03T17:15:31.927121+00:00",
    "updatedAt": "2025-02-03T17:15:35.882+00:00",
    "status": "AWAITING_FUNDS",
    "failedReason": null,
    "source": {
      /* Source */
    },
    "destination": {
      /* Destination */
    },
    "receipt": { "transactionHash": null },
    "developerFee": null,
    "quoteInformation": {
      /* Quote */
    },
    "depositInfo": {
      /* Deposit Info */
    }
  }
}

{
  "userId": "c15c0adf-3e45-4a62-b334-73aeec127649",
  "currency": "usd",
  "transferType": "ach",
  "amount": 10,
  "accountId": null,
  "user": {
    "email": "henry@hifibridge.com",
    "lastName": "Wu",
    "firstName": "Henry",
    "businessName": null
  },
  "bankInfo": null
}

{
  "userId": "c15c0adf-3e45-4a62-b334-73aeec127649",
  "currency": "usdc",
  "chain": "POLYGON_AMOY",
  "walletAddress": "0x848732f6c834E05b17C56fa01E83EE095f72C3c3",
  "externalWalletId": "335051d6-44ba-4ad7-ab78-bb433a568161",
  "amount": null,
  "user": {
    "email": "henry@hifibridge.com",
    "lastName": "Wu",
    "firstName": "Henry",
    "businessName": null
  }
}

{
  "sendGross": {
    "amount": "10.00",
    "currency": "usd"
  },
  "sendNet": {
    "amount": "10.00",
    "currency": "usd"
  },
  "railFee": {
    "amount": "0.00",
    "currency": "usd"
  },
  "receiveGross": {
    "amount": "10.00",
    "currency": "usdc"
  },
  "receiveNet": {
    "amount": "10.00",
    "currency": "usdc"
  },
  "rate": "1.0000",
  "expiresAt": "2025-02-04T17:15:31.927Z"
}

{
  "bankName": "Bank of Nowhere",
  "bankAddress": "1800 North Pole St., Orlando, FL 32801",
  "accountNumber": "11223344556677",
  "routingNumber": "123456789",
  "iban": "",
  "bic": "",
  "beneficiary": {
    "name": "HiFi Bridge",
    "address": "1234 Elm St, Springfield, IL 12345"
  },
  "referenceId": "BRGWX4J5BB7MP693BT8Z",
  "amount": "10.0",
  "currency": "usd",
  "instruction": "Please deposit the exact amount of currency to the bank account provided. Use the reference ID as the deposit reference."
}

​
Transaction Status

Onramp transactions progress through several statuses:
  • AWAITING_FUNDS: Waiting for you to deposit fiat currency to the provided bank account
  • PROCESSING: Funds have been received and are being converted to stablecoins
  • COMPLETED: Stablecoins have been successfully deposited to your wallet
  • FAILED: Transaction failed (check failedReason for details)

​
Deposit Information

The depositInfo object contains all the details you need to complete your fiat deposit:
  • Bank details: Account number, routing number, and bank address
  • Beneficiary information: Name and address of the receiving entity
  • Reference ID: Unique identifier you must include with your deposit
  • Amount: Exact amount to deposit (must match exactly)
  • Instructions: Specific guidance for completing the deposit
Always use the exact reference ID provided in the deposit information when making your fiat transfer. This ensures your funds are properly credited to your onramp transaction.

​
Quote Information

The quote includes both gross and net amounts for both sending and receiving:
  • sendGross: Total amount you’re sending in fiat currency
  • sendNet: Net amount after any rail fees are deducted
  • receiveGross: Total amount you’ll receive in stablecoins
  • receiveNet: Net amount you’ll actually receive
  • rate: Current exchange rate between fiat and stablecoin
  • expiresAt: When the quote expires and you’ll need a new one

​
Settlement Rules

You can configure settlement rules to automatically calculate and distribute fees for onramp transactions. Settlement rules support:
  • Percentage-based or fixed fee structures
  • Tiered pricing based on transaction volume
  • Fee distribution to multiple wallet addresses
  • Network-specific configurations

Settlement Rules

Learn how to configure fee calculations and distribution

​
Try it out

Convert USD to USDC

Learn how to pay in to a Wallet
⌘I