Skip to main content

Prerequisites

Before you begin, make sure you have:
  1. A User with USD Rail enabled
  2. A destination Wallet created

Step 1: Create Virtual Account

Create a dedicated bank account for fiat-to-stablecoin conversions: POST /v2/users/{userId}/virtual-accounts
curl --request POST \
     --url https://production.hifibridge.com/v2/users/userId/virtual-accounts \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '{
  "sourceCurrency": "usd",
  "destinationCurrency": "usdc",
  "destinationChain": "POLYGON"
}'
Response:
{
  "message": "Virtual account created successfully",
  "accountInfo": {
    "id": "cfbc005d-8640-57a4-89e1-539c974fa780",
    "userId": "840c28f2-ea7d-5c3a-9271-b10fd8b6ae6d",
    "source": {
      "paymentRail": ["ach", "wire", "rtp", "swift"],
      "currency": "usd"
    },
    "destination": {
      "chain": "POLYGON",
      "currency": "usdc",
      "walletAddress": "0xd102C4130985B7fcB95697616eaf5542c4f98d49",
      "externalWalletId": null
    },
    "status": "activated",
    "depositInstructions": {
      "bankName": "Bank of NoWhere",
      "bankAddress": "123 Main St, New York, NY 10001, USA",
      "swiftCode": "XXXXXXXX",
      "beneficiary": {
        "name": "Henry Wu",
        "address": "<development>, <development>"
      },
      "ach": {
        "routingNumber": "028000024",
        "accountNumber": "123456789"
      },
      "wire": {
        "routingNumber": "021000021",
        "accountNumber": "123456789"
      },
      "rtp": {
        "routingNumber": "021000021",
        "accountNumber": "123456789"
      }
    }
  }
}

Step 2: Share Deposit Instructions

Provide the deposit instructions to Users
  • Bank Name: Bank of NoWhere
  • ACH Routing Number: 028000024
  • Account Number: 123456789
  • Wire Routing Number: 021000021
  • SWIFT Code: XXXXXXXX
  • Beneficiary: Henry Wu

Step 3: Monitor Deposits

Track incoming deposits to your virtual account:

Webhook Events

  • ONRAMP.CREATED - Transaction received

Step 4: Verify Destination Wallet

Check that the stablecoins were received in the destination wallet: GET /v2/users/{userId}/wallets/balance
curl -X GET "https://production.hifibridge.com/v2/users/840c28f2-ea7d-5c3a-9271-b10fd8b6ae6d/wallets/balance?chain=POLYGON&currency=usdc" \
  -H "Authorization: Bearer YOUR_API_KEY"
Response:
{
  "balances": [
    {
      "currency": "usdc",
      "chain": "POLYGON",
      "balance": "1000.00",
      "availableBalance": "1000.00"
    }
  ]
}

Virtual Account Statuses

Virtual accounts progress through several statuses:
  • CREATED: Account has been created and is being set up
  • ACTIVATED: Account is ready to receive deposits
  • DEACTIVATED: Account is temporarily disabled
  • SUSPENDED: Account is suspended due to compliance issues

Advanced Options

Update Destination Settings

Modify the destination wallet or currency:
curl --request PUT \
     --url https://production.hifibridge.com/v2/virtual-accounts/cfbc005d-8640-57a4-89e1-539c974fa780 \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '{
  "destination": {
    "chain": "ETHEREUM",
    "currency": "usdt",
    "walletAddress": "0xNewWalletAddress"
  }
}'

Deactivate Account

Temporarily disable the virtual account:
curl --request POST \
     --url https://production.hifibridge.com/v2/virtual-accounts/cfbc005d-8640-57a4-89e1-539c974fa780/deactivate \
     --header 'accept: application/json'

Reactivate Account

Re-enable a deactivated account:
curl --request POST \
     --url https://production.hifibridge.com/v2/virtual-accounts/cfbc005d-8640-57a4-89e1-539c974fa780/reactivate \
     --header 'accept: application/json'

Test with Sandbox

Simulate deposits for testing:
curl --request POST \
     --url https://sandbox.hifibridge.com/v2/virtual-accounts/cfbc005d-8640-57a4-89e1-539c974fa780/simulate-deposit \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '{
  "amount": "1000.00",
  "currency": "usd",
  "description": "Test deposit"
}'
I