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