bankr-dev-api-basics

name	Bankr Dev - API Basics
description	This skill should be used when the user asks about "Bankr API", "Bankr Agent API", "how does Bankr work", "Bankr job status", "Bankr response format", or "building on Bankr". Provides endpoint documentation, job patterns, and TypeScript interfaces.
version	1.0.0

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

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

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

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