Bankr x402 SDK - Client Patterns

What this skill does

# x402 SDK Client Patterns

Reusable client code and common files for Bankr SDK projects.

## bankr-client.ts

The core SDK client module for all Bankr SDK projects:

```typescript
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

Transaction execution helper using viem:

```typescript
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;
}
```

---

## Common Files

### package.json

Base package.json for all Bankr SDK projects:

```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"
  }
}
```

#### Framework-Specific Dependencies

Add based on project template:

**Web Service (Express):**
```json
"dependencies": {
  "express": "^4.18.0"
},
"devDependencies": {
  "@types/express": "^4.17.21"
}
```

**CLI:**
```json
"dependencies": {
  "commander": "^12.0.0"
}
```

---

### tsconfig.json

TypeScript configuration:

```json
{
  "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:

```bash
# 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

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

```typescript
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);
```

### With Transaction Execution

```typescript
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);
}
```

### With Error Handling

```typescript
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);
  }
}
```

### Query Without Transactions

```typescript
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.