> ## Documentation Index
> Fetch the complete documentation index at: https://docs.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.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)


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