Bankr Agent API Essentials

When answering questions about the Bankr API:

•Explain the asynchronous job pattern (submit-poll-complete)
•Reference the endpoint documentation and TypeScript examples below
•For detailed response structures, consult references/job-response-schema.md
•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:

•Submit a natural language prompt to start a job
•Poll the job status every 2 seconds
•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

code

https://api.bankr.bot

Authentication

All requests require the x-api-key header:

code

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

code

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

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

Response:

json

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

Code example:

typescript

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

code

GET /agent/job/{jobId}

Response:

json

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

typescript

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

code

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

Response:

json

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

typescript

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

Status	Meaning	Action
`pending`	Job queued, not started	Keep polling
`processing`	Job running	Keep polling, check statusUpdates
`completed`	Job finished successfully	Read response and transactions
`failed`	Job encountered error	Check error field
`cancelled`	Job was cancelled	No further action

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

typescript

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:

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

Example: Complete Flow

typescript

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