> For the complete documentation index, see [llms.txt](https://docs.ezeebit.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.ezeebit.com/customer-accounts/overview.md).

# Overview

Give each of your customers their own USDT wallet, held under your merchant account.

Customer accounts let you offer your customers a stablecoin wallet out of the box, with nothing to build yourself. Each customer gets a USDT account under your merchant account, with its own balance, ledger, and deposit addresses: their deposits are credited to them rather than to your merchant balance, and you run every account through the same API as your own wallets.

![Customer accounts: your merchant account's fiat and USDT wallets convert and transfer with a list of USDT customer accounts, which take USDT deposits and withdraw to whitelisted addresses](https://2829083050-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FeHII0ZzCZxBOdP2AXVNa%2Fuploads%2FFXLMlyBb2oOqvxX1g4hs%2Fbrand-customer-accounts.svg?alt=media\&token=e9d8fbf2-ce2a-4c67-b021-363cda2314c7)

## How the pieces fit

**Open accounts.** [Create Customer Account](https://docs.ezeebit.com/customer-accounts/create-customer-account.md) with your own `customerAccountId` — the ID you already use for that customer, with an optional account name field.

**Use the wallet endpoints on a customer account.** Conversions and crypto withdrawals use the same endpoints as your own wallets, under Wallets and Withdrawal. Pass `customerAccountId` and the call runs against that customer account's wallet instead of your merchant account; leave it out and it uses your own wallets. Rates, fees, limits, the whitelist, and Travel Rule screening work the same way.

**Deposits.** Every account has USDT deposit addresses on Ethereum, BSC, Tron, and Solana. A deposit is credited once it is confirmed, and notifies your server on the [wallet movements webhook](https://docs.ezeebit.com/wallets-and-withdrawal/wallet-webhook.md#wallet-movements) with its `customerAccountId`.

**Transfer.** [Customer Account Transfer](https://docs.ezeebit.com/customer-accounts/customer-account-transfer.md) moves USDT between your crypto wallet and a customer account, in either direction. It is a book transfer, with nothing on chain and no fee.

**Convert.** [Request a conversion quote](https://docs.ezeebit.com/wallets-and-withdrawal/request-conversion-quote.md) with `customerAccountId`, then [accept it](https://docs.ezeebit.com/wallets-and-withdrawal/accept-conversion-quote.md) as usual. The USDT side is the customer account; the fiat side is always your own fiat wallet.

**Withdraw.** [Withdrawal Quote](https://docs.ezeebit.com/wallets-and-withdrawal/withdrawal-quote.md) and [Submit Withdrawal](https://docs.ezeebit.com/wallets-and-withdrawal/submit-withdrawal.md) with `customerAccountId` pay out of the customer account to a whitelisted on-chain address. Destinations come from your own whitelist — see [Create Whitelist Address](https://docs.ezeebit.com/wallets-and-withdrawal/create-whitelist-address.md).

**Read.** [List Customer Accounts](https://docs.ezeebit.com/customer-accounts/list-customer-accounts.md) pages through your accounts, [Customer Account Details](https://docs.ezeebit.com/customer-accounts/customer-account-details.md) returns an account's balance and deposit addresses, and [Customer Account Ledger](https://docs.ezeebit.com/customer-accounts/customer-account-ledger.md) pages its history.

## Endpoints

All `POST`, all relative to the base URL in [Environments & base URLs](https://docs.ezeebit.com/documentation/environments-and-base-urls.md).

<table><thead><tr><th width="290">Endpoint</th><th>Path</th></tr></thead><tbody><tr><td><a href="https://docs.ezeebit.com/customer-accounts/create-customer-account.md">Create Customer Account</a></td><td><code>/customerAccount/create</code></td></tr><tr><td><a href="https://docs.ezeebit.com/customer-accounts/list-customer-accounts.md">List Customer Accounts</a></td><td><code>/customerAccount/list</code></td></tr><tr><td><a href="https://docs.ezeebit.com/customer-accounts/customer-account-details.md">Customer Account Details</a></td><td><code>/customerAccount/details</code></td></tr><tr><td><a href="https://docs.ezeebit.com/customer-accounts/customer-account-ledger.md">Customer Account Ledger</a></td><td><code>/customerAccount/ledger</code></td></tr><tr><td><a href="https://docs.ezeebit.com/customer-accounts/customer-account-transfer.md">Customer Account Transfer</a></td><td><code>/customerAccount/transfer</code></td></tr></tbody></table>

### Wallet endpoints that work on a customer account

These are documented under Wallets and Withdrawal. Pass `customerAccountId` to run them against a customer account.

<table><thead><tr><th width="290">Endpoint</th><th>Path</th></tr></thead><tbody><tr><td><a href="https://docs.ezeebit.com/wallets-and-withdrawal/request-conversion-quote.md">Request Conversion Quote</a></td><td><code>/merchant/wallet/conversion/quote</code></td></tr><tr><td><a href="https://docs.ezeebit.com/wallets-and-withdrawal/accept-conversion-quote.md">Accept Conversion Quote</a></td><td><code>/merchant/wallet/conversion/accept</code> — send the <code>quoteId</code> only; the quote already names the customer account</td></tr><tr><td><a href="https://docs.ezeebit.com/wallets-and-withdrawal/withdrawal-quote.md">Withdrawal Quote</a></td><td><code>/merchant/crypto/withdrawal/quote</code></td></tr><tr><td><a href="https://docs.ezeebit.com/wallets-and-withdrawal/submit-withdrawal.md">Submit Withdrawal</a></td><td><code>/merchant/crypto/withdrawal/submit</code></td></tr><tr><td><a href="https://docs.ezeebit.com/wallets-and-withdrawal/wallet-webhook.md">Wallet Webhooks</a></td><td>Deposits and withdrawals on customer accounts arrive on the wallet movements webhook, with <code>customerAccountId</code></td></tr></tbody></table>

## Error codes

<table><thead><tr><th width="290">Code</th><th>When</th></tr></thead><tbody><tr><td><code>10121</code></td><td>Customer account not found, on any call that takes <code>customerAccountId</code></td></tr><tr><td><code>10122</code></td><td>Request Conversion Quote got both <code>sourceWalletId</code> and <code>customerAccountId</code>, or neither</td></tr><tr><td><code>10109</code>–<code>10111</code>, <code>10123</code>–<code>10126</code></td><td>Customer Account Transfer</td></tr><tr><td><code>10108</code></td><td>Customer account is frozen: no transfers, conversions, or withdrawals</td></tr></tbody></table>
