bankr-dev---api-workflow

SKILL.md

API Workflow

Complete reference for the asynchronous job pattern used by the Bankr Agent API.

Core Pattern: Submit-Poll-Complete

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

Endpoints

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" }

Request fields:

prompt (string, required): Natural language prompt (max 10,000 chars)

threadId (string, optional): Continue existing conversation. Omit for new thread.

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" },
});

Job Status States

Status
Description
Action

pending
Job queued, not started
Keep polling

processing
Job running
Keep polling, show statusUpdates

completed
Finished successfully
Read response and richData

failed
Encountered error
Check error field

cancelled
Was cancelled
No further action

Response Fields

Standard (all states)

success, jobId, threadId, status, prompt, createdAt

Completed

response — Natural language text

richData — Array of structured data (charts, social cards)

transactions — Array of executed transactions

completedAt, processingTime

Processing

statusUpdates — Array of { message, timestamp }

startedAt, cancellable

Failed

error — Error message

completedAt

Cancelled

cancelledAt

Polling Implementation

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");
}

Polling Best Practices

2-second interval — don't poll faster

5-minute timeout — suggest cancellation after that

Track shown updates — only display new statusUpdates

Handle network errors — retry with backoff on fetch failures

Conversation Threads

// 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

Rich Data

Completed jobs may include richData:

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

The response field always has a text summary regardless of richData content.

Error Handling

Status
Error
Resolution

400
Invalid request / Prompt too long
Check input (max 10,000 chars)

401
Authentication required
Check API key

403
Agent API not enabled
Enable at bankr.bot/api

404
Job not found
Check jobId is correct

429
Rate limit exceeded
Wait for resetAt timestamp

// 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`);
}

Complete Example

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}`);
  }
}

Related Skills

bankr-api-basics - Endpoint documentation and TypeScript interfaces

bankr-client-patterns - Reusable client code with execute() helper

bankr-sign-submit-api - Synchronous endpoints (no polling needed)