Bankr Dev - API Basics

Bankr Agent API の基本

Bankr API に関する質問に回答する際は、次の点に従ってください。

1. 非同期ジョブのパターン（送信・ポーリング・完了）を説明します
2. 以下のエンドポイントのドキュメントと TypeScript の例を参照します
3. 詳細なレスポンス構造については、references/job-response-schema.md を確認します
4. 開発者には、examples/ ディレクトリにある動作するサンプルを案内します

---

Bankr Agent API を使用すると、シンプルな非同期ジョブのパターンを通じて、暗号資産の取引、市場分析、予測市場をプログラムから利用できます。

基本概念：非同期ジョブのパターン

Bankr のすべての操作は、送信・ポーリング・完了のパターンに従います。

1. 自然言語のプロンプトを送信してジョブを開始します
2. 2 秒ごとにジョブのステータスをポーリングします
3. ステータスが最終状態（完了／失敗／キャンセル）になったら結果を受け取ります

このパターンは、完了までに 30 秒から 2 分以上かかることがある操作（取引、複雑な分析）に対応します。

API エンドポイント

ベース URL

https://api.bankr.bot

認証

すべてのリクエストで x-api-key ヘッダーが必要です。

x-api-key: bk_your_api_key_here

API キーは、特定のユーザーの Bankr アカウントとウォレットに紐付けられています。

エンドポイント 1：プロンプトの送信

POST /agent/prompt
Content-Type: application/json

{
  "prompt": "Buy $50 of ETH on Base"
}

レスポンス：

{
  "success": true,
  "jobId": "job_abc123",
  "status": "pending"
}

コード例：

async function submitPrompt(prompt: string): Promise<{ jobId: string }> {
  const response = await fetch(`${API_URL}/agent/prompt`, {
    method: "POST",
    headers: {
      "x-api-key": API_KEY,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ prompt }),
  });
  const data = await response.json();
  if (!data.success) throw new Error(data.error || "Failed to submit");
  return { jobId: data.jobId };
}

エンドポイント 2：ジョブのステータスの取得

GET /agent/job/{jobId}

レスポンス：

{
  "success": true,
  "jobId": "job_abc123",
  "status": "completed",
  "prompt": "What is the price of ETH?",
  "response": "Ethereum (ETH) is currently trading at $3,245.67...",
  "transactions": [],
  "statusUpdates": [
    { "message": "Fetching price data...", "timestamp": "2024-01-15T10:00:02Z" }
  ],
  "createdAt": "2024-01-15T10:00:00Z",
  "completedAt": "2024-01-15T10:00:05Z",
  "processingTime": 5000
}

コード例：

async function getJobStatus(jobId: string): Promise<JobStatusResponse> {
  const response = await fetch(`${API_URL}/agent/job/${jobId}`, {
    headers: { "x-api-key": API_KEY },
  });
  return response.json();
}

TypeScript のインターフェースの全容については、references/job-response-schema.md を参照してください。

エンドポイント 3：ジョブのキャンセル

POST /agent/job/{jobId}/cancel
Content-Type: application/json

レスポンス：

{
  "success": true,
  "jobId": "job_abc123",
  "status": "cancelled",
  "prompt": "Buy $50 of ETH on Base",
  "cancelledAt": "2024-01-15T10:00:15Z"
}

キャンセルする場合：

• ユーザーから、実行時間の長い操作を停止するよう求められた場合
• タイムアウトを超過し、正常に中断したい場合
• ジョブが不要になるエラー状態を検出した場合

コード例：

async function cancelJob(jobId: string): Promise<JobStatusResponse> {
  const response = await fetch(`${API_URL}/agent/job/${jobId}/cancel`, {
    method: "POST",
    headers: {
      "x-api-key": API_KEY,
      "Content-Type": "application/json",
    },
  });
  return response.json();
}

// Usage: Cancel if job takes too long
const timeout = setTimeout(async () => {
  console.log("Job taking too long, cancelling...");
  await cancelJob(jobId);
}, 60000); // Cancel after 60 seconds

ジョブのステータス

ステータス	意味	操作
pending	ジョブはキューに入り、まだ開始されていません	ポーリングを続けます
processing	ジョブを実行中です	ポーリングを続け、statusUpdates を確認します
completed	ジョブが正常に完了しました	response と transactions を読み取ります
failed	ジョブでエラーが発生しました	error フィールドを確認します
cancelled	ジョブはキャンセルされました	これ以上の操作は不要です

できること

Bankr API では、次のような自然言語のプロンプトを利用できます。

暗号資産の取引：

• 「Base で ETH を 50 ドル分購入」
• 「Solana で 100 USDC を SOL に交換」
• 「0.1 ETH を BNKR に交換」

価格と市場データ：

• 「ビットコインの価格はいくらですか？」
• 「ETH の価格チャートを表示」
• 「今日の値上がり率上位の銘柄は？」

Polymarket の予測：

• 「次の選挙の当選確率は？」
• 「Eagles の勝利に 10 ドル賭ける」
• 「人気上昇中の予測市場を表示」

DeFi 操作：

• 「Aave の TVL はいくらですか？」
• 「USDC の最良利回りを表示」
• 「ポートフォリオ残高を確認」

ポーリングのベストプラクティス

async function waitForCompletion(jobId: string): Promise<JobStatus> {
  const POLL_INTERVAL = 2000; // 2 seconds
  const MAX_POLLS = 120; // 4 minutes max

  for (let i = 0; i < MAX_POLLS; i++) {
    const status = await getJobStatus(jobId);

    // Terminal states
    if (['completed', 'failed', 'cancelled'].includes(status.status)) {
      return status;
    }

    // Log progress updates
    if (status.statusUpdates?.length) {
      console.log('Progress:', status.statusUpdates.at(-1)?.message);
    }

    await new Promise(r => setTimeout(r, POLL_INTERVAL));
  }

  throw new Error('Job timed out');
}

主なレスポンスフィールド

ジョブが完了すると、レスポンスには次の情報が含まれます。

• response：Bankr からのテキスト回答
• transactions：実行されたトランザクションの配列。チェーンとトークンの詳細を含みます
• richData：画像やチャート（base64 または URL）
• statusUpdates：実行中の進捗メッセージ
• processingTime：処理時間（ミリ秒）

各フィールドの詳細なドキュメントについては、references/job-response-schema.md を参照してください。

エラー処理

次のエラーケースを処理してください。

1. API キーがない：リクエストを送信する前に BANKR_API_KEY を確認します
2. HTTP エラー：API はエラーテキストを含む 4xx／5xx を返します
3. ジョブの失敗：status === 'failed' を確認し、error フィールドを読み取ります
4. タイムアウト：ポーリングの最大回数を設定します（推奨：4 分）

例：一連の処理

// 1. Submit prompt
const { jobId } = await submitPrompt("What is the price of ETH?");

// 2. Poll until complete
const result = await waitForCompletion(jobId);

// 3. Handle result
if (result.status === 'completed') {
  console.log(result.response);
  // "Ethereum (ETH) is currently trading at $3,245.67..."
} else if (result.status === 'failed') {
  console.error('Error:', result.error);
}

関連リソース

参照ファイル

• references/job-response-schema.md - TypeScript インターフェースとフィールドのドキュメントの全容

サンプルファイル

• examples/basic-client.ts - シンプルな API クライアントの実装
• examples/polling-with-updates.ts - ステータス更新を処理するポーリング