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 with chains/currencies you support
2. Store API key + request signing secret
3. Implement webhook signature verification

2. On user signup

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

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
• 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

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.