Rules
On-chain account rules (FR-5) - owner-set caps + contract/recipient allowlists & denylists.
Get the owner's on-chain account rules (FR-5)
Authorization
sessionToken AuthorizationBearer <token>
Botanary session token from POST /auth/session. Not a key - a revocable session bearer.
In: header
Query Parameters
accountId?string
Scope the read to 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 GET "https://api.app.botanary.xyz/account/rules"{
"summary": {
"weeklyLimit": 2000,
"weeklySpent": 430,
"allowContracts": 4,
"denyContracts": 2,
"allowRecipients": 6
},
"caps": [
{
"token": {
"symbol": "USDC",
"chainId": 42161
},
"limit": 2000,
"spent": 430,
"remaining": 1570,
"period": "week",
"resetsAt": "2026-07-10T00:00:00Z"
}
],
"allowlist": {
"contracts": [
{
"name": "Universal Router",
"address": "0x66a9893cC07D91D95644AEDD05D03f95e1dBA8Af"
},
{
"name": "Permit2",
"address": "0x000000000022D473030F116dDEE9F6B43aC78BA3"
},
{
"name": "Aave v3 Pool",
"address": "0x87870Bca3F3fD6335C3F4ce8392D69350B4fA4E2"
},
{
"name": "Curve Router",
"address": "0x16C6521Dff6baB339122a0FE25a9116693265353"
}
],
"recipients": [
{
"name": "coinbase.eth",
"address": "0x71C7656EC7ab88b098defB751B7401B5f6d8976F"
},
{
"name": "trung.eth",
"address": "0x4E83362442B8d1beC281594cEA3050c8EB01311C"
},
{
"name": "0xLandlord",
"address": "0x51C0aB3F4e8c1bB2d9F0aE7c5D6b8A9e2F1c3D40"
}
],
"denied": [
{
"name": "Unverified drainer",
"address": "0xBAD1a9c4419aD77b0392bC41D8123aa77c0FbeEf"
},
{
"name": "Flagged mixer",
"address": "0xDeaD00000000000000000000000000000000C0DE"
}
]
}
}{
"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 config-change op for a desired rules state
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
application/json
curl -X POST "https://api.app.botanary.xyz/account/rules/build" \ -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"
}
]
}
}{
"error": {
"code": "unauthorized",
"message": "Session token missing or expired."
}
}{
"error": {
"code": "out_of_scope",
"message": "This action exceeds the per-action cap.",
"declineReason": "per_action_exceeded"
}
}