> ## Documentation Index
> Fetch the complete documentation index at: https://docs.minisend.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# Create a wallet

> Issue an on-chain address for one of your users, or return their existing one. Idempotent on your own reference string.

Creates an address for your `walletRef`, or returns the existing one if you've already created it. Never mints a second address for the same reference and chain.

<Warning>
  Backend only. Never call from frontend.
</Warning>

## Endpoint

```text theme={null}
POST https://merchant.minisend.xyz/api/v1/wallets
```

```text theme={null}
Authorization: Bearer wsk_live_your_key_here
```

## Body

<ParamField body="walletRef" type="string" required>
  Your own identifier for this user or wallet: 1 to 128 characters, letters, numbers, and `_ : . -`. Your own user ID works well. Unique per your account and chain.
</ParamField>

<ParamField body="chain" default="BASE" type="string">
  `BASE`, `ARB`, `AVAX`, `ETH`, `OP`, or `MATIC`. Must already be activated on your account — see [activating a chain](/wallet-api/overview#master-wallets-and-addresses).
</ParamField>

<ParamField body="metadata" type="object">
  Any JSON object. Stored alongside the wallet and returned when you fetch it later.
</ParamField>

## Example

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://merchant.minisend.xyz/api/v1/wallets \
    -H "Authorization: Bearer wsk_live_your_key_here" \
    -H "Content-Type: application/json" \
    -d '{"walletRef": "user-9214"}'
  ```

  ```javascript Node.js theme={null}
  const res = await fetch('https://merchant.minisend.xyz/api/v1/wallets', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer wsk_live_your_key_here',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ walletRef: 'user-9214' }),
  });

  if (!res.ok) throw new Error((await res.json()).error);
  const { wallet } = await res.json();
  ```

  ```python Python theme={null}
  import requests

  res = requests.post(
      "https://merchant.minisend.xyz/api/v1/wallets",
      headers={
          "Authorization": "Bearer wsk_live_your_key_here",
          "Content-Type": "application/json",
      },
      json={"walletRef": "user-9214"},
  )

  res.raise_for_status()
  wallet = res.json()["wallet"]
  ```
</CodeGroup>

## Response (201)

```json theme={null}
{
  "wallet": {
    "id": "3f6b2e1a-...",
    "tenant_id": "a7c9e2d0-...",
    "master_wallet_id": "d4f81b3c-...",
    "wallet_ref": "user-9214",
    "address": "0xabc1230000000000000000000000000000dead",
    "chain": "BASE",
    "status": "active",
    "mode": "live",
    "metadata": null,
    "created_at": "2026-07-29T09:00:00.000Z"
  }
}
```

<ResponseField name="id" type="string" required>
  Minisend's identifier for this wallet. Use it with [get wallet](/api-reference/wallet-api/get-wallet).
</ResponseField>

<ResponseField name="tenant_id" type="string" required>
  Your account identifier. The same on every wallet you create.
</ResponseField>

<ResponseField name="master_wallet_id" type="string" required>
  The master wallet this address was issued under, for the chain you requested.
</ResponseField>

<ResponseField name="wallet_ref" type="string" required>
  Echoes the reference you provided.
</ResponseField>

<ResponseField name="address" type="string" required>
  The on-chain address, lowercased.
</ResponseField>

<ResponseField name="chain" type="string" required>
  The chain this address lives on.
</ResponseField>

<ResponseField name="status" type="string" required>
  `active` or `frozen`.
</ResponseField>

<ResponseField name="mode" type="string" required>
  Always `live`. The Wallet API has no sandbox today.
</ResponseField>

<ResponseField name="metadata" type="object">
  Whatever you passed at creation, or `null`.
</ResponseField>

## Errors

| Status | Meaning                                                                                                                  |
| ------ | ------------------------------------------------------------------------------------------------------------------------ |
| `400`  | Invalid `walletRef`, unsupported `chain`, `metadata` isn't a JSON object, or `chain` isn't activated on your account yet |
| `401`  | Missing or invalid API key                                                                                               |
| `403`  | Account inactive                                                                                                         |
| `429`  | Rate limit exceeded (60 requests/minute)                                                                                 |