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.
All USDT-related onramps incur an additional 0.1% exchange fee, which will be reflected on your monthly invoice.

​
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

1. Transaction Creation Phase
  • CREATED: The transaction request has been successfully created.
  • NOT_INITIATED: The transaction was not submitted due to a validation error.
2. Quote and Funding Phase
  • OPEN_QUOTE: A quote has been generated and is awaiting user acceptance.
  • QUOTE_FAILED: The transaction failed or expired before the quote was accepted.
  • AWAITING_FUNDS: Waiting for funds to be sent to the provided deposit instruction.
3. Fiat Processing Phase
  • FIAT_INITIATED: The fiat transaction process has started.
  • FIAT_PENDING: The fiat transaction is in progress and awaiting processing.
  • FIAT_PROCESSED: The fiat transaction has been successfully processed.
  • FIAT_FAILED: The fiat transaction failed due to an error.
  • FIAT_RETURNED: The fiat funds were returned after a failed transaction.
4. Crypto Processing Phase
  • CRYPTO_INITIATED: The crypto transaction process has started.
  • CRYPTO_PENDING: The crypto transaction is in progress and awaiting on-chain confirmation.
  • CRYPTO_FAILED: The crypto transaction failed due to an error.
  • COMPLETED: The transaction has been successfully confirmed on-chain.

​
Flow Chart

Onramp Status Flow Chart

​
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