Bankr Dev - Safety & Access Control

安全与访问控制

Bankr API 集成的安全模式和最佳实践。

API 密钥功能标志

每个 API 密钥都有独立的开关，可在 bankr.bot/api 中管理：

标志	控制内容	默认值
agentApiEnabled	/agent/* 端点	false
llmGatewayEnabled	llm.bankr.bot 上的 LLM Gateway	false
readOnly	将 Agent 限制为只读工具	false

分离 Agent 和 LLM 密钥

配置	Agent API 密钥	LLM Gateway 密钥
环境变量	BANKR_API_KEY	BANKR_LLM_KEY（未设置时回退到 API 密钥）
CLI 配置	apiKey	llmKey（未设置时回退到 apiKey）

只读密钥

当 readOnly: true 时：

• /agent/prompt 可以使用，但仅提供读取工具
• /agent/sign 返回 403
• /agent/submit 返回 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 白名单

// 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"
}

专用 Agent 钱包

对于自主 Agent，请创建单独的 Bankr 账户：

1. 使用不同的电子邮箱在 bankr.bot/api 注册
2. 生成启用了 Agent API 的 API 密钥
3. 配置访问控制（readOnly、allowedIps）
4. 充值少量资金

访问控制组合

用例	readOnly	allowedIps	资金
监控机器人	是	是（服务器 IP）	无
交易机器人（服务器）	否	是（服务器 IP）	有限
开发/测试	否	否	少量
研究 Agent	是	否	无

速率限制

层级	每日限额
标准	每天 100 条消息
Bankr Club	每天 1,000 条消息
自定义	为每个 API 密钥单独设置

// 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();
}

密钥管理模式

// 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");
}

存储规则：

• 服务端 Agent 和 CI/CD 使用环境变量
• 本地开发使用 ~/.bankr/config.json（由 CLI 管理）
• 切勿将密钥提交到源代码管理系统
• 将 ~/.bankr/、.env 添加到 .gitignore
• 定期轮换；若密钥遭到泄露，立即撤销

交易安全

• /agent/submit 会立即执行，不会提示确认
• 对于重要交易，始终使用 waitForConfirmation: true
• 先在 Base/Polygon 上用少量资金测试
• 验证任意交易的 calldata 来源

相关技能

• bankr-client-patterns - 配置客户端并处理错误
• bankr-api-basics - API 基础知识
• bankr-sign-submit-api - 需要格外谨慎的同步端点