BotanaryBotanary

Recovery

On-chain guardian / social-recovery module (FR-6).

List recovery guardians

GET
/recovery/guardians

Authorization

sessionToken
AuthorizationBearer <token>

Botanary session token from POST /auth/session. Not a key - a revocable session bearer.

In: header

Response Body

application/json

application/json

curl -X GET "https://api.app.botanary.xyz/recovery/guardians"
[
  {
    "id": "string",
    "name": "iPhone 15 · passkey",
    "kind": "device",
    "primary": true,
    "addedAt": "2019-08-24T14:15:22Z"
  }
]
{
  "error": {
    "code": "unauthorized",
    "message": "Session token missing or expired."
  }
}

Build the add-guardian op

POST
/recovery/guardians

Authorization

sessionToken
AuthorizationBearer <token>

Botanary session token from POST /auth/session. Not a key - a revocable session bearer.

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

application/json

curl -X POST "https://api.app.botanary.xyz/recovery/guardians" \  -H "Content-Type: application/json" \  -d '{    "name": "string",    "kind": "device"  }'
{
  "intentType": "send",
  "userOp": {
    "sender": "0x8f2A9c4419aD77b0392bC41D8123aa77c0Fe41D0",
    "nonce": "0",
    "factory": "0x8f2A9c4419aD77b0392bC41D8123aa77c0Fe41D0",
    "factoryData": "0x",
    "callData": "0x",
    "callGasLimit": "200000",
    "verificationGasLimit": "150000",
    "preVerificationGas": "50000",
    "maxFeePerGas": "1000000000",
    "maxPriorityFeePerGas": "1000000000",
    "paymaster": "0x8f2A9c4419aD77b0392bC41D8123aa77c0Fe41D0",
    "paymasterVerificationGasLimit": "string",
    "paymasterPostOpGasLimit": "string",
    "paymasterData": "0x",
    "signature": "0x",
    "entryPoint": "0x8f2A9c4419aD77b0392bC41D8123aa77c0Fe41D0",
    "chainId": 42161
  },
  "userOpHash": "0x4c1f9a0b2d7e8c3f1a6b0d4e2c9f7a1b4c1f9a0b2d7e8c3f1a6b0d4e2c9f7a1b",
  "humanSummary": "string",
  "simulation": {
    "id": "string",
    "intentType": "send",
    "willSucceed": true,
    "declineReason": "cap_exceeded",
    "amountIn": {
      "token": {
        "symbol": "USDC",
        "chainId": 42161,
        "address": "0x8f2A9c4419aD77b0392bC41D8123aa77c0Fe41D0"
      },
      "amount": 50
    },
    "amountOut": {
      "token": {
        "symbol": "USDC",
        "chainId": 42161,
        "address": "0x8f2A9c4419aD77b0392bC41D8123aa77c0Fe41D0"
      },
      "amount": 50
    },
    "rate": 1.08,
    "route": "USDC → EURC via Uniswap v3",
    "slippageBps": 30,
    "fees": [
      {
        "token": {
          "symbol": "USDC",
          "chainId": 42161,
          "address": "0x8f2A9c4419aD77b0392bC41D8123aa77c0Fe41D0"
        },
        "amount": 50
      }
    ],
    "gas": {
      "method": "sponsored",
      "cost": {
        "token": {
          "symbol": "USDC",
          "chainId": 42161,
          "address": "0x8f2A9c4419aD77b0392bC41D8123aa77c0Fe41D0"
        },
        "amount": 50
      },
      "sponsored": true
    },
    "warnings": [
      "string"
    ],
    "expiresAt": "2019-08-24T14:15:22Z"
  },
  "riskReducing": true,
  "instant": true,
  "gasless": true,
  "gasPermit": {
    "paymaster": "0x8f2A9c4419aD77b0392bC41D8123aa77c0Fe41D0",
    "token": "0x8f2A9c4419aD77b0392bC41D8123aa77c0Fe41D0",
    "tokenName": "USD Coin",
    "tokenVersion": "2",
    "kernelVersion": "0.3.3",
    "permitAmount": "212142",
    "permitNonce": "2",
    "permitDeadline": "string",
    "permitDigest": "0x4c1f9a0b2d7e8c3f1a6b0d4e2c9f7a1b4c1f9a0b2d7e8c3f1a6b0d4e2c9f7a1b",
    "signaturePrefix": "0x",
    "estimatedFee": 0.031296
  },
  "usdtApproval": {
    "token": "0x8f2A9c4419aD77b0392bC41D8123aa77c0Fe41D0",
    "paymaster": "0x8f2A9c4419aD77b0392bC41D8123aa77c0Fe41D0",
    "amount": "string",
    "calls": [
      {
        "to": "0x8f2A9c4419aD77b0392bC41D8123aa77c0Fe41D0",
        "data": "0x",
        "value": "string"
      }
    ]
  }
}
{
  "error": {
    "code": "unauthorized",
    "message": "Session token missing or expired."
  }
}

Build the op that installs social recovery (guardian set + M-of-N threshold)

POST
/recovery/guardians/install

Authorization

sessionToken
AuthorizationBearer <token>

Botanary session token from POST /auth/session. Not a key - a revocable session bearer.

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

application/json

curl -X POST "https://api.app.botanary.xyz/recovery/guardians/install" \  -H "Content-Type: application/json" \  -d '{    "guardians": [      "0x8f2A9c4419aD77b0392bC41D8123aa77c0Fe41D0"    ]  }'
{
  "intentType": "send",
  "userOp": {
    "sender": "0x8f2A9c4419aD77b0392bC41D8123aa77c0Fe41D0",
    "nonce": "0",
    "factory": "0x8f2A9c4419aD77b0392bC41D8123aa77c0Fe41D0",
    "factoryData": "0x",
    "callData": "0x",
    "callGasLimit": "200000",
    "verificationGasLimit": "150000",
    "preVerificationGas": "50000",
    "maxFeePerGas": "1000000000",
    "maxPriorityFeePerGas": "1000000000",
    "paymaster": "0x8f2A9c4419aD77b0392bC41D8123aa77c0Fe41D0",
    "paymasterVerificationGasLimit": "string",
    "paymasterPostOpGasLimit": "string",
    "paymasterData": "0x",
    "signature": "0x",
    "entryPoint": "0x8f2A9c4419aD77b0392bC41D8123aa77c0Fe41D0",
    "chainId": 42161
  },
  "userOpHash": "0x4c1f9a0b2d7e8c3f1a6b0d4e2c9f7a1b4c1f9a0b2d7e8c3f1a6b0d4e2c9f7a1b",
  "humanSummary": "string",
  "simulation": {
    "id": "string",
    "intentType": "send",
    "willSucceed": true,
    "declineReason": "cap_exceeded",
    "amountIn": {
      "token": {
        "symbol": "USDC",
        "chainId": 42161,
        "address": "0x8f2A9c4419aD77b0392bC41D8123aa77c0Fe41D0"
      },
      "amount": 50
    },
    "amountOut": {
      "token": {
        "symbol": "USDC",
        "chainId": 42161,
        "address": "0x8f2A9c4419aD77b0392bC41D8123aa77c0Fe41D0"
      },
      "amount": 50
    },
    "rate": 1.08,
    "route": "USDC → EURC via Uniswap v3",
    "slippageBps": 30,
    "fees": [
      {
        "token": {
          "symbol": "USDC",
          "chainId": 42161,
          "address": "0x8f2A9c4419aD77b0392bC41D8123aa77c0Fe41D0"
        },
        "amount": 50
      }
    ],
    "gas": {
      "method": "sponsored",
      "cost": {
        "token": {
          "symbol": "USDC",
          "chainId": 42161,
          "address": "0x8f2A9c4419aD77b0392bC41D8123aa77c0Fe41D0"
        },
        "amount": 50
      },
      "sponsored": true
    },
    "warnings": [
      "string"
    ],
    "expiresAt": "2019-08-24T14:15:22Z"
  },
  "riskReducing": true,
  "instant": true,
  "gasless": true,
  "gasPermit": {
    "paymaster": "0x8f2A9c4419aD77b0392bC41D8123aa77c0Fe41D0",
    "token": "0x8f2A9c4419aD77b0392bC41D8123aa77c0Fe41D0",
    "tokenName": "USD Coin",
    "tokenVersion": "2",
    "kernelVersion": "0.3.3",
    "permitAmount": "212142",
    "permitNonce": "2",
    "permitDeadline": "string",
    "permitDigest": "0x4c1f9a0b2d7e8c3f1a6b0d4e2c9f7a1b4c1f9a0b2d7e8c3f1a6b0d4e2c9f7a1b",
    "signaturePrefix": "0x",
    "estimatedFee": 0.031296
  },
  "usdtApproval": {
    "token": "0x8f2A9c4419aD77b0392bC41D8123aa77c0Fe41D0",
    "paymaster": "0x8f2A9c4419aD77b0392bC41D8123aa77c0Fe41D0",
    "amount": "string",
    "calls": [
      {
        "to": "0x8f2A9c4419aD77b0392bC41D8123aa77c0Fe41D0",
        "data": "0x",
        "value": "string"
      }
    ]
  }
}
{
  "error": {
    "code": "unauthorized",
    "message": "Session token missing or expired."
  }
}

Build the ordered ops that rotate the root signer to a new owner

POST
/recovery/guardians/recover

Authorization

sessionToken
AuthorizationBearer <token>

Botanary session token from POST /auth/session. Not a key - a revocable session bearer.

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

application/json

curl -X POST "https://api.app.botanary.xyz/recovery/guardians/recover" \  -H "Content-Type: application/json" \  -d '{    "newOwner": "0x8f2A9c4419aD77b0392bC41D8123aa77c0Fe41D0",    "lostOwner": "0x8f2A9c4419aD77b0392bC41D8123aa77c0Fe41D0"  }'
[
  {
    "intentType": "send",
    "userOp": {
      "sender": "0x8f2A9c4419aD77b0392bC41D8123aa77c0Fe41D0",
      "nonce": "0",
      "factory": "0x8f2A9c4419aD77b0392bC41D8123aa77c0Fe41D0",
      "factoryData": "0x",
      "callData": "0x",
      "callGasLimit": "200000",
      "verificationGasLimit": "150000",
      "preVerificationGas": "50000",
      "maxFeePerGas": "1000000000",
      "maxPriorityFeePerGas": "1000000000",
      "paymaster": "0x8f2A9c4419aD77b0392bC41D8123aa77c0Fe41D0",
      "paymasterVerificationGasLimit": "string",
      "paymasterPostOpGasLimit": "string",
      "paymasterData": "0x",
      "signature": "0x",
      "entryPoint": "0x8f2A9c4419aD77b0392bC41D8123aa77c0Fe41D0",
      "chainId": 42161
    },
    "userOpHash": "0x4c1f9a0b2d7e8c3f1a6b0d4e2c9f7a1b4c1f9a0b2d7e8c3f1a6b0d4e2c9f7a1b",
    "humanSummary": "string",
    "simulation": {
      "id": "string",
      "intentType": "send",
      "willSucceed": true,
      "declineReason": "cap_exceeded",
      "amountIn": {
        "token": {
          "symbol": "USDC",
          "chainId": 42161,
          "address": "0x8f2A9c4419aD77b0392bC41D8123aa77c0Fe41D0"
        },
        "amount": 50
      },
      "amountOut": {
        "token": {
          "symbol": "USDC",
          "chainId": 42161,
          "address": "0x8f2A9c4419aD77b0392bC41D8123aa77c0Fe41D0"
        },
        "amount": 50
      },
      "rate": 1.08,
      "route": "USDC → EURC via Uniswap v3",
      "slippageBps": 30,
      "fees": [
        {
          "token": {
            "symbol": "USDC",
            "chainId": 42161,
            "address": "0x8f2A9c4419aD77b0392bC41D8123aa77c0Fe41D0"
          },
          "amount": 50
        }
      ],
      "gas": {
        "method": "sponsored",
        "cost": {
          "token": {
            "symbol": "USDC",
            "chainId": 42161,
            "address": "0x8f2A9c4419aD77b0392bC41D8123aa77c0Fe41D0"
          },
          "amount": 50
        },
        "sponsored": true
      },
      "warnings": [
        "string"
      ],
      "expiresAt": "2019-08-24T14:15:22Z"
    },
    "riskReducing": true,
    "instant": true,
    "gasless": true,
    "gasPermit": {
      "paymaster": "0x8f2A9c4419aD77b0392bC41D8123aa77c0Fe41D0",
      "token": "0x8f2A9c4419aD77b0392bC41D8123aa77c0Fe41D0",
      "tokenName": "USD Coin",
      "tokenVersion": "2",
      "kernelVersion": "0.3.3",
      "permitAmount": "212142",
      "permitNonce": "2",
      "permitDeadline": "string",
      "permitDigest": "0x4c1f9a0b2d7e8c3f1a6b0d4e2c9f7a1b4c1f9a0b2d7e8c3f1a6b0d4e2c9f7a1b",
      "signaturePrefix": "0x",
      "estimatedFee": 0.031296
    },
    "usdtApproval": {
      "token": "0x8f2A9c4419aD77b0392bC41D8123aa77c0Fe41D0",
      "paymaster": "0x8f2A9c4419aD77b0392bC41D8123aa77c0Fe41D0",
      "amount": "string",
      "calls": [
        {
          "to": "0x8f2A9c4419aD77b0392bC41D8123aa77c0Fe41D0",
          "data": "0x",
          "value": "string"
        }
      ]
    }
  }
]
{
  "error": {
    "code": "unauthorized",
    "message": "Session token missing or expired."
  }
}

Build the remove-guardian op

POST
/recovery/guardians/{guardianId}/remove

Authorization

sessionToken
AuthorizationBearer <token>

Botanary session token from POST /auth/session. Not a key - a revocable session bearer.

In: header

Path Parameters

guardianId*string

Response Body

application/json

application/json

application/json

curl -X POST "https://api.app.botanary.xyz/recovery/guardians/string/remove"
{
  "intentType": "send",
  "userOp": {
    "sender": "0x8f2A9c4419aD77b0392bC41D8123aa77c0Fe41D0",
    "nonce": "0",
    "factory": "0x8f2A9c4419aD77b0392bC41D8123aa77c0Fe41D0",
    "factoryData": "0x",
    "callData": "0x",
    "callGasLimit": "200000",
    "verificationGasLimit": "150000",
    "preVerificationGas": "50000",
    "maxFeePerGas": "1000000000",
    "maxPriorityFeePerGas": "1000000000",
    "paymaster": "0x8f2A9c4419aD77b0392bC41D8123aa77c0Fe41D0",
    "paymasterVerificationGasLimit": "string",
    "paymasterPostOpGasLimit": "string",
    "paymasterData": "0x",
    "signature": "0x",
    "entryPoint": "0x8f2A9c4419aD77b0392bC41D8123aa77c0Fe41D0",
    "chainId": 42161
  },
  "userOpHash": "0x4c1f9a0b2d7e8c3f1a6b0d4e2c9f7a1b4c1f9a0b2d7e8c3f1a6b0d4e2c9f7a1b",
  "humanSummary": "string",
  "simulation": {
    "id": "string",
    "intentType": "send",
    "willSucceed": true,
    "declineReason": "cap_exceeded",
    "amountIn": {
      "token": {
        "symbol": "USDC",
        "chainId": 42161,
        "address": "0x8f2A9c4419aD77b0392bC41D8123aa77c0Fe41D0"
      },
      "amount": 50
    },
    "amountOut": {
      "token": {
        "symbol": "USDC",
        "chainId": 42161,
        "address": "0x8f2A9c4419aD77b0392bC41D8123aa77c0Fe41D0"
      },
      "amount": 50
    },
    "rate": 1.08,
    "route": "USDC → EURC via Uniswap v3",
    "slippageBps": 30,
    "fees": [
      {
        "token": {
          "symbol": "USDC",
          "chainId": 42161,
          "address": "0x8f2A9c4419aD77b0392bC41D8123aa77c0Fe41D0"
        },
        "amount": 50
      }
    ],
    "gas": {
      "method": "sponsored",
      "cost": {
        "token": {
          "symbol": "USDC",
          "chainId": 42161,
          "address": "0x8f2A9c4419aD77b0392bC41D8123aa77c0Fe41D0"
        },
        "amount": 50
      },
      "sponsored": true
    },
    "warnings": [
      "string"
    ],
    "expiresAt": "2019-08-24T14:15:22Z"
  },
  "riskReducing": true,
  "instant": true,
  "gasless": true,
  "gasPermit": {
    "paymaster": "0x8f2A9c4419aD77b0392bC41D8123aa77c0Fe41D0",
    "token": "0x8f2A9c4419aD77b0392bC41D8123aa77c0Fe41D0",
    "tokenName": "USD Coin",
    "tokenVersion": "2",
    "kernelVersion": "0.3.3",
    "permitAmount": "212142",
    "permitNonce": "2",
    "permitDeadline": "string",
    "permitDigest": "0x4c1f9a0b2d7e8c3f1a6b0d4e2c9f7a1b4c1f9a0b2d7e8c3f1a6b0d4e2c9f7a1b",
    "signaturePrefix": "0x",
    "estimatedFee": 0.031296
  },
  "usdtApproval": {
    "token": "0x8f2A9c4419aD77b0392bC41D8123aa77c0Fe41D0",
    "paymaster": "0x8f2A9c4419aD77b0392bC41D8123aa77c0Fe41D0",
    "amount": "string",
    "calls": [
      {
        "to": "0x8f2A9c4419aD77b0392bC41D8123aa77c0Fe41D0",
        "data": "0x",
        "value": "string"
      }
    ]
  }
}
{
  "error": {
    "code": "unauthorized",
    "message": "Session token missing or expired."
  }
}
{
  "error": {
    "code": "out_of_scope",
    "message": "This action exceeds the per-action cap.",
    "declineReason": "cap_exceeded",
    "details": {},
    "requestId": "string"
  }
}

Notifications

Alerts feed - every action, every block, every depeg drift.

Rules

On-chain account rules (FR-5) - owner-set caps + contract/recipient allowlists & denylists.