@bithaven/mcp-sdk

TypeScript SDK for Bithaven agent finance. Open source, MIT licensed.

Installation

npm install @bithaven/mcp-sdk

Requires Node.js 18+ with native fetch.

Client Setup

import { BithavenClient } from '@bithaven/mcp-sdk';

const client = new BithavenClient({
  apiKey: 'bh_live_...',            // Required — from dashboard
  baseUrl: 'https://api.bithaven.ai', // Optional — defaults to production
});

Methods

checkBalance()→ BalanceResult

Get the agent wallet's current USDC balance and remaining spend caps.

const balance = await client.checkBalance();
// { walletId, balance: "150.00", currency: "USDC",
//   dailyCapRemaining: "45.00", totalCapRemaining: "350.00" }

sendPayment(input)→ SendPaymentResult

Send USDC to a specified address. Evaluated against all active policies before execution.

toAddressstring— Destination Ethereum address (0x...)

amountstring— USDC amount (e.g., "10.50")

memostring?— Optional description

const tx = await client.sendPayment({
  toAddress: '0x742d...2bD68',
  amount: '10.00',
  memo: 'API credits',
});
// { txId, status: "completed", txHash: "0xabc...", amount, toAddress }

getTxHistory(input?)→ TxHistoryResult

Get paginated transaction history for the agent wallet.

pagenumber?— Page number (default: 1)

limitnumber?— Results per page (default: 20, max: 100)

const history = await client.getTxHistory({ page: 1, limit: 10 });
// { transactions: [...], total: 42, page: 1, limit: 10 }

requestApproval(input)→ RequestApprovalResult

Escalate a transaction for human approval. The wallet owner is notified and can approve/reject from the dashboard.

toAddressstring— Destination Ethereum address

amountstring— USDC amount

memostring?— Optional transaction memo

reasonstring?— Why approval is needed

const approval = await client.requestApproval({
  toAddress: '0x742d...2bD68',
  amount: '500.00',
  reason: 'Large purchase - cloud compute credits',
});
// { txId, status: "pending", message: "Approval request submitted" }

Error Handling

The SDK throws typed errors for all failure modes:

import {
  PolicyDeniedError,
  InsufficientBalanceError,
  RateLimitError,
  AuthenticationError,
  ExecutionFailedError,
} from '@bithaven/mcp-sdk';

try {
  await client.sendPayment({ toAddress: '0x...', amount: '100' });
} catch (err) {
  if (err instanceof PolicyDeniedError) {
    // Transaction violated a spending policy
    console.log(err.violations);
    // [{ policyId, policyType: "spend_cap_daily", reason: "Exceeds $50/day cap" }]

    // Fallback: request human approval
    await client.requestApproval({
      toAddress: '0x...',
      amount: '100',
      reason: 'Exceeds daily cap',
    });
  }

  if (err instanceof InsufficientBalanceError) {
    console.log('Wallet needs more USDC');
  }

  if (err instanceof RateLimitError) {
    console.log(`Retry after ${err.retryAfter} seconds`);
  }

  if (err instanceof AuthenticationError) {
    console.log('API key is invalid or revoked');
  }
}

Exports

Export	Kind
`BithavenClient`	Class — main client
`bithavenTools`	Array — Claude tool_use definitions
`toolNameMap`	Object — tool name → MCP endpoint map
`PolicyDeniedError`	Error class
`InsufficientBalanceError`	Error class
`ExecutionFailedError`	Error class
`AuthenticationError`	Error class
`RateLimitError`	Error class
`BithavenError`	Base error class
`BithavenConfig`	Type
`BalanceResult`	Type
`SendPaymentInput / Result`	Types
`TxHistoryInput / Result`	Types
`RequestApprovalInput / Result`	Types