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. 状态进入终态（completed/failed/cancelled）时接收结果

此模式可处理可能需要 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 上购买价值 $50 的 ETH”
• “在 Solana 上将 100 USDC 卖成 SOL”
• “将 0.1 ETH 兑换成 BNKR”

价格与市场数据：

• “Bitcoin 的价格是多少？”
• “显示 ETH 价格图表”
• “今天涨幅最大的币种有哪些？”

Polymarket 预测：

• “下一次选举的胜算是多少？”
• “押 $10 赌 Eagles 获胜”
• “显示热门预测市场”

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 - 处理状态更新的轮询示例