> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hifi.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Wallets

> 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

<AccordionGroup>
  <Accordion title="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.
  </Accordion>

  {" "}

  <Accordion title="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.
  </Accordion>

  <Accordion title="Multi-Currency">
    Wallets can hold multiple stablecoins simultaneously. Supported currencies include USDC and USDT, with additional stablecoins available based on customer needs.
  </Accordion>
</AccordionGroup>

## Support Chain and Currencies

| Chain           | Currencies              |                        |
| --------------- | ----------------------- | ---------------------- |
| Ethereum        | USDT, USDC, USDG, PYUSD |                        |
| Polygon PoS     | USDT, USDC              |                        |
| Solana          | USDT, USDC, USDG, PYUSD |                        |
| Base            | USDC                    |                        |
| Tron            | USDT                    |                        |
| Arbitrum        | USDC                    | available upon request |
| Optimism        | USDC                    | available upon request |
| Canton          | USDCx                   | available upon request |
| Flow Evm        | PYUSD0                  | available upon request |
| BNB Smart Chain | USDT                    | coming soon...         |
| XRPL            | USDC, RLUSD             | coming soon...         |

## Checking Balances

Get real-time balance information for a specific currency on a specific chain using the [Get Wallet Balance](https://docs.hifi.com/api-reference/wallet/get-wallet-balance) endpoint.

**Request:**

```bash theme={null}
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:**

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

**Response Fields:**

<ResponseField name="balance" type="string">
  Raw balance in smallest unit (e.g., micro-USDC for USDC with 6 decimals)
</ResponseField>

<ResponseField name="displayBalance" type="string">
  Human-readable balance in standard units (e.g., "0.01" USDC)
</ResponseField>

<ResponseField name="tokenInfo.decimals" type="number">
  Number of decimal places for this token (6 for USDC)
</ResponseField>

<ResponseField name="tokenInfo.contractAddress" type="string">
  Smart contract address for this token on the specified chain
</ResponseField>

<Note>
  **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.
</Note>

## 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:**

```bash theme={null}
curl -X GET "https://sandbox.hifibridge.com/v2/users/usr_abc123" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

**Response (excerpt):**

```json theme={null}
{
  "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:

1. **KYC verification** for the relevant rail
2. **Virtual account setup** for the desired fiat currency

See [Virtual Accounts](/docs/accounts/virtual-accounts) for detailed setup instructions.

## Tracking Deposits

Track all incoming blockchain deposits via the [Get Inbound Deposits](https://docs.hifi.com/api-reference/wallet/get-inbound-deposits) endpoint, which returns a full history of stablecoins received by the user's wallet.

**Request:**

```bash theme={null}
curl -X GET "https://sandbox.hifibridge.com/v2/users/usr_abc123/wallets/deposits" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

**Response:**

```json theme={null}
{
  "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:**

<ResponseField name="transaction.transactionHash" type="string">
  Blockchain transaction hash (view on block explorer)
</ResponseField>

<ResponseField name="transaction.status" type="string">
  Deposit status: `PENDING`, `COMPLETED`, `FAILED`
</ResponseField>

<ResponseField name="transaction.amount" type="string">
  Human-readable amount (e.g., "19" USDC)
</ResponseField>

<ResponseField name="transaction.unitAmount" type="string">
  Raw amount in smallest unit (e.g., "19000000" micro-USDC)
</ResponseField>

<ResponseField name="nextCursor" type="string">
  Pagination cursor for retrieving additional records
</ResponseField>

<Note>
  **Real-Time Updates:** Subscribe to `WALLET.DEPOSIT` webhook events to receive immediate notifications when deposits are detected on the blockchain.
</Note>

## 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](https://docs.hifi.com/api-reference/crypto-transfer/create-a-crypto-transfer) endpoint.

**Transfer to another HIFI user:**

```bash theme={null}
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:**

```bash theme={null}
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"
  }'
```

<Note>
  **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.
</Note>

### Fiat Offramps

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

1. **KYC verification** for the relevant rail
2. **Offramp account setup** with bank account details

See [Offramp](/docs/transactions/offramps) for detailed instructions.

## Key Concepts

<AccordionGroup>
  <Accordion title="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.
  </Accordion>

  {" "}

  <Accordion title="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.
  </Accordion>

  {" "}

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>
</AccordionGroup>

## Sample Code

<Steps>
  <Step title="Check balance before transfer">
    Get the current balance using the [Get Wallet Balance](https://docs.hifi.com/api-reference/wallet/get-wallet-balance) endpoint.

    ```bash theme={null}
    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.
  </Step>

  <Step title="Monitor deposit status">
    List recent deposits using the [Get Inbound Deposits](https://docs.hifi.com/api-reference/wallet/get-inbound-deposits) endpoint.

    ```bash theme={null}
    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.
  </Step>

  <Step title="Display balance to users">
    Convert the raw balance response to a user-friendly display format.

    ```javascript theme={null}
    // 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`);
    ```
  </Step>
</Steps>

## Getting Help

* 📧 **Email:** [support@hifi.com](mailto:support@hifi.com)
* 💬 **Slack:** Message us in our shared Slack channel

## Related Resources

* [Users](/docs/users) - Create users and understand wallet provisioning
* [Wallet Transfers](/docs/transactions/transfer) - Send stablecoins between wallets
* [Virtual Accounts](/docs/accounts/virtual-accounts) - Set up fiat onramps to wallets
* [Offramps](/docs/transactions/offramps) - Convert wallet balances to fiat
* [Webhooks](/docs/webhooks) - Real-time deposit and transfer notifications
* [API Reference](https://docs.hifi.com/api-reference/wallet/retrieve-wallet-balance) - Complete endpoint documentation