Safety & Access Control

Security patterns and best practices for Bankr API integrations.

API Key Capability Flags

Each API key has independent toggles managed at bankr.bot/api:

Separate Agent & LLM Keys

Read-Only Keys

When readOnly: true:

• /agent/prompt works but only read tools are available
• /agent/sign returns 403
• /agent/submit returns 403

// Handle read-only 403 errors
const response = await fetch(`${API_URL}/agent/sign`, { ... });
if (response.status === 403) {
  const error = await response.json();
  // error.message: "This API key has read-only access..."
}

IP Whitelisting

// Requests from non-whitelisted IPs get 403
// Configure allowedIps at bankr.bot/api
const response = await fetch(`${API_URL}/agent/prompt`, { ... });
if (response.status === 403) {
  const error = await response.json();
  // error.message: "IP address not allowed for this API key"
}

Dedicated Agent Wallet

For autonomous agents, create a separate Bankr account:

1. Sign up at bankr.bot/api with a different email
2. Generate an API key with Agent API enabled
3. Configure access controls (readOnly, allowedIps)
4. Fund with limited amounts

Access Control Combinations

Rate Limits

// Handle 429 rate limit responses
const response = await fetch(`${API_URL}/agent/prompt`, { ... });
if (response.status === 429) {
  const error = await response.json();
  // error.resetAt: Unix timestamp when counter resets
  // error.limit: Daily limit
  // error.used: Messages used
  const retryAfter = error.resetAt - Date.now();
}

Key Management Patterns

// Always use environment variables
const API_KEY = process.env.BANKR_API_KEY;
const LLM_KEY = process.env.BANKR_LLM_KEY || API_KEY;

if (!API_KEY) {
  throw new Error("BANKR_API_KEY not set. Get one at https://bankr.bot/api");
}

Storage rules:

• Environment variables for server-side agents and CI/CD
• ~/.bankr/config.json for local development (CLI manages this)
• Never commit keys to source control
• Add ~/.bankr/, .env to .gitignore
• Rotate periodically, revoke immediately if compromised

Transaction Safety

• /agent/submit executes immediately with no confirmation prompt
• Always use waitForConfirmation: true for important transactions
• Test with small amounts on Base/Polygon first
• Verify calldata source for arbitrary transactions

Related Skills

• bankr-client-patterns - Client setup with error handling
• bankr-api-basics - API fundamentals
• bankr-sign-submit-api - Sync endpoints that need extra caution