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.

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

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.

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 returns the customer with their wallet addresses.
• List a customer’s addresses returns all of their addresses.
• A customer’s crypto balances returns the current balance per coin as a string.

Paginate customer lists

List customers accepts per_page (between 1 and 100, default 20) and page. The response includes a pagination object:

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