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

# Virtual Accounts

> Create and manage the org virtual account hierarchy, balances, and chains.

A virtual account is the org’s managed wallet hierarchy: a primary account (empty `reference`) with crypto wallets on enabled chains, plus optional pay-in sub-accounts for permanent deposit addresses.

## Create the virtual account

```bash theme={null}
curl -X POST "https://mapi.zbx.boomfi.xyz/v1/accounts/virtual" \
  -H "X-API-KEY: sk_test_xxx" \
  -H "Content-Type: application/json" \
  -H "X-API-Nonce: nonce-$(date +%s)" \
  -H "X-API-Signature: <hmac>" \
  -d '{
    "chains": [
      { "chain_id": 8453, "currencies": ["USDC", "ETH"] }
    ]
  }'
```

<Note>
  Virtual-account write endpoints require request signing when signature verification is enforced. See [Authentication](/authentication).
</Note>

## Get virtual account

```bash theme={null}
curl "https://mapi.zbx.boomfi.xyz/v1/accounts/virtual" \
  -H "X-API-KEY: sk_test_xxx"
```

Returns the primary virtual account and nested structure (chains, addresses, state). The parent must be **enabled** and in a **Ready** state before you create pay-in deposit wallets.

## Update virtual account

Enable additional chains/currencies or disable existing ones via `PATCH https://mapi.zbx.boomfi.xyz/v1/accounts/virtual`.

## Balances

```bash theme={null}
curl "https://mapi.zbx.boomfi.xyz/v1/accounts/virtual/balances" \
  -H "X-API-KEY: sk_test_xxx"
```

Lists balances across the primary virtual-account hierarchy.

## Permanent pay-in wallets

Create customer deposit addresses with `POST https://mapi.zbx.boomfi.xyz/v1/accounts/virtual/payin/address`. Deposits on those addresses are swept to the parent account. Full guide: [Create a Deposit Address](/deposits/create-address).

## Dashboard

* Settlement: `https://merchants.zbx.boomfi.xyz/dashboard/settings/settlement`
* Account balances UI: `https://merchants.zbx.boomfi.xyz/dashboard/account`

<img src="https://mintcdn.com/zbx/Gd3Le6ZnOklhItBk/settlement/images/virtual-account-balances-zbx.png?fit=max&auto=format&n=Gd3Le6ZnOklhItBk&q=85&s=6251408aa4878a454b6c4f6ac731078d" alt="ZBX virtual account balances" width="1440" height="900" data-path="settlement/images/virtual-account-balances-zbx.png" />

## Payouts from the virtual account

`POST https://mapi.zbx.boomfi.xyz/v1/accounts/virtual/payout/address` creates a payout to an external wallet (signed; session auth may require step-up). See the API reference for the full request schema.

## Next steps

* [Deposit Accounts Overview](/deposits/overview)
* [Payment Links](/payments/paylinks)