How Recovery Works
Guardians, the 72-hour protection window and recovery contacts.
Recovery replaces a lost passkey with a new one on the wallet's Safe, on every EVM network the wallet uses.
new deviceattestation or coderecovery.startedrecovery.completedcan cancelWhich wallets can be recovered
| Wallet | Recovery |
|---|---|
| EVM, non-treasury | Yes, once enrolled with a guardian. |
| EVM treasury needing one approval | Yes, once enrolled. |
| EVM treasury needing more than one approval | No. Add or remove signers instead. |
Your responsibilities: enrol each wallet, set and verify a recovery contact, and confirm the customer's identity before you attest to a recovery.
1. Enrol the wallet
A wallet can be recovered only once it has a guardian. Enrol it with the customer's passkey:
- Enrol customer guardian: one approval covers every network.
- Enrol guardian: per wallet, one approval per network.
Get guardians shows which networks are enrolled. Treasury wallets that need more than one approval cannot be enrolled.
2. Set a recovery contact
A recovery contact is an address the customer confirms. It is how the customer hears about a recovery, even one your business did not start, and how they can still recover if your business stops operating.
- Request contact challenge, for the customer to sign with their passkey.
- Set recovery contact. You receive a verification token.
- Deliver the token to the customer through your own channel.
- Verify recovery contact once they confirm it arrived.
Check contact coverage lists which of your wallets have a verified contact.
3. Recover
Register a new passkey on the customer's new device, then authorise the recovery in one of two ways:
| Way | How |
|---|---|
| Business attests | Your business signs a verification attestation for the customer. |
| One-time code | Send recovery code delivers a six-digit code to you to pass on; Verify recovery code exchanges it for a single-use token. Needs a verified recovery contact. |
Then Start recovery.
Business attestation
Send verification as { payload, signatureB64 }:
| Field | Value |
|---|---|
businessId | Your business. |
customerId | The customer being recovered. |
walletId | The wallet, as in the request. |
newSignerAddress | The address of the customer's new passkey. |
chains | The networks to recover, as in the request. |
intent | "recovery". |
nonce | A unique string. |
issuedAt, expiresAt | Epoch milliseconds; at most 15 minutes apart. |
Sign the canonical JSON of payload (keys sorted at every level, no spaces) with your business's Ed25519 key, and send the signature base64-encoded as signatureB64. Register the matching public key in the dashboard first. The payload must match the request exactly, or the recovery is refused with 401.
4. The 72-hour protection window
A recovery waits 72 hours before it completes. During that time the real owner can cancel it with the cancellation token or their passkey: Cancel recovery. Get recovery shows its state on each network.
Events: recovery.started, recovery.reminder, recovery.completed, recovery.cancelled and recovery.failed.
Rotating or turning off recovery
- Rotate guardian moves the wallet to a new guardian.
- Revoke guardian turns recovery off. Tell the customer first: once it is off, a lost passkey means a lost wallet.
Both need the customer's passkey.
Errors
| Code | Status | Cause |
|---|---|---|
unauthorized | 401 | The business attestation is invalid, expired, or does not match the request. |
forbidden | 403 | Revoking with a passkey that does not own the wallet. |
recovery_contact_required | 422 | Recovery by one-time code was started for a customer without a verified recovery contact. |
recovery_contact_unavailable | 422 | Recovery contacts are switched off on the platform. |
validation_failed | 422 | A recovery code was requested but no endpoint subscribes to recovery.code. |
chain_unavailable | 502 | Enrolling, rotating or revoking failed on a network: for example the wallet was never enrolled, the new guardian is already registered, or the treasury needs more than one approval. detail says which. |