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

# Create a Deposit Address

> Create a permanent pay-in crypto wallet for a customer reference.

`POST /accounts/virtual/payin/address` creates a permanent pay-in wallet under the merchant’s virtual account. Deposits are swept to the parent account.

## Request

Requires API key and request signature when signature verification is enforced.

```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-unique-1" \
  -H "X-API-Signature: <hmac-hex>" \
  -d '{
    "chain_id": 8453,
    "reference": "customer-123"
  }'
```

### Fields

| Field       | Required | Description                                                                                                       |
| ----------- | -------- | ----------------------------------------------------------------------------------------------------------------- |
| `reference` | Yes      | Your stable user/customer id for this sub-account                                                                 |
| `chain_id`  | Yes      | Chain id (for example `8453` Base, `1` Ethereum). See [Networks and Currencies](/pricing/networks-and-currencies) |

The parent virtual account must exist, be enabled, and in **Ready** state. The chain must be enabled on the platform.

## Response (shape)

| Field        | Description                       |
| ------------ | --------------------------------- |
| `account_id` | Sub-account id                    |
| `reference`  | Echo of your reference            |
| `chain_id`   | Chain                             |
| `address`    | On-chain address to show the user |
| `status`     | Account state                     |
| `enabled`    | Whether deposits are enabled      |

Persist `address` and `account_id` next to your user record. Creating again for the same reference/chain returns the existing wallet when already provisioned (idempotent behaviour from the account store).

## Request signing

Build `X-API-Signature` as described in [Authentication](/authentication):

`HMAC_SHA256(secret, METHOD + PATH + NONCE + QUERY + BODY)`.

## Show address to users

Display the address only for the **chosen chain**. Educate users not to send assets from incompatible networks.

## Credit your ledger

Watch for payment webhooks involving deposit payment methods / successful payments tied to that customer, and verify signatures. Prefer a conservative rule: **credit only on successful, verified payment events** that match your `reference` / customer mapping.

## Next step

[Cookbook: User Balance Deposits](/deposits/cookbook-user-balance)