@bankr/sdk

The official Bankr TypeScript SDK. Instead of managing API keys, you pay $0.10 USDC per request on Base via the x402 payment protocol. Every call is a micropayment — no accounts, no subscriptions, no rate limits. Server-side only.

npm: npmjs.com/package/@bankr/sdk

Installation

npm install @bankr/sdk

pnpm add @bankr/sdk

yarn add @bankr/sdk

bun add @bankr/sdk

Prerequisites

Before using the SDK, make sure you have the following:

USDC balance on Base — at least $0.10 per request. Each SDK call triggers a micropayment via x402.
A private key for the payment wallet — this wallet holds your USDC and signs the x402 payment. It does not need to be the same wallet you trade from.
A wallet address for transactions — the address your agent uses to execute swaps, transfers, and other on-chain actions.
No API key needed — the x402 payment replaces traditional API key authentication entirely.

Quick Start

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

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

const result = await client.promptAndWait({
  prompt: "What are some trending coins on Base?",
});
console.log(result.response);

That is the entire setup. No API key registration, no dashboard, no OAuth flow. The SDK handles x402 payment negotiation, prompt submission, and job polling in a single call.

Methods

`promptAndWait(options)`

The recommended method for most use cases. Submits a natural language prompt, automatically polls for the result, and returns once the job completes (or times out).

const result = await client.promptAndWait({
  prompt: "Buy $10 of PEPE on Base",
  pollInterval: 2000,  // optional, default 2000ms
  timeout: 60000,      // optional, default 60000ms
});
console.log(result.status);   // "completed"
console.log(result.response); // "Successfully bought..."

`prompt(options)`

Submits a prompt and immediately returns a jobId without waiting for the result. Use this when you want manual control over polling — for example, if you need to fire multiple prompts concurrently and collect results later.

const { jobId } = await client.prompt({
  prompt: "What is the price of ETH on Base?",
});
// Poll manually with pollJob()...

`pollJob(jobId, options)`

Polls a specific job by its ID until it reaches a terminal state (completed, failed, or cancelled) or the timeout is reached. Pair this with prompt() for full manual control.

const result = await client.pollJob("job_abc123", {
  pollInterval: 2000,
  timeout: 60000,
});

TypeScript Interfaces

interface BankrClientConfig {
  privateKey: string;     // Payment wallet private key
  walletAddress: string;  // Wallet for transactions
}

interface PromptOptions {
  prompt: string;         // Natural language instruction
  xmtp?: boolean;         // Enable XMTP messaging support
}

interface PollOptions {
  pollInterval?: number;  // Milliseconds between polls (default: 2000)
  timeout?: number;       // Max wait time in ms (default: 60000)
}

BankrClientConfig is passed to the BankrClient constructor. The privateKey is the key for the wallet that holds USDC and pays for each request. The walletAddress is the address your agent uses for on-chain transactions — it can be the same wallet or a different one.
PromptOptions is passed to prompt() and promptAndWait(). The prompt field accepts any natural language instruction. Set xmtp to true to enable XMTP messaging within the prompt context.
PollOptions is passed to pollJob() and optionally to promptAndWait(). The pollInterval controls how frequently the SDK checks the job status, and timeout sets the maximum time to wait before throwing.

ERC20 Swap Flow

When swapping ERC20 tokens (as opposed to swapping from ETH), you may need to approve the AllowanceHolder contract before the swap can execute. This is standard ERC20 behavior — the swap contract needs permission to move tokens on your behalf.

// 1. Submit swap prompt
const result = await client.promptAndWait({
  prompt: "Swap 100 USDC for ETH on Base",
});

// 2. If the response includes allowanceTarget in metadata,
//    approve the AllowanceHolder contract before the swap executes
// See: https://0x.org/docs/introduction/0x-cheat-sheet#allowanceholder-recommended

The SDK will indicate when an approval is needed via the response metadata. The allowanceTarget field contains the contract address you need to approve. Refer to the 0x AllowanceHolder documentation for implementation details.

XMTP Support

The SDK supports XMTP messaging. Pass xmtp: true in your prompt options to enable messaging capabilities within the agent context.

const result = await client.promptAndWait({
  prompt: "Send a message to 0x...",
  xmtp: true,
});

When XMTP is enabled, the agent can send and receive messages through the XMTP protocol as part of executing your prompt. This is useful for agent-to-agent communication and for building conversational interfaces on top of Bankr.

Next Steps

Agent API Overview REST API for full programmatic control — works with any language, supports all chains.

Prompt Endpoint Deep dive into the prompt submission and job polling endpoints.