Recovery - Integration Guide

This guide explains how to enable and manage wallet recovery for your users. Recovery allows users to regain access to their wallet in case of passkey loss or device failure.

📊 View Flow Diagram

1. Enable Recovery

Enabling recovery requires two steps: first, prepare the recovery operation, then sign it with a passkey.

Step 1: Prepare Recovery Operation

Endpoint : POST /v1.2/safes/operations

Headers :

Authorization: Bearer <access_token> (required)

Body (JSON) :

safeAddress (string, required) : Safe address for which to enable recovery
operations (array, required) : Array containing an operation of type ENABLE_RECOVERY

ENABLE_RECOVERY Operation :

type (string, required) : "ENABLE_RECOVERY"
firstName (string, required) : First name for personal data
lastName (string, required) : Last name for personal data
birthDate (string, required) : Birth date in YYYY-MM-DD format
birthCity (string, required) : Birth city
birthCountry (string, required) : Birth country

Request Example :

POST /v1.2/safes/operations
Content-Type: application/json
Authorization: Bearer <access_token>

{
  "safeAddress": "0xd676c6188195372EC269E9C2cAf815C56436A679",
  "operations": [
    {
      "type": "ENABLE_RECOVERY",
      "firstName": "Jane",
      "lastName": "Doe",
      "birthDate": "1990-01-01",
      "birthCity": "Paris",
      "birthCountry": "France"
    }
  ]
}

Response (200 OK) :

{
  "credentialRequestOptions": {
    "challenge": "<base64url_encoded_userOpHash>",
    "rpId": "foo.domain",
    "userVerification": "required",
    "timeout": 60000,
    "allowCredentials": [
      {
        "id": "<base64url>",
        "type": "public-key"
      }
    ]
  },
  "data": {
    "userOpHash": "0xabc...123"
  }
}

💾 To Store :

credentialRequestOptions : WebAuthn options needed for passkey signature
data.userOpHash : Operation hash for tracking status

Step 2: Sign Recovery Operation

Endpoint : PUT /v1.2/safes/operations

Headers :

Authorization: Bearer <access_token> (required)

Body (JSON) :

credential (object, required) : WebAuthn credential obtained via navigator.credentials.get() with the options from step 1

Request Example :

PUT /v1.2/safes/operations
Content-Type: application/json
Authorization: Bearer <access_token>

{
  "credential": {
    "id": "AVZs0qRCBSmfThZWu37g...",
    "rawId": "AVZs0qRCBSmfThZWu37g...",
    "type": "public-key",
    "response": {
      "authenticatorData": "SZYN5YgOjGh0NBcPZHZgW4/krrmihjLHmVzzuoMdl2MFAAAAAQ...",
      "clientDataJSON": "eyJ0eXBlIjoid2ViYXV0aG4uZ2V0IiwiY2hhbGxlbmdlIjoi...",
      "signature": "MEUCIQC..."
    }
  }
}

Response (200 OK) :

{
  "userOpHash": "0xabc...123",
  "status": "SIGNED",
  "safeAddress": "0xd676c6188195372EC269E9C2cAf815C56436A679"
}

💡 Note : After signing, the operation status becomes SIGNED, then EXECUTED when the bundler submits it to the blockchain, and finally CONFIRMED after block confirmations. Recovery requires a delay (default 1 day = 86400 seconds) before it can be executed. Final execution is performed by the IBEX team via an administrative endpoint after the delay expires.

2. Check Recovery Status

You can check the recovery status of a Safe to see if recovery is enabled, pending, or can be executed.

Endpoint : GET /v1.1/recovery/status/:safeAddress

Headers :

Authorization: Bearer <access_token> (required)

Path Parameters :

safeAddress (string, required) : Safe address (EVM format, case-insensitive)

Request Example :

GET /v1.1/recovery/status/0xd676c6188195372EC269E9C2cAf815C56436A679
Authorization: Bearer <access_token>

Response (200 OK) :

{
  "safeAddress": "0xd676c6188195372EC269E9C2cAf815C56436A679",
  "recoveryEnabled": true,
  "recoveryAddress": "0x303f215950f7B07Ae45FD98590d503E0242E7de3",
  "delay": 86400,
  "pendingRecovery": false,
  "canExecute": false,
  "executeAfter": null,
  "dataRecovery": true,
  "pending": [],
  "executed": [
    {
      "userOpHash": "0xdef...456",
      "transactionHash": "0x789...abc",
      "status": "EXECUTED",
      "createdAt": "2025-08-24T16:58:20.100Z",
      "updatedAt": "2025-08-24T16:59:10.450Z"
    }
  ]
}

📋 Response Fields :

recoveryEnabled : Whether recovery is currently enabled on the Safe
recoveryAddress : Address of the recovery guardian (if enabled)
delay : Recovery delay in seconds (default: 86400 = 1 day)
pendingRecovery : Whether there's a pending recovery operation
canExecute : Whether recovery can be executed (after delay expires)
executeAfter : Timestamp when recovery can be executed (if pending)
dataRecovery : Whether IBEX Safe holds recovery data for this address
pending : Array of pending recovery operations (status: CREATED, SIGNED)
executed : Array of executed recovery operations (status: EXECUTED, CONFIRMED)

3. Cancel Recovery

If a user wants to cancel an ongoing recovery operation, they can use the CANCEL_RECOVERY operation.

Step 1: Prepare Cancel Recovery Operation

Endpoint : POST /v1.2/safes/operations

Body (JSON) :

safeAddress (string, required) : Safe address
operations (array, required) : Array containing an operation of type CANCEL_RECOVERY

CANCEL_RECOVERY Operation :

type (string, required) : "CANCEL_RECOVERY"

Request Example :

POST /v1.2/safes/operations
Content-Type: application/json
Authorization: Bearer <access_token>

{
  "safeAddress": "0xd676c6188195372EC269E9C2cAf815C56436A679",
  "operations": [
    {
      "type": "CANCEL_RECOVERY"
    }
  ]
}

Response (200 OK) :

{
  "credentialRequestOptions": {
    "challenge": "<base64url_encoded_userOpHash>",
    "rpId": "foo.domain",
    "userVerification": "required",
    "timeout": 60000,
    "allowCredentials": [
      {
        "id": "<base64url>",
        "type": "public-key"
      }
    ]
  },
  "data": {
    "userOpHash": "0xdef...456"
  }
}

Step 2: Sign Cancel Recovery Operation

Endpoint : PUT /v1.2/safes/operations

Same as Step 2 of Enable Recovery. Submit the WebAuthn credential to finalize the cancellation.

Request Example :

PUT /v1.2/safes/operations
Content-Type: application/json
Authorization: Bearer <access_token>

{
  "credential": {
    "id": "AVZs0qRCBSmfThZWu37g...",
    "rawId": "AVZs0qRCBSmfThZWu37g...",
    "type": "public-key",
    "response": {
      "authenticatorData": "SZYN5YgOjGh0NBcPZHZgW4/krrmihjLHmVzzuoMdl2MFAAAAAQ...",
      "clientDataJSON": "eyJ0eXBlIjoid2ViYXV0aG4uZ2V0IiwiY2hhbGxlbmdlIjoi...",
      "signature": "MEUCIQC..."
    }
  }
}

💡 Note : Canceling recovery requires passkey authentication to ensure only the wallet owner can cancel recovery operations.

Summary of Data to Store

userOpHash : Operation hash for tracking recovery operation status
recoveryEnabled : Whether recovery is enabled on the Safe
recoveryAddress : Address of the recovery guardian (if enabled)
delay : Recovery delay in seconds
canExecute : Whether recovery can be executed (after delay)
executeAfter : Timestamp when recovery can be executed

Technical Deep Dive - For AI Integration

This section provides detailed technical information for AI systems integrating the IBEX API recovery functionality.

Recovery Module Architecture

The recovery system uses a Safe module pattern:

RecoveryModule : Smart contract module deployed via CREATE2 (deterministic address)
Guardian Address : External address that can execute recovery after delay
Cooldown Period : Delay before recovery can be executed (default: 86400 seconds = 1 day)
Expiration : Maximum time window for recovery execution

ENABLE_RECOVERY Operation Flow

Step 1: POST /v1.2/safes/operations

Validates personal data (firstName, lastName, birthDate, birthCity, birthCountry)
Checks if recovery is already enabled (409 CONFLICT if already enabled)
Creates Safe user operation to:
1. Deploy RecoveryModule (if not exists) via MODULE_PROXY_FACTORY
2. Enable module on Safe via enableModule(recoveryModuleAddress)
3. Enable recovery on module via enableRecovery(guardian, cooldown, expiration)
Stores personal data in Operation.data JSON field
Returns credentialRequestOptions with challenge = userOpHash (base64url encoded)

Step 2: PUT /v1.2/safes/operations

Verifies WebAuthn credential using verifyAuthenticationResponse()
Validates challenge (userOpHash) from credential
Updates SafeOperation status to SIGNED
Bundler automatically submits userOp to blockchain (status → EXECUTED)
After execution, decodes recovery module address from transaction
Registers recovery data with Safe.ib.exchange service
Updates Safe.hasRecovery flag in database

CANCEL_RECOVERY Operation Flow

Step 1: POST /v1.2/safes/operations

Creates Safe user operation to call cancelRecovery() on RecoveryModule
Requires Safe.hasRecovery = true (recovery must be enabled)
Returns credentialRequestOptions for passkey signature

Step 2: PUT /v1.2/safes/operations

Same signature flow as ENABLE_RECOVERY
After execution, recovery is disabled on the Safe

Recovery Status Endpoint

GET /v1.1/recovery/status/:safeAddress

Queries Safe record from database (hasRecovery, recoveryModuleAddress)
Checks IBEX Safe service for recovery data (dataRecovery flag)
Fetches pending and executed SafeOperations with type ENABLE_RECOVERY or CANCEL_RECOVERY
Calculates canExecute based on delay and executeAfter timestamp
Returns comprehensive status including operation history

State Management

SafeOperation Status Flow for Recovery:

CREATED : Operation created, awaiting passkey signature
SIGNED : Passkey signature received, operation ready for bundler
EXECUTED : Bundler submitted userOp to blockchain, awaiting confirmation
CONFIRMED : Sufficient block confirmations received

Error Handling

409 CONFLICT : Attempting ENABLE_RECOVERY on Safe where recovery is already enabled
400 BAD REQUEST : Missing or invalid personal data fields
403 FORBIDDEN : User doesn't have access to the target Safe
404 NOT FOUND : Safe address not found

Key Implementation Files

src/routes/v1/safesOperations.ts : ENABLE_RECOVERY and CANCEL_RECOVERY operation handlers
src/routes/v1.1/recovery.ts : Recovery status endpoint
src/clients/IbexSafe.ts : Safe.ib.exchange service integration

← Back to Main Guide