# Restart a Pending Wallet

Give up a wallet whose setup never finished — its device share lost, its backup never kept — so that a new key generation can make another. Nothing is deleted.

## Overview

- Only a pending wallet: its setup not complete and its backup not confirmed (otherwise `409` `MPC_WALLET_NOT_PENDING`). Its balance is read on every chain first: a wallet that holds funds is never retired (`409` `MPC_WALLET_NOT_EMPTY`); a balance that cannot be read answers `503` `MPC_WALLET_BALANCE_UNVERIFIED`.
- The wallet becomes `retired` (`retiredReason` `restart`), your server hears `wallet.setup.retired`, and the answer's `restartsLeft` says how many more restarts the user has in the last 24 hours. Then start a new key generation ([Start DKG Ceremony](https://docs.aureahub.com/docs/mpc-dkg-start.md)).
- Three restarts per user in 24 hours by default; past them `429` `MPC_WALLET_RESTART_LIMIT` with `Retry-After` and [help@aureahub.com](mailto:help@aureahub.com).
- Every tenant has one wallet in setup per user and purpose ([MPC Wallet Setup › Resume After a Reload](https://docs.aureahub.com/docs/guide-wallet-setup.md)); only where those rules are off for your tenant: `403` `MPC_WALLET_SETUP_RULES_OFF`.
- The wallet's own user only: `403` `MPC_WALLET_NOT_OWNED`, `404` `MPC_WALLET_NOT_FOUND`.

## Endpoint

### `POST /v1/mpc/wallets/{walletId}/restart`

Authentication: bearer token required.

Retires the caller's pending MPC wallet after its balance reads zero on every chain.

**Path parameters**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `walletId` | string (uuid) | yes | The pending MPC wallet's id |

**Responses**

`200` Retired

```json
{
  "setup": { "walletId": "7c1e9b24-3f5a-4d8e-9b6c-1a2f3e4d5c6b", "state": "retired", "nextStep": "create_wallet", "retiredReason": "restart", "sharesKeptUntil": "2027-02-03T09:40:00.000Z", "…": "…" },
  "restartsLeft": 2
}
```

`409` Holds Funds

```json
{
  "statusCode": 409,
  "error": "ConflictError",
  "message": "…",
  "details": { "code": "MPC_WALLET_NOT_EMPTY" }
}
```

**Example request**

```bash
curl -X POST https://api.aureahub.com/v1/mpc/wallets/7c1e9b24-3f5a-4d8e-9b6c-1a2f3e4d5c6b/restart \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
```

---

Web version: https://docs.aureahub.com/#mpc-wallet-restart