Bankr Dev - Client Patterns

Bankr Client Patterns

Reusable client code and common files for Bankr API projects.

bankr-client.ts

The core API client module for all Bankr projects:

import "dotenv/config";

const API_URL = process.env.BANKR_API_URL || "https://api.bankr.bot";
const API_KEY = process.env.BANKR_API_KEY;

// ============================================
// Types
// ============================================

export type JobStatus = "pending" | "processing" | "completed" | "failed" | "cancelled";

export interface JobStatusResponse {
  success: boolean;
  jobId: string;
  status: JobStatus;
  prompt: string;
  response?: string;
  transactions?: Transaction[];
  richData?: RichData[];
  statusUpdates?: StatusUpdate[];
  error?: string;
  createdAt: string;
  startedAt?: string;
  completedAt?: string;
  cancelledAt?: string;
  processingTime?: number;
  cancellable?: boolean;
}

export interface StatusUpdate {
  message: string;
  timestamp: string;
}

// Transaction types
export type Transaction =
  | SwapTransaction
  | ApprovalTransaction
  | TransferErc20Transaction
  | TransferEthTransaction
  | ConvertEthToWethTransaction
  | ConvertWethToEthTransaction
  | TransferNftTransaction
  | MintManifoldNftTransaction
  | MintSeaDropNftTransaction
  | BuyNftTransaction
  | AvantisTradeTransaction
  | SwapCrossChainTransaction
  | ManageBankrStakingTransaction;

interface BaseTransactionMetadata {
  __ORIGINAL_TX_DATA__: {
    chain: string;
    humanReadableMessage: string;
    inputTokenAddress: string;
    inputTokenAmount: string;
    inputTokenTicker: string;
    outputTokenAddress: string;
    outputTokenTicker: string;
    receiver: string;
  };
  transaction: {
    chainId: number;
    to: string;
    data: string;
    gas: string;
    gasPrice: string;
    value: string;
  };
}

export interface SwapTransaction {
  type: "swap";
  metadata: BaseTransactionMetadata & {
    approvalRequired?: boolean;
    approvalTx?: { to: string; data: string };
    permit2?: object;
  };
}

export interface ApprovalTransaction {
  type: "approval";
  metadata: BaseTransactionMetadata;
}

export interface TransferErc20Transaction {
  type: "transfer_erc20";
  metadata: BaseTransactionMetadata;
}

export interface TransferEthTransaction {
  type: "transfer_eth";
  metadata: BaseTransactionMetadata;
}

export interface ConvertEthToWethTransaction {
  type: "convert_eth_to_weth";
  metadata: BaseTransactionMetadata;
}

export interface ConvertWethToEthTransaction {
  type: "convert_weth_to_eth";
  metadata: BaseTransactionMetadata;
}

export interface TransferNftTransaction {
  type: "transfer_nft";
  metadata: BaseTransactionMetadata;
}

export interface MintManifoldNftTransaction {
  type: "mint_manifold_nft";
  metadata: BaseTransactionMetadata;
}

export interface MintSeaDropNftTransaction {
  type: "mint_seadrop_nft";
  metadata: BaseTransactionMetadata;
}

export interface BuyNftTransaction {
  type: "buy_nft";
  metadata: BaseTransactionMetadata;
}

export interface AvantisTradeTransaction {
  type: "avantisTrade";
  metadata: {
    chainId: number;
    description: string;
    to: string;
    data: string;
    value?: string;
  };
}

export interface SwapCrossChainTransaction {
  type: "swapCrossChain";
  metadata: {
    chainId: number;
    description: string;
    to: string;
    data: string;
    value: string;
  };
}

export interface ManageBankrStakingTransaction {
  type: "manage_bankr_staking";
  metadata: {
    chainId: number;
    description: string;
    to: string;
    data: string;
    value?: string;
  };
}

// Rich data types
export type RichData = SocialCard | Chart;

export interface SocialCard {
  type: "social-card";
  variant: "analysis";
  text: string;
}

export interface Chart {
  type: "chart";
  url: string;
}

// ============================================
// API Functions
// ============================================

export async function submitPrompt(prompt: string): Promise<{ jobId: string }> {
  if (!API_KEY) {
    throw new Error("BANKR_API_KEY not set. Get one at https://bankr.bot/api");
  }

  const response = await fetch(`${API_URL}/agent/prompt`, {
    method: "POST",
    headers: {
      "x-api-key": API_KEY,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ prompt }),
  });

  if (!response.ok) {
    const text = await response.text();
    throw new Error(`API error ${response.status}: ${text}`);
  }

  const data = await response.json();
  if (!data.success) {
    throw new Error(data.error || "Failed to submit prompt");
  }

  return { jobId: data.jobId };
}

export async function getJobStatus(jobId: string): Promise<JobStatusResponse> {
  if (!API_KEY) {
    throw new Error("BANKR_API_KEY not set");
  }

  const response = await fetch(`${API_URL}/agent/job/${jobId}`, {
    headers: { "x-api-key": API_KEY },
  });

  if (!response.ok) {
    const text = await response.text();
    throw new Error(`API error ${response.status}: ${text}`);
  }

  return response.json();
}

export async function cancelJob(jobId: string): Promise<JobStatusResponse> {
  if (!API_KEY) {
    throw new Error("BANKR_API_KEY not set");
  }

  const response = await fetch(`${API_URL}/agent/job/${jobId}/cancel`, {
    method: "POST",
    headers: {
      "x-api-key": API_KEY,
      "Content-Type": "application/json",
    },
  });

  if (!response.ok) {
    const text = await response.text();
    throw new Error(`API error ${response.status}: ${text}`);
  }

  return response.json();
}

export async function waitForCompletion(
  jobId: string,
  onProgress?: (message: string) => void,
  options?: { pollInterval?: number; maxAttempts?: number }
): Promise<JobStatusResponse> {
  const pollInterval = options?.pollInterval || 2000;
  const maxAttempts = options?.maxAttempts || 150; // 5 minutes max
  let lastUpdateCount = 0;

  for (let attempt = 0; attempt < maxAttempts; attempt++) {
    const status = await getJobStatus(jobId);

    // Report new status updates
    if (onProgress && status.statusUpdates) {
      for (let i = lastUpdateCount; i < status.statusUpdates.length; i++) {
        onProgress(status.statusUpdates[i].message);
      }
      lastUpdateCount = status.statusUpdates.length;
    }

    // Check for terminal states
    if (["completed", "failed", "cancelled"].includes(status.status)) {
      return status;
    }

    await new Promise((resolve) => setTimeout(resolve, pollInterval));
  }

  throw new Error("Job timed out after maximum attempts");
}

/**
 * Execute a Bankr prompt and wait for completion
 * Convenience function that combines submit + poll
 */
export async function execute(
  prompt: string,
  onProgress?: (message: string) => void
): Promise<JobStatusResponse> {
  const { jobId } = await submitPrompt(prompt);
  onProgress?.(`Job submitted: ${jobId}`);
  return waitForCompletion(jobId, onProgress);
}

Common Files

package.json

Base package.json for all Bankr projects:

{
  "name": "{project-name}",
  "version": "0.1.0",
  "description": "{description}",
  "type": "module",
  "main": "dist/index.js",
  "scripts": {
    "build": "tsc",
    "start": "node dist/index.js",
    "dev": "tsx src/index.ts"
  },
  "dependencies": {
    "dotenv": "^16.3.1"
  },
  "devDependencies": {
    "@types/node": "^20.10.0",
    "tsx": "^4.7.0",
    "typescript": "^5.3.0"
  }
}

Framework-Specific Dependencies

Add based on project template:

Web Service (Express):

"dependencies": {
  "express": "^4.18.0"
},
"devDependencies": {
  "@types/express": "^4.17.21"
}

Web Service (Fastify):

"dependencies": {
  "fastify": "^4.25.0"
}

CLI:

"dependencies": {
  "commander": "^12.0.0"
}

tsconfig.json

TypeScript configuration:

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "NodeNext",
    "moduleResolution": "NodeNext",
    "outDir": "./dist",
    "rootDir": "./src",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true,
    "declaration": true
  },
  "include": ["src/**/*"],
  "exclude": ["node_modules", "dist"]
}

.env.example

Environment variables template:

# Bankr API Configuration
BANKR_API_KEY=bk_your_api_key_here
BANKR_API_URL=https://api.bankr.bot

# Optional: Wallet address for context
BANKR_WALLET_ADDRESS=0x...

.gitignore

Standard ignore patterns:

# Dependencies
node_modules/

# Build output
dist/

# Environment
.env
.env.local
.env.*.local

# Logs
*.log
npm-debug.log*

# IDE
.idea/
.vscode/
*.swp
*.swo

# OS
.DS_Store
Thumbs.db

# Testing
coverage/

Usage Patterns

Basic Usage

import { execute } from "./bankr-client";

const result = await execute("What is the price of ETH?", (msg) => {
  console.log("Progress:", msg);
});

console.log(result.response);

With Error Handling

import { execute } from "./bankr-client";

try {
  const result = await execute("Buy $50 of ETH on Base");

  if (result.status === "completed") {
    console.log("Success:", result.response);

    // Handle transactions
    if (result.transactions) {
      for (const tx of result.transactions) {
        console.log(`${tx.type}:`, tx.metadata.__ORIGINAL_TX_DATA__?.humanReadableMessage);
      }
    }
  } else if (result.status === "failed") {
    console.error("Failed:", result.error);
  }
} catch (error) {
  console.error("Error:", error.message);
}

Manual Control

import { submitPrompt, waitForCompletion, cancelJob } from "./bankr-client";

// Submit
const { jobId } = await submitPrompt("Analyze ETH market");

// Set up timeout
const timeout = setTimeout(() => {
  cancelJob(jobId);
}, 120000);

// Wait with custom options
const result = await waitForCompletion(jobId, console.log, {
  pollInterval: 2000,
  maxAttempts: 60,
});

clearTimeout(timeout);

API Reference

Consult the bankr-api-basics skill for:

• Complete endpoint documentation
• Authentication details
• Response field descriptions
• Error codes and handling