# Import Wallet

Bring an existing self-custodied wallet into Aurea's managed system using a private key or mnemonic phrase.

## Overview

Use this endpoint when a user already has a blockchain wallet they want to manage through Aurea without creating a new one. Provide either a `privateKey` (64-character hex) or a `mnemonic` (BIP-39, 12 or 24 words). For HD wallets, optionally specify a `derivationPath` and `accountIndex`.

You can also import a **watch-only** wallet by providing just the address (set `watchOnly: true`). Watch-only wallets can receive funds and have their balance queried, but cannot sign transactions.

> ⚠️ **Security critical:** Private keys and mnemonics grant full control of a wallet. Only accept these from users directly in your UI — never log, cache, or proxy them through your own servers. Always enforce HTTPS.

### `POST /v1/wallets/import`

Authentication: bearer token required.

Imports an existing wallet into Aurea via private key, mnemonic, or watch-only address.

**Request body**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `chain` | string | yes | Blockchain identifier (e.g. ethereum). A testnet's chain registry id (e.g. `celo-sepolia`) is also accepted: the wallet is stored under the family chain (`celo`) with `isTestnet: true`. |
| `privateKey` | string | no | 64-char hex private key (provide this OR mnemonic) |
| `mnemonic` | string | no | BIP-39 mnemonic phrase, 12 or 24 words |
| `derivationPath` | string | no | BIP-44 derivation path (e.g. m/44'/60'/0'/0/0) |
| `accountIndex` | integer | no | HD wallet account index (default: 0) |
| `label` | string | no | Friendly label for this wallet |
| `watchOnly` | boolean | no | Import as watch-only (provide address instead of key) |
| `address` | string | no | Wallet address (required when watchOnly: true) |
| `isPrimary` | boolean | no | Set as primary wallet |
| `isTestnet` | boolean | no | Import on testnet (default: false) |

**Responses**

`201` Created

```json
{
  "id": "wallet-uuid",
  "chain": "ethereum",
  "address": "0xAbCd...",
  "label": "My Imported Wallet",
  "walletType": "imported",
  "isPrimary": false,
  "isWatchOnly": false
}
```

`400` Bad Request

```json
{ "detail": "Invalid private key format" }
```

## Implementation

```javascript
// Import by private key
async function importWalletByKey(token, chain, privateKey, label) {
  const res = await fetch('https://api.aureahub.com/v1/wallets/import', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': `Bearer ${token}`
    },
    body: JSON.stringify({ chain, privateKey, label })
  });
  if (!res.ok) throw new Error((await res.json()).detail);
  return res.json();
}

// Import by mnemonic (HD wallet, first account)
async function importWalletByMnemonic(token, chain, mnemonic, label) {
  const res = await fetch('https://api.aureahub.com/v1/wallets/import', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': `Bearer ${token}`
    },
    body: JSON.stringify({
      chain,
      mnemonic,
      derivationPath: "m/44'/60'/0'/0/0",
      label
    })
  });
  if (!res.ok) throw new Error((await res.json()).detail);
  return res.json();
}

// Import watch-only (read balance, can't send)
async function importWatchOnlyWallet(token, chain, address) {
  const res = await fetch('https://api.aureahub.com/v1/wallets/import', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': `Bearer ${token}`
    },
    body: JSON.stringify({ chain, address, watchOnly: true })
  });
  if (!res.ok) throw new Error((await res.json()).detail);
  return res.json();
}
```

---

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