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

# Cookbook: User Balance Deposits

> Map users to permanent deposit addresses and credit balances from verified events.

## Goal

Each end user has a durable deposit address. When they send crypto, you credit their in-app balance after ZBX confirms the payment via signed webhooks.

## 1. Foundation

1. [Create virtual account](/settlement/virtual-accounts) with chains/currencies you support
2. Store API key + request signing secret
3. Implement [webhook signature verification](/webhooks/verify-signatures)

## 2. On user signup

Generate a deposit address for each chain you show in the UI:

```bash theme={null}
curl -X POST "https://mapi.zbx.boomfi.xyz/v1/accounts/virtual/payin/address" \
  -H "X-API-KEY: sk_test_xxx" \
  -H "Content-Type: application/json" \
  -H "X-API-Nonce: ${NONCE}" \
  -H "X-API-Signature: ${SIG}" \
  -d "{\"chain_id\": 8453, \"reference\": \"user_${INTERNAL_USER_ID}\"}"
```

Save `address` → `user_id` → `chain_id` in your database.

## 3. Wallet UI

* Show address (and QR) only for the selected network
* Copy labels from [Networks and Currencies](/pricing/networks-and-currencies)
* Warn that wrong-chain or wrong-token transfers may be unrecoverable

## 4. Webhook credit rule

On verified `Payment.Updated` (or related payment event) with a successful status:

1. Map payment customer / reference back to your user
2. Idempotently apply ledger credit by payment id
3. Optionally notify the user

Never credit solely because funds appear on-chain without a platform payment event.

## 5. Balances and ops

* Merchant balances: `GET https://mapi.zbx.boomfi.xyz/v1/accounts/virtual/balances`
* Dashboard: `https://merchants.zbx.boomfi.xyz/dashboard/account` and transactions
* Failed webhooks: [Event History and Replay](/webhooks/event-history-and-replay)

## 6. Withdrawals / payouts (optional)

If users can cash out, use the virtual-account payout API (`POST /accounts/virtual/payout/address` with request signing) and apply your own risk controls.