Access Control

API keys support granular access controls that let you restrict what an agent can do and where it can connect from.

All access controls are managed at bankr.bot/api.

Best practices

This page is the reference for every flag and error response. For prescriptive guidance on how to configure keys safely (dedicated wallets, recommended configs by use case, incident response), see Security Best Practices → Developer API.

API Key Permissions

Each API key has independent capability flags:

Flag	Default	Description
walletApiEnabled	Enabled	Access to wallet write operations (/wallet/transfer, /wallet/sign, /wallet/submit) and legacy /agent/me, /agent/balances, /agent/sign, /agent/submit
agentApiEnabled	Disabled	Access to AI agent endpoints (/agent/prompt, /agent/profile, /agent/job/*)
tokenLaunchApiEnabled	Enabled	Access to token deployment (/token-launches/deploy). Also gates the deploy tool when using the Agent API.
llmGatewayEnabled	Disabled	Access to the LLM Gateway at llm.bankr.bot
readOnly	Enabled	Restricts Wallet/Agent API to read-only operations (no transactions). Disable with --read-write in CLI or toggle in web settings.
allowedIps	Empty (all IPs)	IP allowlist — accepts IPs and CIDR ranges (e.g., 10.0.0.0/24)
allowedRecipients	Empty (all addresses)	Wallet allowlist — restricts which addresses the agent can send funds to

All keys share the bk_... format. Each flag is configured independently.

Read-Only Mode

When readOnly is enabled on an API key, the agent can only retrieve information — it cannot execute transactions, swaps, transfers, or any state-changing operations.

Behavior by Endpoint

Endpoint	Behavior
POST /agent/prompt	Works, but only read tools are available (prices, balances, analytics, research)
GET /agent/job/:jobId	Works normally
POST /agent/cancel/:jobId	Works normally
POST /wallet/sign	Blocked — returns 403
POST /wallet/submit	Blocked — returns 403
POST /wallet/transfer	Blocked — returns 403
GET /wallet/me	Works normally
GET /wallet/portfolio	Works normally

Error Responses

Sign endpoint (403):

{
  "error": "Read-only API key",
  "message": "This API key has read-only access and cannot sign messages or transactions. Update your API key permissions at https://bankr.bot/api"
}

Submit endpoint (403):

{
  "error": "Read-only API key",
  "message": "This API key has read-only access and cannot submit transactions. Update your API key permissions at https://bankr.bot/api"
}

How It Works

When a read-only key calls /agent/prompt, the agent session receives a system directive that removes all write tools. The following tool categories are filtered out:

• Token swaps
• Token and ETH transfers
• NFT purchases and trades
• Staking and unstaking
• Limit, stop, DCA, and TWAP orders
• Token launches and deployments
• Leveraged trading positions
• Polymarket bets
• Fee claims

The agent is aware of the restriction and will explain it to users who request write operations.

IP Allowlist

The allowedIps array restricts which IP addresses can use the key. Supports both individual IPs and CIDR ranges. Validation runs in the auth middleware before any endpoint logic.

• Empty array (default) — all IPs are accepted
• One or more entries — only requests from listed IPs or CIDR ranges are accepted (e.g., "192.168.1.1", "10.0.0.0/24")

Minimum CIDR prefix lengths are enforced to prevent overly broad ranges that would effectively disable the allowlist: /8 for IPv4 and /16 for IPv6. Ranges broader than these are rejected at key creation time.

Error response (403):

{
  "error": "IP address not allowed",
  "message": "IP address not allowed for this API key"
}

Wallet Allowlist

The allowedRecipients field restricts which wallet addresses the agent can send funds or assets to. It applies to transfers, swaps, and any tool that moves value to an external address.

• Empty arrays (default) — all recipient addresses are accepted
• One or more addresses — only listed addresses (plus the user's own wallet) are accepted

Supports both EVM and Solana independently:

{
  "allowedRecipients": {
    "evm": ["0xabc..."],
    "solana": ["7xKX..."]
  }
}

EVM addresses are stored and matched case-insensitively. You can update evm and solana independently — omit a chain key to leave it unchanged.

Error response when a blocked address is targeted:

Recipient 0xabc... is not in the trusted addresses list. Contact your API key administrator to add this address.

The agent is aware of the restriction and will surface this message if a user requests a transaction to an unlisted address.

Rate Limits

Daily Message Limits

The /agent/prompt endpoint requires a Bankr Club subscription or Max Mode with LLM credits. There is no free tier.

Tier	Daily Limit	Requirement
Max Mode	100 messages	LLM credit balance > $0
Bankr Club	1,000 messages	Active subscription ($20/mo in BNKR)
Custom (per key)	Set at bankr.bot/api	—

Custom limits override both the Max Mode and Bankr Club defaults.

The limit uses a rolling 24-hour window from the time of first usage — it does not reset at midnight.

Error response (429):

{
  "error": "Daily limit exceeded",
  "message": "You have reached your daily API limit of 100 messages. Upgrade to Bankr Club for 1000 messages/day. Resets at 2025-01-15T12:00:00.000Z",
  "resetAt": 1736942400000,
  "limit": 100,
  "used": 100
}

The resetAt field is a Unix timestamp (milliseconds) indicating when the counter resets. The limit and used fields show the current quota and consumption.

note

The "Upgrade to Bankr Club" portion of the message only appears for Max Mode accounts. Bankr Club members and accounts with a custom daily limit see a shorter message without the upgrade prompt.

General API Rate Limits

These apply to all API consumers by IP or API key:

Scope	Window	Limit
Public endpoints (/public/*)	15 minutes	100 requests per IP
General endpoints	1 minute	120 requests per IP
External orders (/trading/order)	1 second	10 requests per API key

API Key vs LLM Gateway Key

A single API key can serve both the Agent API and the LLM Gateway when both flags are enabled. You can also use separate keys:

Config	Agent API	LLM Gateway
Single key	BANKR_API_KEY	Same key
Separate keys	BANKR_API_KEY	BANKR_LLM_KEY

In the CLI:

• bankr login --api-key KEY sets the Agent API key
• bankr login --llm-key KEY sets the LLM Gateway key
• bankr config set llmKey KEY updates the LLM key independently

When to use separate keys:

• Different permission requirements (e.g., agent key is read-only, LLM key only needs gateway access)
• Independent revocation — rotate one without affecting the other
• Different rate limit tracking