Skip to main content
Onramps convert fiat currency into stablecoins and deliver them to wallets. Users can onramp through virtual accounts (reusable) or the Onramp API (one-time virtual accounts).

​
Onramp Methods

HIFI supports two onramp methods:
MethodDescriptionBest For
Virtual AccountReusable bank account for USD depositsRecurring USD deposits, simplified flows
Onramp APIOne-time virtual account per transactionUSD and Africa currencies via API
Virtual Accounts for USD: For recurring USD deposits, use reusable Virtual Accounts which provide permanent bank account numbers. The Onramp API generates one-time virtual accounts per transaction and currently supports USD and Africa currencies.

​
Using the Onramp API

The Onramp API generates a one-time virtual account for a specific transaction. This method currently supports USD and Africa currencies. The flow is similar to regular virtual accounts, but the bank account details are valid only for this single transaction.

​
Request Quote

Create an onramp to get a conversion quote using the Create Onramp endpoint. Request: 
curl -X POST "https://sandbox.hifibridge.com/v2/onramps" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "source": {
      "userId": "usr_abc123",
      "currency": "usd",
      "amount": 100,
      "transferType": "ach"
    },
    "destination": {
      "userId": "usr_abc123",
      "currency": "usdc",
      "chain": "POLYGON"
    },
    "requestId": "e1047def-6942-4fd7-be04-e62eb41813b6"
  }'
The response contains the onramp quote and deposit information: 
{
  "transferType": "ONRAMP",
  "transferDetails": {
    "id": "onr_abc123",
    "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",
    "source": {
      "userId": "usr_abc123",
      "currency": "usd",
      "amount": 100,
      "transferType": "ach"
    },
    "destination": {
      "userId": "usr_abc123",
      "currency": "usdc",
      "chain": "POLYGON",
      "walletAddress": "0x848732f6c834E05b17C56fa01E83EE095f72C3c3"
    },
    "quoteInformation": {
      "sendGross": {
        "amount": "100.00",
        "currency": "usd"
      },
      "receiveNet": {
        "amount": "100.00",
        "currency": "usdc"
      },
      "rate": "1.0000",
      "expiresAt": "2025-02-04T17:15:31.927Z"
    },
    "depositInfo": {
      "bankName": "Cross River Bank",
      "bankAddress": "885 Teaneck Road, Teaneck, NJ 07666",
      "accountNumber": "11223344556677",
      "routingNumber": "021214891",
      "beneficiary": {
        "name": "HIFI Bridge",
        "address": "123 Main St, New York, NY 10010"
      },
      "referenceId": "BRGWX4J5BB7MP693BT8Z",
      "amount": "100.0",
      "currency": "usd",
      "instruction": "Please deposit the exact amount to the bank account provided. Use the reference ID as the deposit reference."
    },
    "receipt": {
      "transactionHash": null
    }
  }
}
​
transferDetails.id
string
Unique onramp ID. Save this for tracking the transaction status.
​
transferDetails.status
string
Current status. AWAITING_FUNDS means the quote is ready and waiting for your deposit.
​
transferDetails.quoteInformation
object
Conversion details including rates and amounts.
​
transferDetails.depositInfo
object
Most Important: Bank account details for sending your fiat deposit.

​
Send Payment

After receiving the quote, send the exact amount specified in depositInfo to the provided bank account. Critical requirements:
  • Use the reference ID - Include the referenceId in your bank transfer memo/reference field
  • Send exact amount - The amount must match depositInfo.amount exactly
  • Send before expiration - Deposit must arrive before quoteInformation.expiresAt
Reference ID Required: Always include the reference ID with your deposit. Deposits without the correct reference ID cannot be matched to your onramp and may be lost or delayed.

​
Processing

Once HIFI detects your deposit:
  1. Fiat validation - Confirms amount and reference ID match
  2. Conversion - Exchanges fiat for stablecoins at the quoted rate
  3. Delivery - Sends stablecoins to the destination wallet
  4. Completion - Transaction hash becomes available in receipt.transactionHash
Processing times vary by payment method:
  • ACH: 1-3 business days
  • Wire: Same day
  • International transfers: 1-5 business days depending on country

​
Transaction Status

Onramps progress through several phases:

​
Creation & Quote Phase

StatusDescription
CREATEDOnramp request created successfully
NOT_INITIATEDRequest not submitted due to validation error
OPEN_QUOTEQuote generated and awaiting deposit
QUOTE_FAILEDQuote expired before deposit was received
AWAITING_FUNDSWaiting for fiat deposit with reference ID

​
Fiat Processing Phase

StatusDescription
FIAT_INITIATEDDeposit detected, fiat processing started
FIAT_PENDINGFiat clearing and validation in progress
FIAT_PROCESSEDFiat successfully received and validated
FIAT_FAILEDFiat processing failed (e.g., invalid amount, missing reference)
FIAT_RETURNEDFiat returned to sender after failure

​
Crypto Processing Phase

StatusDescription
CRYPTO_INITIATEDConverting fiat to stablecoins
CRYPTO_PENDINGSending stablecoins on blockchain
CRYPTO_FAILEDBlockchain transaction failed
COMPLETEDStablecoins delivered to wallet, transaction complete

​
Tracking Onramps

Status Updates: Subscribe to ONRAMP.CREATE and ONRAMP.UPDATE webhook events to receive real-time status notifications. See Webhooks for setup instructions.
Monitor onramp status using the Retrieve Onramp endpoint. The response structure matches the create endpoint shown above. Request: 
curl -X GET "https://sandbox.hifibridge.com/v2/onramps/onr_abc123" \
  -H "Authorization: Bearer YOUR_API_KEY"
Use the transactionHash in the response to view the stablecoin delivery on a blockchain explorer.

​
Quote Validity

Quote expiration times vary by currency. This ensures:
  • Current market rates
  • Prevention of stale pricing
  • Timely transaction processing
If your quote expires (status becomes QUOTE_FAILED):
  1. Create a new onramp request
  2. Get updated pricing
  3. Complete the deposit with the new reference ID
Quote Expiration: The expiresAt timestamp in quoteInformation shows exactly when the quote expires for your specific currency. Always check this timestamp and plan to send your deposit with enough time for bank processing before this deadline.

​
Key Concepts

Both methods use virtual accounts, but with different characteristics:Virtual Accounts (reusable):
  • Permanent bank account number
  • Can be used for multiple deposits
  • USD currency only
  • Created via Virtual Accounts API
Onramp API (one-time):
  • One-time virtual account per transaction
  • Generated per transaction via Onramps API
  • Currently supports USD and Africa currencies
  • Bank details valid only for that transaction
The Onramp API works like one-time virtual accounts. The reference ID functions similarly to how deposits are matched to virtual accounts:
  • Each onramp generates a unique reference ID
  • Include it in your bank transfer memo/reference field
  • HIFI uses it to match your deposit to the correct transaction
  • Missing reference IDs cause delays or lost funds
Where to include it: Most banks have a “memo,” “reference,” or “description” field for transfers. Put the reference ID there.
The deposit amount must match exactly:
  • Send the exact amount shown in depositInfo.amount
  • Include all decimal places (e.g., 100.00,not100.00, not 100)
  • Don’t round or adjust for fees
  • Mismatched amounts may be rejected or require manual intervention
USDT onramps incur an additional 0.1% exchange fee beyond standard rates. This fee appears on your monthly invoice, not deducted from the transaction amount.
By default, stablecoins go to the user’s HIFI wallet. To send to an external wallet instead, include externalWalletId in the destination.

​
Getting Help