@bithaven/mcp-sdk

Open-source TypeScript SDK for Bithaven agent finance. Give your AI agents a USDC wallet with policy guardrails.

Quick Start (< 5 minutes)

1. Install

npm install @bithaven/mcp-sdk

2. Get an API Key

1. Sign up at bithaven.io
2. Create an agent wallet in the dashboard
3. Generate an API key for that wallet
4. Copy the bh_live_... key (shown once)

3. Use It

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

const client = new BithavenClient({
  apiKey: 'bh_live_your_key_here',
});

// Check balance
const balance = await client.checkBalance();
console.log(`Balance: ${balance.balance} ${balance.currency}`);

// Send payment
const tx = await client.sendPayment({
  toAddress: '0x742d35Cc6634C0532925a3b844Bc9e7595f2bD68',
  amount: '10.00',
  memo: 'API credits',
});
console.log(`Sent! TX: ${tx.txHash}`);

Claude Integration

Pass the pre-built tool definitions directly to Claude's tools parameter:

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

const response = await anthropic.messages.create({
  model: 'claude-sonnet-4-5-20250929',
  tools: bithavenTools,
  messages: [{ role: 'user', content: 'Send 5 USDC to 0x...' }],
});

See examples/claude-agent.ts for the full agent loop.

API Reference

BithavenClient

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

Methods

| Method | Description | Returns | |--------|-------------|---------| | checkBalance() | Get wallet balance and remaining spend caps | BalanceResult | | sendPayment(input) | Send USDC (policy-evaluated, on-chain) | SendPaymentResult | | getTxHistory(input?) | Paginated transaction history | TxHistoryResult | | requestApproval(input) | Escalate to human for approval | RequestApprovalResult | | listTools() | Discover available MCP tools | Tool definitions |

Error Handling

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

try {
  await client.sendPayment({ toAddress: '0x...', amount: '100' });
} catch (err) {
  if (err instanceof PolicyDeniedError) {
    console.log('Denied:', err.violations);
    // Fallback: request human approval
    await client.requestApproval({ toAddress: '0x...', amount: '100', reason: 'Large purchase' });
  }
  if (err instanceof InsufficientBalanceError) {
    console.log('Need more funds');
  }
  if (err instanceof RateLimitError) {
    console.log(`Wait ${err.retryAfter}s`);
  }
}

Tools

The SDK exports Claude-compatible tool definitions:

| Tool Name | Scope | Description | |-----------|-------|-------------| | bithaven_check_balance | read | Check balance and spend caps | | bithaven_send_payment | write | Send USDC with policy evaluation | | bithaven_get_tx_history | read | Transaction history | | bithaven_request_approval | write | Request human sign-off |

Rate Limits

| Tool | Limit | |------|-------| | check_balance | 60/min | | send_payment | 10/min | | get_tx_history | 30/min | | request_approval | 5/min |

License

MIT