Skip to main content

Safe Recovery UX API

Safe Recovery UX API gives developers the ability to build smooth recovery process

  1. Alerts and Notifications: Account owners can subscribe to receive notifications via email or SMS when a recovery request is initiated on-chain.
  2. One click for Guardians: By aggregating signatures, we enable off-chain collection and automatic execution once all signatures are received.
  3. Auto Executed: A built-in relayer to submit signed transactions on behalf of guardians for both confirmation and finalization after the grace period.
  4. Social Engineering Protection: A communication system using emojis that allows guardians to verify and approve legitimate recovery requests from their rightful owners.
info

The following API is in a pre-release phase. Request access here.

/recoveries

  • /recoveries/create
    • POST: Creates a new recovery request
  • /recoveries/fetchByAddress
    • GET: Fetches recovery requests
  • /recoveries/fetchById
    • GET: Fetch a recovery request by ID
  • /recoveries/sign
    • POST: Collects a guardian siganture
  • /recoveries/execute
    • POST: Execute a recovery request by ID
  • /recoveries/finalize
    • POST: Finalize a recovery request by ID

/alerts

  • /alerts/subscribe
    • POST: Creates an inactive alerts subscription for an account
  • /alerts/activate
    • POST: Activate subscripton to recovery requests
  • /alerts/subscriptions
    • GET: Fetches active alerts subscriptions for an account.
  • /alerts/unsubscribe
    • POST: Unsubscribes from an active alerts subscription.

Recoveries​

Create recovery request​

Creates a new recovery request by a guardian with a lost signer of a Safe account. Can only be initated by guardians of the account.

POST /recoveries/create​

curl -X POST \
  https://api.candide.dev/recoveries/$version/$network/$your_api_key/create \
  -H 'Content-Type: application/json' \
  -d '{
        "account": "0xD422B9d638a7BA4eBeF9e33Af9456007eAB4ccba",
        "newOwners": ["0x41153290c995c8c4410d50f95D87ee86A1B07eeC", "0xB97A1C3993A551f0Febf030539630ACb77E6832D"],
        "newThreshold": 2,
        "chainId": 1,
        "signer": "0x795B9cD1E5419C54B07768d4AD09809407dfAF5b",
        "signature": "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef"
      }'

Fetch recovery by address​

Fetches recovery requests created by guardians of the Safe accounts by the safe address

GET /recoveries/fetchByAddress​

curl -G "https://api.candide.dev/recoveries/$version/$network/$your_api_key/fetchByAddress" \
  --data-urlencode "account=0xD422B9d638a7BA4eBeF9e33Af9456007eAB4ccba" \
  --data-urlencode "chainId=11155111" \
  --data-urlencode "nonce=0x1"

Fetch recovery by ID​

Fetch a recovery request by ID

GET /recoveries/fetchById​

curl -G "https://api.candide.dev/recoveries/$version/$network/$your_api_key/fetchById" \
  --data-urlencode "id=0x123"

Collect a guardian signature​

Collects a guardian siganture to store for later confirmation and finilization

POST /recoveries/sign​

curl -X POST \
  https://api.candide.dev/recoveries/$version/$network/$your_api_key/sign \
  -H 'Content-Type: application/json' \
  -d '{
        "id": 123456789,
        "signer": "0x0b16b3bD015C1e4C866A88e5Cd3f5836fECe7e8A",
        "signature": "0x45a915e4fc10f6030065f199c1d9258166eb2b98e5a0fe2c4b2ee3a4ed8d6f0a2c5d6e7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5"
      }'

Execute a recovery by ID​

POST /recoveries/execute​

Execute a recovery request by ID

curl -X POST \
  https://api.candide.dev/recoveries/$version/$network/$your_api_key/execute \
  -H 'Content-Type: application/json' \
  -d '{
        "id": 123456789,
      }'

Finalize recovery by ID​

POST /recoveries/finalize​

Finalize a recovery request by ID

curl -X POST \
  https://api.candide.dev/recoveries/$version/$network/$your_api_key/finalize \
  -H 'Content-Type: application/json' \
  -d '{
        "id": 123456789,
      }'

Alerts​

Alerts: Subscribe to recovery requests​

POST /alerts/subscribe​

Creates an inactive alerts subscription for an account, both onchain and offchain. It then needs to be activated through challenge submission using POST /alerts/activate.

curl -X POST \
  https://api.candide.dev/recoveries/$version/$network/$your_api_key/alerts/subscribe \
  -H 'Content-Type: application/json' \
  -d '{
  "account": "0x...",
  "chainId": 1,
  "channel": "email",
  "target": "user@example.com",
  "message": "siwe(chainId, statement(channel, target))",
  "signature": "sign(message)"
}'
  • account: The smart account address requesting registration.
  • chainId: The chain id in which the account resides (this is used to verify the signature field only, the alert will trigger for any action for this account across any chain)
  • channel: Either "email" or "sms" (defines the delievery channel).
  • target: The email or phone number for authentication.
  • message: SIWE (EIP-4361) message statement. Statement:
I agree to receive Social Recovery Module alert notifications for my account address on all supported chains sent to {{target}}
  • signature: signature proving the request is initiated from the account

See example guide how to construct the message and signature using Sign in With Ethereum (SIWE)

Alerts: Activate subscripton to recovery requests​

POST /alerts/activate​

Verifies submitted challenge and activates alerts subscription.

curl -X POST \
  https://api.candide.dev/recoveries/$version/$network/$your_api_key/alerts/activate \
  -H 'Content-Type: application/json' \
  -d '{
  "subscriptionId": "unique-subscription-id",
  "challenge": "123456"
}'
  • subscriptionId: The unique ID received in the subscription response.
  • challenge: The code received via email/SMS.

Alerts: Get active subscription​

Fetches active alerts subscriptions for an account.

GET /alerts/subscriptions​

curl -G "https://api.candide.dev/recoveries/$version/$network/$your_api_key/alerts/subscriptions" \
   --data-urlencode "account=0x...",
   --data-urlencode "chainId=0x1",
   --data-urlencode "message=siwe(chainId, statement)",
   --data-urlencode "signature=sign(message)"
  • account: The smart account address.
  • chainId: The chain id in which the account resides (this is used to verify the signature field only, the alerts are global for this account accross all supported chains that have alerts enabled)
  • message: SIWE (EIP-4361) message statement. Statement:
I request to retrieve all Social Recovery Module alert subscriptions linked to my account
  • signature: signature proving the request is initiated from the account

See example guide how to construct the message and signature using Sign in With Ethereum (SIWE)

Alerts: Unsubscribe​

Unsubscribes from an active alerts subscription.

POST /alerts/unsubscribe​

curl -X GET \
  https://api.candide.dev/recoveries/$version/$network/$your_api_key/alerts/subscriptions \
  -H 'Content-Type: application/json' \
  -d '{
  "subscriptionId": "unique-subscription-id",
}'
  • subscriptionId: The unique ID received in the subscription response.

Error Handeling​

The API uses standard HTTP status codes to indicate the success or failure of a request. Error responses will include a JSON object with the following structure:

​​{
​​  "error": {
​​    "code": 404,
​​    "message": "Recovery request not found"
​​  }
​​}
Last updated on by sednaoui