BotanaryBotanary

Account

The owner's self-custodial ERC-7579 smart account (counterfactual → deployed on first op).

Get the owner's smart account

GET
/account

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

application/json

curl -X GET "https://api.app.botanary.xyz/account"
{
  "id": "acct_01H8",
  "label": "Main account",
  "address": "0x8f2A9c4419aD77b0392bC41D8123aa77c0Fe41D0",
  "type": "Smart account",
  "deploymentStatus": "counterfactual",
  "chainId": 42161,
  "signerAddress": "0x8f2A9c4419aD77b0392bC41D8123aa77c0Fe41D0",
  "frozen": true,
  "index": 0,
  "hidden": true,
  "purpose": "primary",
  "createdAt": "2019-08-24T14:15:22Z",
  "totalFiat": 8765.66
}
{
  "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"
  }
}

Register the counterfactual account and return its deploy intent

POST
/account

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/account" \  -H "Content-Type: application/json" \  -d '{}'
{
  "account": {
    "id": "acct_01H8",
    "label": "Main account",
    "address": "0x8f2A9c4419aD77b0392bC41D8123aa77c0Fe41D0",
    "type": "Smart account",
    "deploymentStatus": "counterfactual",
    "chainId": 42161,
    "signerAddress": "0x8f2A9c4419aD77b0392bC41D8123aa77c0Fe41D0",
    "frozen": true,
    "index": 0,
    "hidden": true,
    "purpose": "primary",
    "createdAt": "2019-08-24T14:15:22Z",
    "totalFiat": 8765.66
  },
  "deployUserOp": {
    "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"
}
{
  "error": {
    "code": "unauthorized",
    "message": "Session token missing or expired."
  }
}

List every account this owner has (visible and hidden)

GET
/accounts

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/accounts"
[
  {
    "id": "acct_01H8",
    "label": "Main account",
    "address": "0x8f2A9c4419aD77b0392bC41D8123aa77c0Fe41D0",
    "type": "Smart account",
    "deploymentStatus": "counterfactual",
    "chainId": 42161,
    "signerAddress": "0x8f2A9c4419aD77b0392bC41D8123aa77c0Fe41D0",
    "frozen": true,
    "index": 0,
    "hidden": true,
    "purpose": "primary",
    "createdAt": "2019-08-24T14:15:22Z",
    "totalFiat": 8765.66
  }
]
{
  "error": {
    "code": "unauthorized",
    "message": "Session token missing or expired."
  }
}

Mint the next account (always a NEW CREATE2 index)

POST
/accounts

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 POST "https://api.app.botanary.xyz/accounts"
{
  "account": {
    "id": "acct_01H8",
    "label": "Main account",
    "address": "0x8f2A9c4419aD77b0392bC41D8123aa77c0Fe41D0",
    "type": "Smart account",
    "deploymentStatus": "counterfactual",
    "chainId": 42161,
    "signerAddress": "0x8f2A9c4419aD77b0392bC41D8123aa77c0Fe41D0",
    "frozen": true,
    "index": 0,
    "hidden": true,
    "purpose": "primary",
    "createdAt": "2019-08-24T14:15:22Z",
    "totalFiat": 8765.66
  },
  "deployUserOp": {
    "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"
}
{
  "error": {
    "code": "unauthorized",
    "message": "Session token missing or expired."
  }
}

Rename and/or hide/unhide an account

PATCH
/accounts/{id}

Authorization

sessionToken
AuthorizationBearer <token>

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

In: header

Path Parameters

id*string

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

application/json

application/json

application/json

curl -X PATCH "https://api.app.botanary.xyz/accounts/string" \  -H "Content-Type: application/json" \  -d '{}'
{
  "id": "acct_01H8",
  "label": "Main account",
  "address": "0x8f2A9c4419aD77b0392bC41D8123aa77c0Fe41D0",
  "type": "Smart account",
  "deploymentStatus": "counterfactual",
  "chainId": 42161,
  "signerAddress": "0x8f2A9c4419aD77b0392bC41D8123aa77c0Fe41D0",
  "frozen": true,
  "index": 0,
  "hidden": true,
  "purpose": "primary",
  "createdAt": "2019-08-24T14:15:22Z",
  "totalFiat": 8765.66
}
{
  "error": {
    "code": "out_of_scope",
    "message": "This action exceeds the per-action cap.",
    "declineReason": "cap_exceeded",
    "details": {},
    "requestId": "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"
  }
}

Import an ERC-20 by address into this account

POST
/accounts/{id}/tokens

Authorization

sessionToken
AuthorizationBearer <token>

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

In: header

Path Parameters

id*string

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://api.app.botanary.xyz/accounts/string/tokens" \  -H "Content-Type: application/json" \  -d '{    "tokenAddress": "0x8f2A9c4419aD77b0392bC41D8123aa77c0Fe41D0",    "chainId": 42161  }'
{
  "symbol": "USDC",
  "name": "USD Coin",
  "chain": "Arbitrum",
  "chainId": 42161,
  "tokenAddress": "0x8f2A9c4419aD77b0392bC41D8123aa77c0Fe41D0",
  "decimals": 6,
  "amount": 6420.5,
  "fiat": 6420.5,
  "price": 1,
  "change24h": 0,
  "isStablecoin": true,
  "peg": {
    "symbol": "USDT",
    "price": 0.9938,
    "target": 1,
    "deviationBps": -62,
    "status": "ok",
    "observedAt": "2019-08-24T14:15:22Z",
    "source": "chainlink",
    "unavailableReason": "Chainlink oracle unavailable"
  },
  "spendable": true,
  "source": "registry",
  "unrecognized": true,
  "graduationStatus": "sentient",
  "recognized": true,
  "fdvUsd": 0
}
{
  "error": {
    "code": "out_of_scope",
    "message": "This action exceeds the per-action cap.",
    "declineReason": "cap_exceeded",
    "details": {},
    "requestId": "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"
  }
}
{
  "error": {
    "code": "out_of_scope",
    "message": "This action exceeds the per-action cap.",
    "declineReason": "cap_exceeded",
    "details": {},
    "requestId": "string"
  }
}

Remove a previously-imported ERC-20 from this account

DELETE
/accounts/{id}/tokens/{tokenAddress}

Authorization

sessionToken
AuthorizationBearer <token>

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

In: header

Path Parameters

id*string
tokenAddress*string

A 20-byte EVM address.

Match^0x[a-fA-F0-9]{40}$

Response Body

application/json

application/json

curl -X DELETE "https://api.app.botanary.xyz/accounts/string/tokens/0x8f2A9c4419aD77b0392bC41D8123aa77c0Fe41D0"
Empty
{
  "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"
  }
}

Build the account-level kill-switch (freeze) op

POST
/account/freeze

Authorization

sessionToken
AuthorizationBearer <token>

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

In: header

Query Parameters

accountId?string

Target this specific account of the caller's (must belong to the authenticated signer - a foreign or unknown id is rejected, never silently ignored). Omitted defaults to the signer's lowest-visible-index account. Safety-critical: the freeze always targets the resolved account, never an unrelated default - freezing while viewing a non-primary account must freeze THAT account.

lane?string

panic routes to the 1-of-N panic session (any single device signs, gas-abstracted). Omitted or any other value keeps the default owner-lane freeze (needs the current M-of-N threshold).

Value in"owner" | "panic"

Response Body

application/json

application/json

application/json

curl -X POST "https://api.app.botanary.xyz/account/freeze"
{
  "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"
      }
    ]
  },
  "permissionId": "0x4c1f9a0b2d7e8c3f1a6b0d4e2c9f7a1b4c1f9a0b2d7e8c3f1a6b0d4e2c9f7a1b"
}
{
  "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"
  }
}

Build the account-level unfreeze op

POST
/account/unfreeze

Authorization

sessionToken
AuthorizationBearer <token>

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

In: header

Query Parameters

accountId?string

Target this specific account of the caller's (must belong to the authenticated signer - a foreign or unknown id is rejected, never silently ignored). Omitted defaults to the signer's lowest-visible-index account.

Response Body

application/json

application/json

application/json

curl -X POST "https://api.app.botanary.xyz/account/unfreeze"
{
  "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"
  }
}

Build a "fund with test USDC" op (testnet mock, self-custodial mint to this account)

POST
/account/fund

Authorization

sessionToken
AuthorizationBearer <token>

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

In: header

Query Parameters

accountId?string

Target this specific account of the caller's (must belong to the authenticated signer - a foreign or unknown id is rejected, never silently ignored). Omitted defaults to the signer's lowest-visible-index account.

Response Body

application/json

application/json

application/json

application/json

curl -X POST "https://api.app.botanary.xyz/account/fund"
{
  "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": "out_of_scope",
    "message": "This action exceeds the per-action cap.",
    "declineReason": "cap_exceeded",
    "details": {},
    "requestId": "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"
  }
}

Build the op that installs the panic freeze lane (scoped 1-of-N SmartSession)

POST
/account/panic/install

Authorization

sessionToken
AuthorizationBearer <token>

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

In: header

Query Parameters

accountId?string

Target this specific account of the caller's (must belong to the authenticated signer - a foreign or unknown id is rejected, never silently ignored). Omitted defaults to the signer's lowest-visible-index account.

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

application/json

application/json

curl -X POST "https://api.app.botanary.xyz/account/panic/install" \  -H "Content-Type: application/json" \  -d '{}'
{
  "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"
      }
    ]
  },
  "permissionId": "0x4c1f9a0b2d7e8c3f1a6b0d4e2c9f7a1b4c1f9a0b2d7e8c3f1a6b0d4e2c9f7a1b",
  "deviceKeys": [
    "0x8f2A9c4419aD77b0392bC41D8123aa77c0Fe41D0"
  ]
}
{
  "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"
  }
}

Build the 1-of-N panic freeze op (any single device signs, gas-abstracted)

POST
/account/panic/freeze

Authorization

sessionToken
AuthorizationBearer <token>

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

In: header

Query Parameters

accountId?string

Target this specific account of the caller's (must belong to the authenticated signer - a foreign or unknown id is rejected, never silently ignored). Omitted defaults to the signer's lowest-visible-index account.

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

application/json

application/json

curl -X POST "https://api.app.botanary.xyz/account/panic/freeze" \  -H "Content-Type: application/json" \  -d '{}'
{
  "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"
      }
    ]
  },
  "permissionId": "0x4c1f9a0b2d7e8c3f1a6b0d4e2c9f7a1b4c1f9a0b2d7e8c3f1a6b0d4e2c9f7a1b"
}
{
  "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"
  }
}

List saved contacts / recipients (for pickers)

GET
/contacts

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/contacts"
[
  {
    "name": "coinbase.eth",
    "address": "0x71C7656EC7ab88b098defB751B7401B5f6d8976F"
  },
  {
    "name": "trung.eth",
    "address": "0x4E83362442B8d1beC281594cEA3050c8EB01311C"
  },
  {
    "name": "0xLandlord",
    "address": "0x51C0aB3F4e8c1bB2d9F0aE7c5D6b8A9e2F1c3D40"
  }
]
{
  "error": {
    "code": "unauthorized",
    "message": "Session token missing or expired."
  }
}

API Reference

Interactive reference for the Botanary v1 API, generated from the frozen backend-frontend OpenAPI contract.

Activity

The tamper-evident, hash-chained audit log (paginated; executed vs declined).