Bankr Dev - Safety & Access Control

安全性とアクセス制御

Bankr API 統合のセキュリティパターンとベストプラクティスです。

API キーの機能フラグ

各 API キーには、bankr.bot/api で管理する独立した切り替え設定があります。

フラグ	制御対象	デフォルト
agentApiEnabled	/agent/* エンドポイント	false
llmGatewayEnabled	llm.bankr.bot の LLM Gateway	false
readOnly	エージェントを読み取り専用ツールに制限	false

エージェント用キーと LLM 用キーの分離

設定	エージェント 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"
}

専用エージェントウォレット

自律型エージェントを利用する場合は、別の Bankr アカウントを作成します。

1. 別のメールアドレスを使って bankr.bot/api で登録します
2. Agent API を有効にした API キーを生成します
3. アクセス制御（readOnly、allowedIps）を設定します
4. 少額を入金します

アクセス制御の組み合わせ

用途	readOnly	allowedIps	入金額
監視ボット	はい	はい（サーバー IP）	なし
取引ボット（サーバー）	いいえ	はい（サーバー IP）	少額
開発／テスト	いいえ	いいえ	最小限
リサーチエージェント	はい	いいえ	なし

レート制限

ティア	1 日あたりの上限
Standard	100 件／日
Bankr Club	1,000 件／日
Custom	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");
}

保管ルール：

• サーバーサイドのエージェントと 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 - 特に注意が必要な同期エンドポイント