Bankr SDK

⚠️ Alpha Release - This SDK is currently in alpha. For support and questions, join our Discord server.

💰 Pricing - Each request costs $0.10 in USDC using standard x402 payment protocol.

🎯 Recommended Method - Use client.promptAndWait() for the simplest experience - it handles everything automatically!

Official SDK for the Bankr API with automatic x402 payment support. Each request costs $0.10 in USDC. This SDK is intended to be used in a secure server environment and not in the browser.

When requesting transactions, ie Buy $5 of $BNKR, Bankr will return transaction data that you can execute with any wallet.

Swap Transactions

For ERC20 token swaps, Bankr uses 0x for routing. To complete a swap from one ERC20 token to another, you will need to approve the AllowanceHolder contract address to move your tokens. The address required for approval can be found in the metadata.allowanceTarget field of the returned transaction data.

Also reference the following documentation:

• https://0x.org/docs/introduction/0x-cheat-sheet#allowanceholder-recommended
• https://github.com/0xProject/0x-settler/blob/master/README.md#allowanceholder-addresses

Prerequisites

Before using the SDK, you need to:

1. USDC Balance: Ensure you have USDC tokens in your wallet for payments. Each request costs $0.10 in USDC.

2. No API Key Required: The v2/prompt endpoint uses standard x402 payment protocol, so no API key is needed.

Quick Start

import { BankrClient } from "@bankr/sdk";

// Initialize client
const client = new BankrClient({
  privateKey: "0x...", // Payment wallet
  walletAddress: "0x...", // Your wallet for transactions
});

// Send a prompt and wait for the result (recommended)
const result = await client.promptAndWait({
  prompt: "What are some trending coins on Base?",
});

console.log(result.response); // "here are some trending coins on base..."

Installation

npm install @bankr/sdk

Usage

Basic Setup

import { BankrClient } from "@bankr/sdk";

const client = new BankrClient({
  privateKey: "0x...", // Required: Payment wallet (derived address used for x402 USDC payments)
  walletAddress: "0x...", // Optional: Context wallet for prompts/transactions (e.g., "What are my balances?" or "Swap ETH to USDC" will use this address)
});

🎯 Recommended: Send Prompt and Wait for Response

Best Practice: Use promptAndWait() for the simplest and most reliable experience. This method sends your prompt and automatically polls until completion or failure.

// Basic query example
const result = await client.promptAndWait({
  prompt: "What's the current price of ETH?",
});

console.log(result.response);
// "The current price of ETH is $2,500..."

// Transaction example - Swap with full response
const swapResult = await client.promptAndWait({
  prompt: "Swap 0.1 ETH to USDC",
});

console.log(swapResult);
// {
//   success: true,
//   jobId: "job_456",
//   status: "completed",
//   prompt: "Swap 0.1 ETH to USDC",
//   response: "I'll help you swap 0.1 ETH to USDC...",
//   transactions: [
//     {
//       type: "swap",
//       metadata: {
//         __ORIGINAL_TX_DATA__: {
//           chain: "base",
//           humanReadableMessage: "Swap 0.1 ETH to USDC",
//           inputTokenAddress: "0x4200000000000000000000000000000000000006",
//           inputTokenAmount: "0.1",
//           inputTokenTicker: "ETH",
//           outputTokenAddress: "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
//           outputTokenTicker: "USDC",
//           receiver: "0x..." // Your context wallet receives the USDC
//         },
//         transaction: {
//           chainId: 8453,
//           to: "0x...",
//           data: "0x...",
//           gas: "300000",
//           value: "100000000000000000" // 0.1 ETH in wei
//         },
//         allowanceTarget: "0x..." // For ERC20->ERC20: approve this address first
//       }
//     }
//   ],
//   richData: [],
//   createdAt: "2024-01-01T00:00:00.000Z",
//   processingTime: 5000
// }

// Execute the transaction with your wallet client
// const tx = await wallet.sendTransaction(swapResult.transactions[0].metadata.transaction);

⚠️ Important: Payment vs Context Wallets

Two Different Wallets: The SDK supports using different wallets for different purposes:

• Payment Wallet (privateKey): Used for x402 USDC payments ($0.10 per request)
• Context Wallet (walletAddress): Used for prompt context and transaction receiver

Examples:

• Swaps: "Swap 0.1 ETH to USDC" → USDC will be sent to your context wallet
• Purchases: "Buy $100 of $BNKR" → Tokens will be sent to your context wallet
• Balance Checks: "What are my balances?" → Checks your context wallet

You can use different wallets: Pay with wallet A, but have transactions sent to wallet B!

Payment Setup

USDC Payment

The SDK uses standard x402 payment protocol with USDC. No token approvals are needed - the SDK automatically handles USDC payments through the x402 protocol.

Advanced: Manual Prompt and Polling

Note: Only use this approach if you need fine-grained control over the prompt submission and status checking. For most use cases, use promptAndWait() instead.

// Step 1: Send a prompt and get a job ID
const response = await client.prompt({
  prompt: "Swap 0.1 ETH to USDC",
  walletAddress: "0x...", // Optional, overrides default context wallet for this prompt
  xmtp: false, // Optional, convert transaction data to XMTP format
});

console.log(response);
// {
//   success: true,
//   jobId: "job_123",
//   status: "pending",
//   message: "Prompt submitted successfully. Use the jobId to check status.",
//   price: {
//     amount: "100000", // $0.10 in USDC (6 decimals)
//     asset: "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913" // USDC on Base
//   }
// }

// Step 2: Manually check status or poll for completion
const status = await client.getJobStatus(response.jobId);
// OR
const result = await client.pollJob({
  jobId: response.jobId,
  interval: 2000,
  maxAttempts: 150,
  timeout: 300000,
});

Using Different Wallets for Payment vs Context

// Example: Pay with one wallet, but have transactions sent to another
const client = new BankrClient({
  privateKey: "0x123...", // Payment wallet (pays $0.10 USDC per request)
  walletAddress: "0x456...", // Context wallet (receives swapped tokens)
});

// This will:
// 1. Pay $0.10 USDC from wallet 0x123... (payment wallet)
// 2. Send the swapped USDC to wallet 0x456... (context wallet)
const response = await client.prompt({
  prompt: "Swap 0.1 ETH to USDC",
});

// You can also override the context wallet per prompt:
const response2 = await client.prompt({
  prompt: "Buy $100 of $BNKR",
  walletAddress: "0x789...", // Send tokens to a different wallet
});

Advanced: Check Job Status

Note: Only needed for manual polling. Use promptAndWait() for automatic polling.

const status = await client.getJobStatus("job_123");
console.log(status);
// Returns JobStatus object with response, transactions, and richData

Advanced: Poll for Completion

Note: Only needed for manual polling. Use promptAndWait() for automatic polling.

const result = await client.pollJob({
  jobId: "job_123",
  interval: 2000, // Check every 2 seconds
  maxAttempts: 150, // Max 5 minutes
  timeout: 300000, // 5 minutes total timeout
});

Cancel a Job

// Cancel a running job
const status = await client.cancelJob("job_123");
console.log(status);
// {
//   success: true,
//   jobId: "job_123",
//   status: "cancelled",
//   prompt: "What's the current price of ETH?",
//   createdAt: "2024-01-01T00:00:00.000Z",
//   cancelledAt: "2024-01-01T00:01:00.000Z"
// }

Payment Integration

The SDK uses x402-fetch to automatically handle x402 payment requirements:

1. Automatic Payment Handling: When a prompt requires payment, x402-fetch automatically creates and signs payments using the provided private key.

2. Dynamic Pricing: The API calculates pricing based on prompt complexity, and x402-fetch handles the payment requirements.

3. Payment Verification: x402-fetch handles payment verification and settlement through the Bankr facilitator.

4. Error Handling: If payment is required but not provided, the SDK will throw an error with payment requirements.

5. Network Support: Supports base network through viem chain configuration.

API Methods Overview

The SDK provides three approaches for sending prompts:

1. promptAndWait() - ✅ RECOMMENDED - Sends prompt and automatically waits for completion

   • Simplest to use
   • Handles polling automatically
   • Best for most use cases

2. prompt() + pollJob() - Manual control over submission and polling

   • Use when you need to store the job ID separately
   • Useful for background processing
   • More complex but gives you fine-grained control

3. prompt() + getJobStatus() - Full manual control

   • Use when implementing custom polling logic
   • Check status on-demand without automatic polling
   • Most complex but most flexible

Configuration

BankrClientConfig

interface BankrClientConfig {
  privateKey: `0x${string}`; // Required: Private key for x402 USDC payments
  walletAddress?: string; // Optional: Default wallet address for prompt context and as transaction receiver (e.g., "What are my balances?" or "Swap ETH to USDC" will send USDC to this address)
}

PromptOptions

interface PromptOptions {
  prompt: string; // Required: The prompt to send
  walletAddress?: string; // Optional: Override default wallet for prompt context and as transaction receiver (e.g., balance lookups, "Swap ETH to USDC" will send USDC to this address)
  xmtp?: boolean; // Optional: Convert transaction data to XMTP call data format
}

PollOptions

interface PollOptions {
  jobId: string; // Required: Job ID to poll
  interval?: number; // Optional: Polling interval in ms
  maxAttempts?: number; // Optional: Max polling attempts
  timeout?: number; // Optional: Total timeout in ms
}

Transaction and Rich Data

The SDK now supports rich transaction data and analytics in job responses:

Transaction Types

The SDK includes comprehensive transaction types:

• SwapTransaction: Token swaps
• ApprovalTransaction: Token approvals
• TransferErc20Transaction: ERC20 token transfers
• TransferEthTransaction: ETH transfers
• ConvertEthToWethTransaction: ETH to WETH conversions
• ConvertWethToEthTransaction: WETH to ETH conversions
• TransferNftTransaction: NFT transfers
• MintManifoldNftTransaction: NFT mints
• BuyNftTransaction: NFT purchases
• AvantisTradeTransaction: Avantis trading
• SwapCrossChainTransaction: Cross-chain swaps/bridges

Rich Data Types

• SocialCard: Analysis cards with text content
• Chart: Chart URLs for data visualization

XMTP Integration

When xmtp: true is set in the prompt options, transaction data is converted to XMTP call data format for seamless integration with XMTP messaging.

Error Handling

The SDK handles various error scenarios:

• 402 Payment Required: When payment is required but not provided
• 400 Bad Request: Invalid prompt or request format
• 500 Internal Server Error: Server-side errors

Networks

Supported networks for payments:

• base (default)

Security

• Private keys are used only for signing payments through x402-fetch
• No private key data is sent to the server
• All payments are signed locally using viem
• Payment verification is handled server-side
• Uses the official x402-fetch library for reliable payment handling