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

# Manage customers and crypto wallet addresses

> Create one customer per user, generate deposit addresses per coin and network, and read balances and customer lists with the Bitliva Merchant API.

A customer in the Bitliva Merchant API represents one user of yours. Each customer holds crypto balances and has a deposit address for every coin and network you generate for them.

## Create a customer

Send your own id for the user as `reference`, plus a first and last name. The `reference` accepts up to 100 letters, numbers and `. _ : @ -`. Sending the same reference again returns the same customer, so it is safe to retry.

```bash theme={null}
curl -X POST https://merchant.bitliva.com/api/v1/customers \
  -H "Authorization: Bearer $BITLIVA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"reference": "user_1042", "first_name": "Ada", "last_name": "Obi"}'
```

Names can be up to 60 characters each. If a customer is still being set up, you get `customer_pending`: retry in a moment with the same reference. The sandbox allows 5 customers, after which you get `customer_limit_reached`.

## Generate a wallet address

A customer receives a coin on an address that you create for a coin and its network. The `network` is required for every coin and must match the coin. Repeating the same coin and network returns the existing address instead of creating a new one.

| Coin | `currency` | `network` |
| - | - | - |
| Bitcoin | `btc` | Required: `bitcoin` |
| Ethereum | `eth` | Required: `erc20` |
| Solana | `sol` | Required: `solana` |
| Tron | `trx` | Required: `trc20` |
| BNB | `bnb` | Required: `bep20` |
| Litecoin | `ltc` | Required: `ltc` |
| Tether | `usdt` | Required: `trc20`, `bep20`, `erc20` or `solana` |
| USD Coin | `usdc` | Required: `bep20`, `erc20`, `polygon` or `solana` |

```bash theme={null}
curl -X POST https://merchant.bitliva.com/api/v1/customers/$CUSTOMER_ID/wallets \
  -H "Authorization: Bearer $BITLIVA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"currency": "usdt", "network": "trc20"}'
```

An unsupported coin returns `unsupported_currency`, and a missing or wrong network for that coin returns `invalid_network`. The address list and every wallet in a response include its `network`.

> [!TIP]
>
> Generate the address before you try to buy that coin for a customer. Buying without one returns `address_required`.

## Read customers, addresses and balances

* [Get a customer](https://docs.bitliva.com/api-reference/customers-get.md) returns the customer with their wallet addresses.
* [List a customer's addresses](https://docs.bitliva.com/api-reference/wallets-list.md) returns all of their addresses.
* [A customer's crypto balances](https://docs.bitliva.com/api-reference/customers-balances.md) returns the current balance per coin as a string.

## Paginate customer lists

[List customers](https://docs.bitliva.com/api-reference/customers-list.md) accepts `per_page` (between 1 and 100, default 20) and `page`. The response includes a `pagination` object:

```json theme={null}
"pagination": {
  "page": 1,
  "per_page": 20,
  "total": 1,
  "last_page": 1
}
```

When a deposit reaches one of these addresses, Bitliva sends a [`crypto.deposit.received` webhook](https://docs.bitliva.com/guides/webhooks).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.