Bankr Dev - API Workflow

API ワークフロー

Bankr Agent API で使用される非同期ジョブパターンの完全なリファレンスです。

基本パターン：送信・ポーリング・完了

1. SUBMIT  -> POST /agent/prompt   -> Get jobId + threadId
2. POLL    -> GET /agent/job/{id}  -> Check status every 2s
3. COMPLETE -> Terminal status      -> Process response + richData

エンドポイント

POST /agent/prompt

const response = await fetch(`${API_URL}/agent/prompt`, {
  method: "POST",
  headers: { "x-api-key": API_KEY, "Content-Type": "application/json" },
  body: JSON.stringify({
    prompt: "What is my ETH balance?",
    threadId: "thr_XYZ789", // optional: continue conversation
  }),
});
// → { success: true, jobId: "job_abc123", threadId: "thr_XYZ789", status: "pending" }

リクエストフィールド：

• prompt（文字列、必須）：自然言語のプロンプト（最大10,000文字）
• threadId（文字列、任意）：既存の会話を続行します。新しいスレッドの場合は省略します。

GET /agent/job/{jobId}

const status = await fetch(`${API_URL}/agent/job/${jobId}`, {
  headers: { "x-api-key": API_KEY },
});

POST /agent/job/{jobId}/cancel

const cancel = await fetch(`${API_URL}/agent/job/${jobId}/cancel`, {
  method: "POST",
  headers: { "x-api-key": API_KEY, "Content-Type": "application/json" },
});

ジョブのステータス

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

レスポンスフィールド

標準（すべての状態）

• success、jobId、threadId、status、prompt、createdAt

完了時

• response — 自然言語のテキスト
• richData — 構造化データ（チャート、ソーシャルカード）の配列
• transactions — 実行されたトランザクションの配列
• completedAt、processingTime

処理中

• statusUpdates — { message, timestamp } の配列
• startedAt、cancellable

失敗時

• error — エラーメッセージ
• completedAt

キャンセル時

• cancelledAt

ポーリングの実装

async function waitForCompletion(
  jobId: string,
  onProgress?: (message: string) => void
): Promise<JobStatusResponse> {
  const POLL_INTERVAL = 2000; // 2 seconds
  const MAX_POLLS = 150;      // 5 minutes max
  let lastUpdateCount = 0;

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

    // Report new status updates
    if (onProgress && status.statusUpdates) {
      for (let j = lastUpdateCount; j < status.statusUpdates.length; j++) {
        onProgress(status.statusUpdates[j].message);
      }
      lastUpdateCount = status.statusUpdates.length;
    }

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

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

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

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

• 2秒間隔 — これより短い間隔でポーリングしないでください
• 5分のタイムアウト — その後はキャンセルを提案します
• 表示済みの更新を追跡 — 新しい statusUpdates のみを表示します
• ネットワークエラーに対処 — fetch に失敗した場合は、バックオフして再試行します

会話スレッド

// Start a conversation
const first = await submitPrompt("What is the price of ETH?");
const threadId = first.threadId;

// Continue the conversation (agent remembers context)
const second = await submitPrompt("And what about BTC?", threadId);

// Each response includes the same threadId

リッチデータ

完了したジョブには richData が含まれることがあります。

type RichData = {
  type?: string;          // "social-card", "chart", etc.
  [key: string]: unknown;
};

richData の内容にかかわらず、response フィールドには常にテキストの要約が含まれます。

エラー処理

ステータス	エラー	解決方法
400	リクエストが無効です／プロンプトが長すぎます	入力を確認します（最大10,000文字）
401	認証が必要です	API キーを確認します
403	Agent API が有効になっていません	bankr.bot/api で有効にします
404	ジョブが見つかりません	jobId が正しいことを確認します
429	レート制限を超過しました	resetAt のタイムスタンプまで待ちます

// Handle rate limits
if (response.status === 429) {
  const error = await response.json();
  const waitMs = error.resetAt - Date.now();
  console.log(`Rate limited. Resets in ${Math.ceil(waitMs / 60000)} minutes`);
}

完全な例

import { submitPrompt, waitForCompletion } from "./bankr-client";

async function main() {
  // Submit
  const { jobId } = await submitPrompt("Swap 0.1 ETH for USDC on Base");
  console.log(`Job: ${jobId}`);

  // Poll with progress
  const result = await waitForCompletion(jobId, (msg) => {
    console.log(`Progress: ${msg}`);
  });

  // Handle result
  if (result.status === "completed") {
    console.log(result.response);
    for (const tx of result.transactions || []) {
      console.log(`Transaction: ${tx.type}`);
    }
  } else if (result.status === "failed") {
    console.error(`Failed: ${result.error}`);
  }
}

関連スキル

• bankr-api-basics - エンドポイントのドキュメントと TypeScript インターフェース
• bankr-client-patterns - execute() ヘルパーを使った再利用可能なクライアントコード
• bankr-sign-submit-api - 同期エンドポイント（ポーリングは不要）