# Set Primary Wallet (atomic)

Promote a wallet to primary and demote the user's other primary wallets on the same network type in a single database transaction. No request body.

## Overview

Ownership is checked against the JWT: a wallet that belongs to another user of your tenant returns `403`, and an unknown id returns `404`. Inside one transaction the server then:

1. locks the target wallet row;
2. sets `isPrimary: false` on every other primary wallet of the same user on the same network type (mainnet or testnet);
3. sets `isPrimary: true` on the target wallet.

> ⚠️ The demotion is **not limited to the target wallet's chain**: afterwards the target is the user's only primary wallet across all chains of that network type. The endpoint's OpenAPI description mentions the same chain, but the implementation applies no chain condition. Use [Set Primary Wallet](https://docs.aureahub.com/docs/wallets-primary.md) to change the primary wallet of one chain only.

## Endpoint

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

Authentication: bearer token required.

Atomically demotes the user's other primary wallets on the same network type and promotes the target wallet.

**Path parameters**

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

**Responses**

`200` OK

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

`403` Forbidden

```json
{
  "error": "ForbiddenError",
  "message": "You do not have permission to update this wallet"
}
```

`404` Not Found

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

**Example request**

```bash
curl -X PATCH https://api.aureahub.com/v1/wallets/WALLET_ID/set-primary \
  -H "Authorization: Bearer YOUR_TOKEN"
```

## Compared with PATCH /primary

|  |  |  |
| --- | --- | --- |
| Request body | **/primary:** `{ "isPrimary": true }` required | **/set-primary:** None |
| Wallets demoted | **/primary:** Previous primary on the same chain and network type (database trigger) | **/set-primary:** All other primary wallets of the user on the same network type, on every chain |
| Another user's wallet | **/primary:** `404` | **/set-primary:** `403` |
| Already primary | **/primary:** Returned unchanged | **/set-primary:** Demotion still runs |

## Implementation

```javascript
async function makeOnlyPrimary(token, walletId) {
  const res = await fetch(
    `https://api.aureahub.com/v1/wallets/${walletId}/set-primary`,
    { method: 'PATCH', headers: { Authorization: `Bearer ${token}` } }
  );
  if (res.status === 403) throw new Error('Wallet belongs to another user');
  if (!res.ok) throw new Error((await res.json()).message);
  return res.json(); // wallet object with isPrimary: true
}
```

---

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