# Create Wallet

Generate a new blockchain wallet for the authenticated user — either custodial (key managed by Aurea) or non-custodial (user-controlled key). Wallets are cross-chain and any network or token can be supported upon request.

## Overview

Aurea supports two wallet models to fit different regulatory and product requirements:

- **Custodial wallets** — Aurea generates and securely stores the private key on behalf of the user. Designed for **regulated entities** (banks, EMIs, licensed custodians) that need full key custody and compliance controls. Your application never touches the private key.
- **Non-custodial wallets** — Available to **everyone**. The private key is generated client-side and held by the user. Aurea manages wallet metadata and blockchain interactions without ever having access to the key.

This endpoint provisions a new managed (custodial) wallet on the specified blockchain. For non-custodial wallet import, use **Import Wallet** instead.

> ⚠️ Tenants configured for **MPC (2-of-3)** wallets (`walletMode: "mpc"`) or **non-custodial** wallets cannot mint a server-held key here — this endpoint returns `400`. Use **Start DKG Ceremony** (MPC) or **Register Client Wallet** (non-custodial) instead. This guarantees an MPC/non-custodial tenant never silently receives a custodial key.

A user can have multiple wallets across different chains. Set `isPrimary: true` to make this the default wallet for QR code payments. Each user can only have one primary wallet at a time — setting a new one automatically demotes the previous primary.

Use `isTestnet: true` to create wallets on test networks (Sepolia, Mumbai, etc.) for development and integration testing.

> 💡 Aurea is natively **cross-chain**. The chains listed below are available by default. Any other blockchain network or token in the market can be enabled for your tenant upon request.

### `POST /v1/wallets/`

Authentication: bearer token required.

Creates a new custodial wallet on the specified blockchain.

**Request body**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `chain` | string | yes | Chain identifier: ethereum, polygon, bsc, arbitrum, optimism, gnosis, base, avalanche, celo, flowevm, solana — or any chain enabled for your tenant. A testnet's chain registry id (e.g. `polygon-amoy`) is also accepted: the wallet is stored under the family chain (`polygon`) with `isTestnet: true`. |
| `name` | string | no | Friendly label for this wallet |
| `isPrimary` | boolean | no | Mark as the user's primary wallet (default: false) |
| `isTestnet` | boolean | no | Create on a test network (default: false) |

**Responses**

`201` Created

```json
{
  "id": "wallet-uuid",
  "chain": "ethereum",
  "address": "0xAbCd...",
  "label": "My ETH Wallet",
  "walletType": "managed",
  "isPrimary": false,
  "isWatchOnly": false,
  "isTestnet": false,
  "created_at": "2024-01-15T10:00:00Z"
}
```

`400` Bad Request

```json
{ "detail": "Unsupported chain: 'bitcoin'" }
```

**Example request**

```bash
curl -X POST https://api.aureahub.com/v1/wallets/ \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"chain": "ethereum", "name": "My ETH Wallet", "isPrimary": true}'
```

## Supported Chains

The following chains are available by default. Any blockchain network or token in the market can be added upon request.

ethereum polygon bsc arbitrum optimism base avalanche celo flowevm gnosis solana

Use `GET /v1/tokens/meta/chains` to fetch the authoritative list of chains enabled for your tenant at runtime.

## Implementation

```javascript
// Create a new wallet for the authenticated user
async function createWallet(token, chain, label, isPrimary = false) {
  const res = await fetch('https://api.aureahub.com/v1/wallets/', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': `Bearer ${token}`
    },
    body: JSON.stringify({ chain, name: label, isPrimary })
  });

  if (!res.ok) {
    const err = await res.json();
    throw new Error(err.detail || 'Failed to create wallet');
  }

  return res.json(); // { id, chain, address, label, isPrimary, ... }
}

// Provision wallets on multiple chains at once
async function setupMultiChainWallets(token) {
  const chains = ['ethereum', 'polygon', 'solana'];
  const wallets = await Promise.all(
    chains.map((chain, i) =>
      createWallet(token, chain, `My ${chain} wallet`, i === 0)
    )
  );
  console.log('Created wallets:', wallets.map(w => w.address));
  return wallets;
}
```

---

Web version: https://docs.aureahub.com/#wallets-create