Skip to main content
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
  • You have reviewed our Virtual USD Accounts Core Concepts

​
What you can do

Hold USD

Maintain a USD balance in your named virtual account

View balance

See your available USD at any time

Receive deposits

Share deposit instructions to accept funds from first-party or third-party senders

View transactions

See an itemized list of all credits and debits specific to your virtual account

Transfer or convert

Use your USD balance as the source for transfers and currency conversions

​
Deposits

Deposits are automatically credited to your virtual account.. There’s no need to create a transaction for first party deposits. It is still strongly encouraged to create 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. 
GET /customers/{customer_id}/account/deposit-instructions

​
Response Example

{
    "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 as the client have a USD VA with us, you can retrieve bank details to share with senders from here. If you have onboarded multiple subsidiaries, you can pass the client_idfor one of your particular subsidiary’s account deposit instructions. 
GET /clients/{client_id}/account/deposit-instructions

​
Response Example

{
    "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

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"
  }'
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)

​
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 for more details.

​
Important notes

  • 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_...)

​
Get Account Overview

Retrieve your account information including total USD balance across all subsidiaries.
This endpoint will be deprecated in a future release. Use GET /clients/accounts instead.
GET /accounts

​
Response Example

{
    "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 (you as the client) as well as your subsidiaries’ accounts with their account IDs, balances, and deposit instructions. Includes total balances aggregated across all subsidiaries. 
GET /clients/accounts

​
Response Example

{
  "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. 
GET /customers/accounts

​
Response Example

{
  "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 USD balance for your USD VA account. If you have multiple subsidiaries onboarded, you can use this endpoint to retrieve the USD balance for a specific client account of yours.
The API treats every client account as a subsidiary, including direct business entities
GET /clients/{client_id}/account

​
Response Example

{
  "id": "acct_36ZdIN1OQufNaZkf7bDBxP9E7Dp",
  "balances": {
    "available": [
      {
        "asset": "USD",
        "amount": "0.00"
      }
    ]
  }
}

​
Get Customer Account

Retrieve USD balance for a specific customer (end user). Each customer has exactly one account. 
GET /customers/{customer_id}/account

​
Response Example

{
  "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?

​
Support

Reach out to our support team to get help and share your feedback.