# Set Primary Wallet

Mark a wallet as the user's primary wallet for its chain and network type (mainnet or testnet).

## Overview

A user has at most one primary wallet per chain and network type. The request body must be `{ "isPrimary": true }` — sending `false` returns `400`, because a primary wallet cannot be unset directly; promote another wallet instead.

- If the wallet is already primary, it is returned unchanged.
- Otherwise the wallet is set as primary, and a database trigger demotes the user's previous primary wallet on the same chain and network type.
- An unknown id, or a wallet that belongs to another user, returns `404`.
- New wallets can already be primary: `POST /v1/wallets/` makes a wallet primary when the user has no primary wallet on that chain and network type, and `POST /v1/wallets/client` does so for the user's first wallet there (unless `isPrimary` is passed).

To make the wallet the user's *only* primary wallet across all chains of its network type, use [Set Primary (atomic)](https://docs.aureahub.com/docs/wallets-set-primary.md).

## Endpoint

### `PATCH /v1/wallets/{id}/primary`

Authentication: bearer token required.

Sets the wallet as primary for its chain and network type.

**Path parameters**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string (uuid) | yes | Wallet to promote. |

**Request body**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `isPrimary` | boolean | yes | Must be `true`. |

**Responses**

`200` OK

```json
{
  "id": "3f8b2a1e-5c4d-4e7f-9a0b-1c2d3e4f5a6b",
  "chain": "gnosis",
  "address": "0x71C7656EC7ab88b098defB751B7401B5f6d8976F",
  "walletType": "eoa",
  "isPrimary": true,
  "isTestnet": false,
  "label": "Main",
  "isWatchOnly": false,
  "keyManagementScheme": "sss_2of2_akv",
  "createdAt": "2026-09-01T08:00:00.000Z",
  "updatedAt": "2026-09-11T10:00:00.000Z"
}
```

`400` Bad Request

```json
{
  "error": "BAD_REQUEST",
  "message": "isPrimary must be true. To unset primary, set another wallet as primary."
}
```

`404` Not Found

```json
{
  "error": "NotFoundError",
  "message": "Wallet not found"
}
```

**Example request**

```bash
curl -X PATCH https://api.aureahub.com/v1/wallets/WALLET_ID/primary \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"isPrimary": true}'
```

## Implementation

```javascript
// Promote a wallet from a wallet-settings screen
async function setPrimaryWallet(token, walletId) {
  const res = await fetch(
    `https://api.aureahub.com/v1/wallets/${walletId}/primary`,
    {
      method: 'PATCH',
      headers: { Authorization: `Bearer ${token}`, 'Content-Type': 'application/json' },
      body: JSON.stringify({ isPrimary: true })
    }
  );
  if (!res.ok) {
    const err = await res.json();
    throw new Error(err.message || 'Failed to update primary wallet');
  }
  return res.json(); // wallet object with isPrimary: true
}
```

---

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