Bankr x402 SDK - Client Patterns

x402 SDK 客户端模式

Bankr SDK 项目可复用的客户端代码和常用文件。

bankr-client.ts

所有 Bankr SDK 项目的核心 SDK 客户端模块：

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

// ============================================
// Validation
// ============================================

if (!process.env.BANKR_PRIVATE_KEY) {
  throw new Error(
    "BANKR_PRIVATE_KEY environment variable is required. " +
      "This wallet pays $0.01 USDC per request (needs USDC on Base)."
  );
}

// ============================================
// Client Setup
// ============================================

/**
 * Bankr SDK Client
 *
 * Provides AI-powered Web3 operations with x402 micropayments.
 * Each API request costs $0.01 USDC (paid from payment wallet on Base).
 *
 * @example
 * ```typescript
 * import { bankrClient } from "./bankr-client";
 *
 * // Token swap
 * const swap = await bankrClient.promptAndWait({
 *   prompt: "Swap 0.1 ETH to USDC on Base",
 * });
 *
 * // Check balances
 * const balances = await bankrClient.promptAndWait({
 *   prompt: "What are my token balances?",
 * });
 * ```
 *
 * @see https://www.npmjs.com/package/@bankr/sdk
 */
export const bankrClient = new BankrClient({
  // Required: Payment wallet private key
  // This wallet pays $0.01 USDC per API request (must have USDC on Base)
  privateKey: process.env.BANKR_PRIVATE_KEY as `0x${string}`,

  // Optional: Override receiving wallet address
  // If not set, tokens are sent to the payment wallet address
  walletAddress: process.env.BANKR_WALLET_ADDRESS,

  // Optional: API endpoint (defaults to production)
  ...(process.env.BANKR_API_URL && { baseUrl: process.env.BANKR_API_URL }),
});

// Export the wallet address for reference
export const walletAddress = bankrClient.getWalletAddress();

// ============================================
// Types (re-exported from SDK)
// ============================================

export type { JobStatusResponse, Transaction } from "@bankr/sdk";

---

executor.ts

使用 viem 执行交易的辅助模块：

import { createWalletClient, http, type WalletClient } from "viem";
import { privateKeyToAccount } from "viem/accounts";
import { base, mainnet, polygon } from "viem/chains";
import type { Transaction } from "@bankr/sdk";

// Chain configuration
const chains = {
  8453: base,
  1: mainnet,
  137: polygon,
} as const;

// Create wallet client for transaction execution
const account = privateKeyToAccount(
  process.env.BANKR_PRIVATE_KEY as `0x${string}`
);

function getWalletClient(chainId: number): WalletClient {
  const chain = chains[chainId as keyof typeof chains];
  if (!chain) {
    throw new Error(`Unsupported chain ID: ${chainId}`);
  }

  return createWalletClient({
    account,
    chain,
    transport: http(),
  });
}

/**
 * Execute a transaction returned by the Bankr SDK
 *
 * @example
 * ```typescript
 * const result = await bankrClient.promptAndWait({
 *   prompt: "Swap 0.1 ETH to USDC",
 * });
 *
 * if (result.transactions?.length) {
 *   const hash = await executeTransaction(result.transactions[0]);
 *   console.log("Transaction:", hash);
 * }
 * ```
 */
export async function executeTransaction(tx: Transaction): Promise<string> {
  const txData = tx.metadata.transaction;
  const client = getWalletClient(txData.chainId);

  console.log(`Executing ${tx.type} on chain ${txData.chainId}...`);

  const hash = await client.sendTransaction({
    to: txData.to as `0x${string}`,
    data: txData.data as `0x${string}`,
    value: BigInt(txData.value || "0"),
    gas: BigInt(txData.gas),
  });

  console.log(`Transaction submitted: ${hash}`);
  return hash;
}

/**
 * Execute all transactions from a Bankr result
 */
export async function executeAllTransactions(
  transactions: Transaction[]
): Promise<string[]> {
  const hashes: string[] = [];

  for (const tx of transactions) {
    const hash = await executeTransaction(tx);
    hashes.push(hash);
  }

  return hashes;
}

---

常用文件

package.json

所有 Bankr SDK 项目的基础 package.json：

{
  "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": {
    "@bankr/sdk": "^1.0.0",
    "dotenv": "^16.3.1",
    "viem": "^2.0.0"
  },
  "devDependencies": {
    "@types/node": "^20.10.0",
    "tsx": "^4.7.0",
    "typescript": "^5.3.0"
  }
}

特定框架的依赖项

根据项目模板添加：

Web 服务（Express）：

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

CLI：

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

---

tsconfig.json

TypeScript 配置：

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

环境变量模板：

# Bankr SDK Configuration
# See: https://docs.bankr.bot

# Required: Payment wallet private key
# This wallet pays $0.01 USDC per API request (must have USDC on Base)
# Format: 64 hex characters with 0x prefix
BANKR_PRIVATE_KEY=0x

# Optional: Receiving wallet address
# Tokens from swaps/purchases go here. Defaults to payment wallet if not set.
# BANKR_WALLET_ADDRESS=0x

# Optional: API endpoint override (defaults to https://api.bankr.bot)
# BANKR_API_URL=https://api.bankr.bot

---

.gitignore

标准忽略规则：

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

---

使用模式

基本用法

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

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

console.log(result.response);

执行交易

import { bankrClient } from "./bankr-client";
import { executeTransaction } from "./executor";

const result = await bankrClient.promptAndWait({
  prompt: "Swap 0.1 ETH to USDC on Base",
});

if (result.status === "completed" && result.transactions?.length) {
  // Review before executing
  console.log("Transaction ready:", result.transactions[0].type);
  console.log("Details:", result.transactions[0].metadata.__ORIGINAL_TX_DATA__);

  // Execute
  const hash = await executeTransaction(result.transactions[0]);
  console.log("Executed:", hash);
}

错误处理

import { bankrClient } from "./bankr-client";
import { executeAllTransactions } from "./executor";

async function performSwap(prompt: string) {
  try {
    const result = await bankrClient.promptAndWait({
      prompt,
      onStatusUpdate: console.log,
    });

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

      if (result.transactions?.length) {
        const hashes = await executeAllTransactions(result.transactions);
        console.log("Transactions:", hashes);
      }
    } else if (result.status === "failed") {
      console.error("Failed:", result.error);
    }
  } catch (error) {
    console.error("Error:", error.message);
  }
}

不执行交易的查询

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

// Balance queries don't return transactions
const balances = await bankrClient.promptAndWait({
  prompt: "What are my balances on Base?",
});

console.log(balances.response);

// Price queries
const price = await bankrClient.promptAndWait({
  prompt: "Price of DEGEN",
});

console.log(price.response);

---

SDK 参考

请查阅 sdk-capabilities 技能，了解：

• 完整的操作参考
• 支持的链和代币
• 每种操作的提示词示例

请查阅 sdk-token-swaps 技能，了解：

• 兑换模式和授权处理
• 交易执行详情