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
• 处理网络错误 — 获取失败时采用退避策略重试

对话线程

// 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 - 同步端点（无需轮询）