Bankr Dev Api Basics

Bankr Agent API Essentials

When answering questions about the Bankr API: 1. Explain the asynchronous job pattern (submit-poll-complete) 2. Reference the endpoint documentation and TypeScript examples below 3. For detailed response structures, consult references/job-response-schema.md 4. Point developers to working examples in examples/ directory

---

The Bankr Agent API enables programmatic access to crypto trading, market analysis, and prediction markets through a simple asynchronous job pattern.

Core Concept: Asynchronous Job Pattern

All Bankr operations follow a submit-poll-complete pattern:

1. Submit a natural language prompt to start a job 2. Poll the job status every 2 seconds 3. Receive results when status is terminal (completed/failed/cancelled)

This pattern handles operations that may take 30 seconds to 2+ minutes (trades, complex analysis).

API Endpoints

Base URL

https://api.bankr.bot

Authentication

All requests require the x-api-key header:

x-api-key: bk_your_api_key_here

The API key is tied to a specific user's Bankr account and wallet.

Endpoint 1: Submit Prompt

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

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

Response:

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

Code example:

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

Endpoint 2: Get Job Status

GET /agent/job/{jobId}

Response:

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

Code example:

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

For complete TypeScript interfaces, see references/job-response-schema.md.

Endpoint 3: Cancel Job

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

Response:

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

When to cancel:

• User requests to stop a long-running operation
• Timeout exceeded and want to abort cleanly
• Detected an error condition that makes the job unnecessary

Code example:

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

Job Status States

What You Can Do

The Bankr API accepts natural language prompts for:

Crypto Trading:

• "Buy $50 of ETH on Base"
• "Sell 100 USDC for SOL on Solana"
• "Swap 0.1 ETH for BNKR"

Price & Market Data:

• "What is the price of Bitcoin?"
• "Show me ETH price chart"
• "What are the top gainers today?"

Polymarket Predictions:

• "What are the odds on the next election?"
• "Bet $10 on the Eagles to win"
• "Show me trending prediction markets"

DeFi Operations:

• "What's the TVL on Aave?"
• "Show me best yields for USDC"
• "Check my portfolio balance"

Polling Best Practices

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

Key Response Fields

When a job completes, the response includes:

• `response`: The text answer from Bankr
• `transactions`: Array of executed transactions with chain/token details
• `richData`: Images or charts (base64 or URL)
• `statusUpdates`: Progress messages during execution
• `processingTime`: Duration in milliseconds

For complete field documentation, see references/job-response-schema.md.

Error Handling

Handle these error cases:

1. Missing API key: Check BANKR_API_KEY before making requests 2. HTTP errors: API returns 4xx/5xx with error text 3. Job failures: Check status === 'failed' and read error field 4. Timeouts: Implement max poll count (recommended: 4 minutes)

Example: Complete Flow

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

Additional Resources

Reference Files

• `references/job-response-schema.md` - Complete TypeScript interfaces and field documentation

Example Files

• `examples/basic-client.ts` - Simple API client implementation
• `examples/polling-with-updates.ts` - Polling with status update handling

Bankr API Response Schema

Complete TypeScript interfaces for the Bankr Agent API responses.

Submit Prompt Response

interface PromptResponse {
  success: boolean;
  jobId?: string;    // Present on success
  status?: string;   // Usually "pending"
  message?: string;  // Info message
  error?: string;    // Present on failure
}

Job Status Response

interface JobStatusResponse {
  success: boolean;
  jobId: string;
  status: "pending" | "processing" | "completed" | "failed" | "cancelled";
  prompt: string;              // Original prompt submitted
  response?: string;           // Final text response (on completion)
  transactions?: Transaction[];// Executed blockchain transactions
  richData?: RichData[];       // Images, charts, visualizations
  statusUpdates?: StatusUpdate[]; // Progress messages
  error?: string;              // Error message (on failure)
  createdAt: string;           // ISO timestamp
  completedAt?: string;        // ISO timestamp (on completion)
  startedAt?: string;          // ISO timestamp (when processing began)
  cancelledAt?: string;        // ISO timestamp (if cancelled)
  processingTime?: number;     // Duration in milliseconds
}

Transaction Structure

Transactions represent blockchain operations executed by Bankr:

interface Transaction {
  type: string;      // Transaction type identifier
  metadata?: {
    // Raw transaction data (for advanced use)
    transaction?: {
      chainId: number;   // Chain ID (e.g., 8453 for Base)
      to: string;        // Contract address
      data: string;      // Encoded call data
      gas?: string;      // Gas limit
      value?: string;    // ETH value in wei
    };
    // Human-readable summary
    humanReadableMessage?: string;  // e.g., "Swapped 0.1 ETH for 150 USDC"
    // Token details for swaps/trades
    inputTokenTicker?: string;      // e.g., "ETH"
    outputTokenTicker?: string;     // e.g., "USDC"
    inputTokenAmount?: string;      // e.g., "0.1"
    outputTokenAmount?: string;     // e.g., "150"
  };
}

Common Chain IDs

Status Update Structure

Status updates provide real-time progress during job execution:

interface StatusUpdate {
  message: string;     // Human-readable progress message
  timestamp: string;   // ISO timestamp
}

Example status updates sequence:

[
  { "message": "Analyzing request...", "timestamp": "2024-01-15T10:00:01Z" },
  { "message": "Fetching current prices...", "timestamp": "2024-01-15T10:00:03Z" },
  { "message": "Preparing transaction...", "timestamp": "2024-01-15T10:00:05Z" },
  { "message": "Executing swap...", "timestamp": "2024-01-15T10:00:08Z" }
]

Rich Data Structure

Rich data includes images, charts, and other media:

interface RichData {
  type: string;       // Content type (e.g., "image/png", "chart")
  base64?: string;    // Base64-encoded content
  url?: string;       // URL to content
}

Usage:

• Check for base64 first for inline content
• Fall back to url for externally hosted content
• The type field indicates how to render/display

Complete Example Response

{
  "success": true,
  "jobId": "job_abc123xyz",
  "status": "completed",
  "prompt": "Buy $50 of ETH on Base",
  "response": "Successfully purchased 0.0154 ETH on Base for $50 USDC.",
  "transactions": [
    {
      "type": "swap",
      "metadata": {
        "humanReadableMessage": "Swapped 50 USDC for 0.0154 ETH on Base",
        "inputTokenTicker": "USDC",
        "outputTokenTicker": "ETH",
        "inputTokenAmount": "50",
        "outputTokenAmount": "0.0154",
        "transaction": {
          "chainId": 8453,
          "to": "0x...",
          "data": "0x...",
          "gas": "150000"
        }
      }
    }
  ],
  "statusUpdates": [
    { "message": "Analyzing request...", "timestamp": "2024-01-15T10:00:01Z" },
    { "message": "Fetching best route...", "timestamp": "2024-01-15T10:00:03Z" },
    { "message": "Executing swap...", "timestamp": "2024-01-15T10:00:08Z" }
  ],
  "richData": [],
  "createdAt": "2024-01-15T10:00:00Z",
  "startedAt": "2024-01-15T10:00:01Z",
  "completedAt": "2024-01-15T10:00:12Z",
  "processingTime": 12000
}

Error Response Example

{
  "success": true,
  "jobId": "job_def456",
  "status": "failed",
  "prompt": "Buy $1000000 of ETH",
  "error": "Insufficient balance. Available: $500 USDC",
  "statusUpdates": [
    { "message": "Analyzing request...", "timestamp": "2024-01-15T10:00:01Z" },
    { "message": "Checking balance...", "timestamp": "2024-01-15T10:00:03Z" }
  ],
  "createdAt": "2024-01-15T10:00:00Z",
  "completedAt": "2024-01-15T10:00:05Z",
  "processingTime": 5000
}