HIFI Developer Docs

A Wallet is a cryptocurrency account that holds and moves digital assets on the HIFI platform. Every wallet belongs to a user and can hold balances in supported stablecoins across multiple blockchain networks.

Automatic Provisioning

Wallets are automatically created when a user is created - no separate setup required. Each user receives wallet addresses on Polygon and Ethereum. Other chains can be added later.

Wallet Properties

Custodial

HIFI wallets are custodial, meaning HIFI manages the private keys for security and regulatory compliance. This allows for features like account recovery and compliance monitoring while users maintain full control over their funds through the API.

Multi-Chain

Each user has a unique wallet address on every supported blockchain. HIFI currently supports Polygon, Ethereum, Solana, and Base, with additional chains available based on customer demand. Each blockchain has its own address - for example, a single user has separate addresses for USDC on Polygon, USDC on Ethereum, and USDC on Solana.

Multi-Currency

Wallets can hold multiple stablecoins simultaneously. Supported currencies include USDC and USDT, with additional stablecoins available based on customer needs.

Checking Balances

Get real-time balance information for a specific currency on a specific chain using the Get Wallet Balance endpoint. Request:

curl -X GET "https://sandbox.hifibridge.com/v2/users/usr_abc123/wallets/balance?chain=POLYGON&currency=usdc" \
  -H "Authorization: Bearer YOUR_API_KEY"

Query Parameters:

Parameter	Type	Required	Description	Example Values
`chain`	string	✅	Blockchain network	`POLYGON`, `ETHEREUM`, `SOLANA`, `BASE`
`currency`	string	✅	Stablecoin to check balance for	`usdc`, `usdt`

Response:

{
  "balance": "10000",
  "displayBalance": "0.01",
  "tokenInfo": {
    "chain": "POLYGON_MAINNET",
    "contractAddress": "0x3c499c542cef5e3811e1192ce70d8cc03d5c3359",
    "assetType": "ERC20",
    "quantity": "10000",
    "symbol": "USDC",
    "decimals": 6
  }
}

Response Fields:

balance

string

Raw balance in smallest unit (e.g., micro-USDC for USDC with 6 decimals)

displayBalance

string

Human-readable balance in standard units (e.g., “0.01” USDC)

tokenInfo.decimals

number

Number of decimal places for this token (6 for USDC)

tokenInfo.contractAddress

string

Smart contract address for this token on the specified chain

Balance Units: The balance field returns the amount in the token’s smallest unit. For USDC (6 decimals), a balance of “10000” equals 0.01 USDC. Use displayBalance for user-facing displays.

Receiving Funds

Wallets can receive funds through two methods:

Blockchain Transfers

Wallets can receive stablecoins from:

Other HIFI users (instant, no fees)
External wallets (standard blockchain confirmation times)
Exchange withdrawals
Any wallet address on supported networks

To receive funds, simply share the user’s wallet address for the specific blockchain and currency. No additional setup required. Get wallet addresses:

curl -X GET "https://sandbox.hifibridge.com/v2/users/usr_abc123" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response (excerpt):

{
  "id": "usr_abc123",
  "wallets": {
    "INDIVIDUAL": {
      "POLYGON": {
        "address": "0x1b932E54e77Aeb698144550d5a493Ea99E20Daa7"
      },
      "ETHEREUM": {
        "address": "0xC1c767eaB34b3Cc2C33a354f6Ff2c20fCB98D3C9"
      },
      "SOLANA": {
        "address": "9xQeWvG816bUx9EPjHmaT23yvVM2ZWbrrpZb9PusVFin"
      }
    }
  }
}

Fiat Onramps

When a user deposits fiat currency (USD, EUR, etc.) through a virtual account, it’s automatically converted to stablecoins and credited to their wallet. This requires:

KYC verification for the relevant rail
Virtual account setup for the desired fiat currency

See Virtual Accounts for detailed setup instructions.

Tracking Deposits

Track all incoming blockchain deposits via the Get Inbound Deposits endpoint, which returns a full history of stablecoins received by the user’s wallet. Request:

curl -X GET "https://sandbox.hifibridge.com/v2/users/usr_abc123/wallets/deposits" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response:

{
  "count": 1,
  "records": [
    {
      "userId": "usr_abc123",
      "id": "dep_xyz789",
      "createdAt": "2025-06-25T15:47:16.983978+00:00",
      "updatedAt": "2025-06-25T15:47:16.983978+00:00",
      "wallet": {
        "id": "wlt_def456",
        "address": "0x0B95D270400BE4319EAFbfDD82F6C38B59ab54Ef",
        "chain": "POLYGON",
        "walletType": "INDIVIDUAL"
      },
      "transaction": {
        "transactionHash": "0xe5284c4cb35ae9b5eb0ae23b840032f320b87b63f8967ee9b67ee09dfe6a194a",
        "chain": "POLYGON",
        "currency": "usdc",
        "status": "COMPLETED",
        "sourceAddress": "0x8B3D4E9C42F7A1B5D2E6F8A9C3B7D5E1F4A2C8B6",
        "destinationAddress": "0x0B95D270400BE4319EAFbfDD82F6C38B59ab54Ef",
        "contractAddress": "0x41E94Eb019C0762f9Bfcf9Fb1E58725BfB0e7582",
        "amount": "19",
        "unitAmount": "19000000"
      }
    }
  ],
  "nextCursor": "2025-06-25T15:47:16.983978+00:00"
}

Response Fields:

transaction.transactionHash

string

Blockchain transaction hash (view on block explorer)

transaction.status

string

Deposit status: PENDING, COMPLETED, FAILED

transaction.amount

string

Human-readable amount (e.g., “19” USDC)

transaction.unitAmount

string

Raw amount in smallest unit (e.g., “19000000” micro-USDC)

nextCursor

string

Pagination cursor for retrieving additional records

Real-Time Updates: Subscribe to WALLET.DEPOSIT webhook events to receive immediate notifications when deposits are detected on the blockchain.

Sending Funds

Wallets can send stablecoins through two methods:

Wallet Transfers

Send stablecoins to other HIFI users or external wallet addresses using the Create Crypto Transfer endpoint. Transfer to another HIFI user:

curl -X POST "https://sandbox.hifibridge.com/v2/wallets/transfers" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "source": {
      "userId": "usr_abc123"
    },
    "destination": {
      "userId": "usr_xyz789"
    },
    "amount": 10,
    "currency": "usdc",
    "chain": "POLYGON",
    "requestId": "a40ea2aa-7937-4be9-bb1f-b75f1489bcc6"
  }'

Transfer to external wallet:

curl -X POST "https://sandbox.hifibridge.com/v2/wallets/transfers" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "source": {
      "userId": "usr_abc123"
    },
    "destination": {
      "address": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb"
    },
    "amount": 10,
    "currency": "usdc",
    "chain": "POLYGON",
    "requestId": "b51fb3bb-8a48-5cfa-cc2g-c86g2589cdd7"
  }'

No Registration Required: You can send to any external wallet address directly without registering it first. Simply provide the address in the destination.address field.

Fiat Offramps

Convert stablecoins to fiat currency and send to a bank account. This requires:

KYC verification for the relevant rail
Offramp account setup with bank account details

See Offramp for detailed instructions.

Key Concepts

Wallet Types

Each wallet has a walletType that indicates its purpose:

INDIVIDUAL - Personal wallet for individual users
BUSINESS - Business wallet for corporate users

The wallet type affects compliance requirements and transaction limits.

Chain-Specific Addresses

Each blockchain network has its own address format: - Ethereum/Polygon/Base - 0x format (e.g., 0x1b932E54...) - Solana - Base58 format (e.g., 9xQeWvG816...) Always use the correct address for the target blockchain to avoid lost funds.

Token Decimals

Stablecoins use different decimal places: - USDC - 6 decimals (1 USDC = 1,000,000 micro-USDC) - USDT - 6 decimals Always check the decimals field in API responses to correctly display amounts.

Confirmation Times

Blockchain transfer speeds vary by network:

Polygon - ~2 seconds
Ethereum - ~12 seconds
Solana - ~0.4 seconds
Base - ~2 seconds

HIFI credits deposits after the blockchain confirms the transaction.

Sample Code

Check balance before transfer

Get the current balance using the Get Wallet Balance endpoint.

curl -X GET "https://sandbox.hifibridge.com/v2/users/usr_abc123/wallets/balance?chain=POLYGON&currency=usdc" \
  -H "Authorization: Bearer YOUR_API_KEY"

Check that displayBalance is greater than or equal to the amount you want to send. If insufficient, the transfer will fail with an insufficient balance error.

Monitor deposit status

List recent deposits using the Get Inbound Deposits endpoint.

curl -X GET "https://sandbox.hifibridge.com/v2/users/usr_abc123/wallets/deposits" \
  -H "Authorization: Bearer YOUR_API_KEY"

Look for the deposit record with the matching transactionHash. The status field shows:

PENDING - Waiting for blockchain confirmation
COMPLETED - Funds credited to wallet
FAILED - Transaction failed (funds not received)

Alternatively, set up WALLET.DEPOSIT webhook events for real-time notifications instead of polling the API.

Display balance to users

Convert the raw balance response to a user-friendly display format.

// Example: Convert raw balance to display format
const response = await fetch(
  "https://sandbox.hifibridge.com/v2/users/usr_abc123/wallets/balance?chain=POLYGON&currency=usdc",
  {
    headers: { Authorization: "Bearer YOUR_API_KEY" },
  }
);

const data = await response.json();

// Use displayBalance for user-facing displays
console.log(`Balance: ${data.displayBalance} USDC`);

// Or calculate manually from raw balance and decimals
const displayAmount =
  parseFloat(data.balance) / Math.pow(10, data.tokenInfo.decimals);
console.log(`Balance: ${displayAmount.toFixed(2)} USDC`);

Getting Help

📧 Email: support@hifibridge.com
💬 Slack: Message us in our shared Slack channel

Users - Create users and understand wallet provisioning
Wallet Transfers - Send stablecoins between wallets
Virtual Accounts - Set up fiat onramps to wallets
Offramps - Convert wallet balances to fiat
Webhooks - Real-time deposit and transfer notifications
API Reference - Complete endpoint documentation

Get started

Core concepts

Features

Compliance

References

Wallets

Automatic Provisioning

Wallet Properties

Checking Balances

Receiving Funds

Blockchain Transfers

Fiat Onramps

Tracking Deposits

Sending Funds

Wallet Transfers

Fiat Offramps

Key Concepts

Sample Code

Getting Help

Get started

Core concepts

Features

Compliance

References

​Automatic Provisioning

​Wallet Properties

​Checking Balances

​Receiving Funds

​Blockchain Transfers

​Fiat Onramps

​Tracking Deposits

​Sending Funds

​Wallet Transfers

​Fiat Offramps

​Key Concepts

​Sample Code

​Getting Help

​Related Resources

Automatic Provisioning

Wallet Properties

Checking Balances

Receiving Funds

Blockchain Transfers

Fiat Onramps

Tracking Deposits

Sending Funds

Wallet Transfers

Fiat Offramps

Key Concepts

Sample Code

Getting Help

Related Resources