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

# USD Balances in Virtual Accounts

> Hold, view, and manage USD balances in virtual accounts

In this guide, you'll learn how to use Conduit's API to `hold, view, receive deposits, transfer/convert and manage USD balances` in virtual accounts.

## Prerequisites

* You have an active Conduit account with API access
* You have API credentials (API Key and Secret)
* You have reviewed our [Customers](/core-concepts/customers) Core Concepts
* You have reviewed our [Virtual USD Accounts](/core-concepts/virtual-accounts) Core Concepts

## What you can do

<CardGroup cols={2}>
  <Card title="Hold USD" icon="wallet">
    Maintain a USD balance in your named virtual account
  </Card>

  <Card title="View balance" icon="eye">
    See your available USD at any time
  </Card>

  <Card title="Receive deposits" icon="arrow-down">
    Share deposit instructions to accept funds from first-party or third-party senders
  </Card>

  <Card title="View transactions" icon="list">
    See an itemized list of all credits and debits specific to your virtual account
  </Card>

  <Card title="Transfer or convert" icon="arrow-right-arrow-left">
    Use your USD balance as the source for transfers and currency conversions
  </Card>
</CardGroup>

## Deposits

Deposits are automatically credited to your virtual account. There's no need to create a transaction for first-party deposits; however, we strongly encourage creating transactions for third-party deposits. Simply share your deposit instructions with the sender and the balance updates automatically when funds arrive. Each virtual account has both domestic and international deposit instructions, which contain different bank details depending on where the sender is located.

### Get Customer Deposit Instructions

Retrieve bank details to share with senders for a specific customer.

```http theme={null}
GET /customers/{customer_id}/account/deposit-instructions
```

### Response Example

```json theme={null}
{
    "data": [
      {
        "bank": {
          "name": "MOCK BANK INC",
          "address": {
            "city": "Mock City",
            "state": "MC",
            "street": "123 Mock Street",
            "country": "US",
            "postalCode": "12345"
          },
          "branchCode": "001",
          "routingCode": "123456789",
          "accountNumber": "000123456789"
        },
        "type": "local",
        "assetType": "USD",
        "reference": "mock-reference",
        "accountHolder": {
          "name": "Mock Fintech LLC",
          "address": {
            "city": "Mockville",
            "state": "MV",
            "street": "456 Mock Avenue",
            "country": "US",
            "postalCode": "67890"
          },
          "taxNumber": "TAX123456"
        }
      }
    ]
}
```

### Get Client Deposit Instructions

If you have a USD virtual account, you can retrieve your bank details to share with senders. If you have multiple subsidiaries onboarded, pass the `client_id` to retrieve deposit instructions for a specific subsidiary's account.

```http theme={null}
GET /clients/{client_id}/account/deposit-instructions
```

### Response Example

```json theme={null}
{
    "data": [
      {
        "bank": {
          "name": "MOCK BANK INC",
          "address": {
            "city": "Mock City",
            "state": "MC",
            "street": "123 Mock Street",
            "country": "US",
            "postalCode": "12345"
          },
          "branchCode": "001",
          "routingCode": "123456789",
          "accountNumber": "000123456789"
        },
        "type": "local",
        "assetType": "USD",
        "reference": "mock-reference",
        "accountHolder": {
          "name": "Mock Fintech LLC",
          "address": {
            "city": "Mockville",
            "state": "MV",
            "street": "456 Mock Avenue",
            "country": "US",
            "postalCode": "67890"
          },
          "taxNumber": "TAX123456"
        }
      }
    ]
}
```

## Using USD Balance for Transfers

When you want to transfer funds **from** your USD virtual account balance to another bank account (including buying other currencies like BRL), use the standard `POST /transactions` endpoint. Previously, you used a bank account ID (`bank_...`) as the source for on-ramps and off-ramps. Now, you can use your **account ID** (`acct_...`) as the source to pull from your USD balance.

### Example: Transferring from USD Balance

```bash theme={null}
curl --request POST \
  --url https://api.conduit.financial/transactions \
  --header "X-API-Key: your_api_key" \
  --header "X-API-Secret: your_api_secret" \
  --header "Content-Type: application/json" \
  --header "Api-Version: 2024-12-01" \
  --data '{
    "type": "transfer",
    "quote": "quote_2nqjHpNLK6wSNlFyMvZgX8SYeAO",
    "source": "acct_2UOcdiXWXbHdLRl3zfU2gG27yRi",
    "destination": "bank_2kezVryAA3Uw9LJYBiXUV7Pj6gu",
    "purpose": "Other"
  }'
```

<Note>
  **Key points:**

  * `source`: Use your account ID (starts with `acct_`) instead of a bank account ID (starts with `bank_`)
  * The account ID is available from `GET /customers/{customer_id}/account` or `GET /clients/{client_id}/account` responses
  * This works for both same-currency transfers and currency conversions (e.g., USD to BRL)
</Note>

### Transactions

The transaction list shows all activity specific to the virtual account — both internal (on-ramps, transfers) and external (third-party deposits and payouts). This is filtered by the virtual account payment method, not just USD currency. Refer to: [List transactions API reference](/api-reference/transactions/list-transactions) for more details.

### Important notes

<Warning>
  * Each customer has exactly one USD virtual account, linked 1:1 with their customer record
  * Domestic and international deposit instructions differ
  * Use your account ID (`acct_...`) as the source when initiating transactions from your USD balance, not a bank account ID (`bank_...`)
</Warning>

## Get Account Overview

Retrieve your account information including total USD balance across all subsidiaries.

<Warning>
  This endpoint will be deprecated in a future release. Use `GET /clients/accounts` instead.
</Warning>

```http theme={null}
GET /accounts
```

### Response Example

```json theme={null}
{
    "data": [
        {
            "id": "acct_36LY7wagchjpr4VJzpnl72k0XRT",
            "balances": {
                "available": [
                     {
                        "asset": "USD",
                        "amount": "10000.00"
                    },
                    {
                        "asset": "USDC",
                        "network": "ethereum",
                        "amount": "0"
                    }
                ]
            },
            "createdAt": "2025-12-03T18:39:14.960Z"
        }
    ]
}
```

## Get All Client Accounts

Retrieve a summary of your account as well as your subsidiaries' accounts with their account IDs and balances. Includes total balances aggregated across all subsidiaries.

```http theme={null}
GET /clients/accounts
```

### Response Example

```json theme={null}
{
  "data": [
    {
      "id": "client_2fb9ADpfgEEaM4SysFUBlg290HY",
      "balances": {
        "available": [
          {
            "asset": "USD",
            "amount": "0"
          }
        ]
      },
      "createdAt": "2024-04-25T13:56:13.872Z",
      "accountId": "acct_36ZdIN1OQufNaZkf7bDBxP9E7Dp"
    }
  ],
  "totalBalances": {
    "available": [
      {
        "asset": "USD",
        "amount": "0.00"
      }
    ]
  }
}
```

## Get All Customer Accounts

Retrieve a summary of all customer accounts with their account IDs and balances. Includes total balances aggregated across all customers.

```http theme={null}
GET /customers/accounts
```

### Response Example

```json theme={null}
{
  "data": [
    {
      "id": "cus_2fb9ADpfgEEaM4SysFUBlg290HY",
      "balances": {
        "available": [
          {
            "asset": "USD",
            "amount": "0"
          }
        ]
      },
      "createdAt": "2024-04-25T13:56:13.872Z",
      "accountId": "acct_36ZdIN1OQufNaZkf7bDBxP9E7Dp"
    }
  ],
  "totalBalances": {
    "available": [
      {
        "asset": "USD",
        "amount": "0.00"
      }
    ]
  }
}
```

## Get Client Account

Retrieve the USD balance for your USD virtual account. If you have multiple subsidiaries onboarded, you can use this endpoint to retrieve the USD balance for a specific client account.

<Note>
  The API treats every client account as a subsidiary, including direct business entities
</Note>

```http theme={null}
GET /clients/{client_id}/account
```

### Response Example

```json theme={null}
{
  "id": "acct_36ZdIN1OQufNaZkf7bDBxP9E7Dp",
  "balances": {
    "available": [
      {
        "asset": "USD",
        "amount": "0.00"
      }
    ]
  }
}
```

## Get Customer Account

Retrieve the USD balance for a specific customer (end user). Each customer has exactly one account.

```http theme={null}
GET /customers/{customer_id}/account
```

### Response Example

```json theme={null}
{
  "id": "acct_36ZdIN1OQufNaZkf7bDBxP9E7Dp",
  "balances": {
    "available": [
      {
        "asset": "USD",
        "amount": "0.00"
      }
    ]
  }
}
```

## Summary

You have successfully learned how to manage USD balances in virtual accounts using Conduit's API.

**What just happened:**

* You shared deposit instructions with senders for both domestic and international transfers.
* You used USD balances as the source for transfers and currency conversions.
* You retrieved USD balances for clients and customers.

## What's next?

* Learn about Virtual Accounts: [Virtual Accounts](/core-concepts/virtual-accounts)
* Understand funding and payouts: [Payment Methods](/core-concepts/payment-methods)

## Support

Reach out to our [support team](https://support.conduitpay.com/) to get help and share your feedback.