Skip to main content

Prerequisites

Before you begin, make sure you have:
  1. A User with GLOBAL_NETWORK Rail enabled
  2. Valid payment method (bank account, card, etc.)

Step 1: Create Account

POST /v2/users/{userId}/accounts
curl --request POST \
     --url https://production.hifibridge.com/v2/users/{userId}/accounts \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '{
  "rail": "onramp",
  "type": "nigeriaGlobalNetwork",
  "accountHolder": {
    "name": "Adebayo Johnson",
    "type": "individual",
    "address": {
      "city": "Lagos",
      "country": "NG",
      "postalCode": "100001",
      "addressLine1": "123 Victoria Island",
      "addressLine2": "Block A",
      "stateProvinceRegion": "Lagos"
    },
    "dateOfBirth": "1985-03-20",
    "idNumber": "NG12345678901",
    "nationality": "NGA"
  },
  "nigeriaGlobalNetwork": {
    "bankName": "Access Bank",
    "accountNumber": "1234567890",
    "currency": "ngn"
  }
}'
Response:
{
  "id": "acc_987654321",
  "type": "nigeriaGlobalNetwork",
  "rail": "offramp",
  "status": "ACTIVE",
  "accountHolder": {
    "name": "Adebayo Johnson",
    "type": "individual"
  },
  "nigeriaGlobalNetwork": {
    "bankName": "Access Bank",
    "accountNumber": "1234567890",
    "currency": "ngn"
  },
  "createdAt": "2025-02-03T17:15:31.927121+00:00"
}

Step 2: Create Onramp

Create the onramp transaction directly: POST /v2/onramps
curl --request POST \
     --url https://production.hifibridge.com/v2/onramps \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '{
  "requestId": "string",
  "purposeOfPayment": "gift",
  "isInstant": false,
  "source": {
    "amount": 60000,
    "currency": "ngn",
    "transferType": "ach",
    "accountId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "userId": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
  },
  "destination": {
    "amount": 100,
    "currency": "usdc",
    "chain": "POLYGON_AMOY",
    "userId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "externalWalletId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "virtualAccountId": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
  },
  "fee": {
    "type": "FIX",
    "value": 0
  }
}'
Response:
{
  "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 account details */
    },
    "destination": {
      /* destination wallet details */
    },
    "receipt": {
      /* transaction receipt */
    },
    "developerFee": null,
    "quoteInformation": {
      /* exchange rate and fees */
    },
    "depositInfo": {
      /* bank deposit instructions */
    }
  }
}

Response Breakdown

Information about the source of funds (NGN account). Includes user details, currency, transfer type, and amount.
{
  "userId": "c15c0adf-3e45-4a62-b334-73aeec127649",
  "currency": "ngn",
  "transferType": "ach",
  "amount": 60000,
  "accountId": null,
  "user": {
    "email": "henry@hifibridge.com",
    "lastName": "Wu",
    "firstName": "Henry",
    "businessName": null
  },
  "bankInfo": null
}
Information about the destination (USDC wallet). Includes wallet address, chain, user details, and external wallet ID.
{
  "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
  }
}
Transaction receipt information. The transactionHash will be populated once the USDC is sent to your wallet.
{
  "transactionHash": null
}
Exchange rate and fee breakdown including:
  • sendGross: Total amount you’re sending
  • sendNet: Amount after fees
  • railFee: Fee charged by the payment rail
  • receiveGross: Total USDC you’ll receive
  • receiveNet: USDC after all fees
  • rate: Exchange rate
  • expiresAt: When the quote expires
{
  "sendGross": {
    "amount": "60000.00",
    "currency": "ngn"
  },
  "sendNet": {
    "amount": "60000.00",
    "currency": "ngn"
  },
  "railFee": {
    "amount": "0.00",
    "currency": "ngn"
  },
  "receiveGross": {
    "amount": "100.00",
    "currency": "usdc"
  },
  "receiveNet": {
    "amount": "100.00",
    "currency": "usdc"
  },
  "rate": "0.0017",
  "expiresAt": "2025-02-04T17:15:31.927Z"
}
Bank deposit information for ACH transfers. Includes:
  • bankName: Name of the bank
  • bankAddress: Bank’s address
  • accountNumber: Account number for deposits
  • routingNumber: Bank routing number
  • beneficiary: Recipient information
  • referenceId: Unique reference for your deposit
  • amount: Exact amount to deposit
  • instruction: Deposit instructions
{
  "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": "60000.0",
  "currency": "ngn",
  "instruction": "Please deposit the exact amount of currency to the bank account provided. Use the reference ID as the deposit reference."
}

Refresh Quote

While the quote is still valid, you can refresh it to get updated rates: POST /v2/onramps/{transferId}/quote/refresh
curl --request POST \
     --url https://production.hifibridge.com/v2/onramps/{transferId}/quote/refresh \
     --header 'accept: application/json'
Info: You can only refresh quotes while the onramp is in AWAITING_FUNDS status and before the quote expires.

Step 3: Accept Quote

Once you’re satisfied with the quote, accept it to proceed with the onramp: POST /v2/onramps/{transferId}/quote/accept
curl --request POST \
     --url https://production.hifibridge.com/v2/onramps/{transferId}/quote/accept \
     --header 'accept: application/json'
Info: Once you accept the quote, you cannot refresh it again. Make sure you’re ready to proceed with the deposit.

Step 4: Send Bank Deposit

Use the deposit information from the response to send funds:
  1. Bank Name: Bank of Nowhere
  2. Account Number: 11223344556677
  3. Routing Number: 123456789
  4. Reference ID: BRGWX4J5BB7MP693BT8Z
  5. Amount: 60000.00 NGN (exact amount)
  6. Beneficiary: HiFi Bridge

Step 5: Confirm Transaction

Listen for Webhooks

Set up webhook notifications to track status changes: Webhook Events:
  • ONRAMP.CREATE - Creation for onramps
  • ONRAMP.UPDATE - Updates for onramps

Check Wallet Balance

Verify the USDC has been received in your wallet: GET /v2/users/{userId}/wallets/balance
curl -X GET "https://production.hifibridge.com/v2/users/{userId}/wallets/balance" \
  -H "Authorization: Bearer YOUR_API_KEY"
I