Quickstart

Get an AI agent sending USDC in under 5 minutes.

Prerequisites

curl or any HTTP client
USDC on Base in an external wallet (for deposits)
Node.js 18+ (for the SDK step)

1Create an Account

Create your account and receive a JWT token. A master wallet with a deposit address is generated automatically.

Request

curl -X POST https://api.bithaven.ai/api/v1/auth/signup \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "password": "your-secure-password"
  }'

Response

{
  "success": true,
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIs...",
    "user": {
      "id": "usr_a1b2c3d4",
      "email": "[email protected]",
      "plan": "free"
    }
  }
}

Tip: Save the token value — you'll use it as a Bearer token for all subsequent requests.

2Get Your Deposit Address

Retrieve your master wallet details, including the Base L2 address where you'll send USDC.

Request

curl https://api.bithaven.ai/api/v1/wallet \
  -H "Authorization: Bearer YOUR_TOKEN"

Response

{
  "success": true,
  "data": {
    "id": "wal_m1n2o3p4",
    "address": "0x4a2e8C9f3B7d1E5a6F0c8D2b4A9e7F1c3B5d8E0a",
    "balance": "0.00"
  }
}

3Deposit USDC

Send USDC on the Base network to your deposit address from any wallet (Coinbase, MetaMask, etc.). Bithaven detects the deposit automatically within ~15 seconds.

You can poll for the deposit to confirm:

Check balance

curl https://api.bithaven.ai/api/v1/wallet/balance \
  -H "Authorization: Bearer YOUR_TOKEN"

# → { "data": { "balance": "100.00", "lastUpdated": "..." } }

4Create an Agent Wallet

Create a sub-wallet for your agent and fund it from your master wallet.

Create wallet

curl -X POST https://api.bithaven.ai/api/v1/agent-wallets \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "label": "my-claude-agent" }'

# → { "data": { "id": "aw_x1y2z3", "label": "my-claude-agent", "balance": "0.00" } }

Fund it

curl -X POST https://api.bithaven.ai/api/v1/agent-wallets/aw_x1y2z3/fund \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "amount": "50.00" }'

# → { "data": { "id": "aw_x1y2z3", "balance": "50.00" } }

5Set a Spending Policy

Add guardrails so your agent can only spend within defined limits.

Daily spend cap

curl -X POST https://api.bithaven.ai/api/v1/agent-wallets/aw_x1y2z3/policies \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "spend_cap_daily",
    "params": { "limit": "25.00" }
  }'

Address whitelist (optional)

curl -X POST https://api.bithaven.ai/api/v1/agent-wallets/aw_x1y2z3/policies \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "address_whitelist",
    "params": {
      "addresses": [
        "0x742d35Cc6634C0532925a3b844Bc9e7595f2bD68"
      ]
    }
  }'

Available policy types: spend_cap_daily, spend_cap_total, address_whitelist. See the Policies guide for details.

6Generate an API Key

Create a scoped API key for the agent. The raw key is only returned once — store it securely.

Request

curl -X POST https://api.bithaven.ai/api/v1/agent-wallets/aw_x1y2z3/keys \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "label": "production" }'

Response

{
  "success": true,
  "data": {
    "id": "key_r4s5t6",
    "label": "production",
    "keyPrefix": "bh_live_a1b2",
    "rawKey": "bh_live_a1b2c3d4e5f6g7h8i9j0..."
  }
}

Tip: The rawKey is only shown at creation time. Store it in your environment variables or a secrets manager.

7Send Your First Payment

Your agent is now autonomous. Install the SDK and start transacting:

Install

npm install @bithaven/mcp-sdk

agent.ts

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

const client = new BithavenClient({
  apiKey: process.env.BITHAVEN_API_KEY!,
});

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

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

The agent authenticates with its API key. All transactions are validated against the policies you set in Step 5. Violations are blocked automatically.

Complete Setup Script

Here's the entire flow as a single Bash script — zero UI interaction required:

setup.sh

#!/bin/bash
# Bithaven headless setup — from zero to agent-ready
set -e

API="https://api.bithaven.ai/api/v1"

# 1. Create account
echo "Creating account..."
AUTH=$(curl -s -X POST "$API/auth/signup" \
  -H "Content-Type: application/json" \
  -d '{"email":"'$1'","password":"'$2'"}')
TOKEN=$(echo $AUTH | jq -r '.data.token')
echo "✓ Account created"

# 2. Get deposit address
WALLET=$(curl -s "$API/wallet" -H "Authorization: Bearer $TOKEN")
ADDRESS=$(echo $WALLET | jq -r '.data.address')
echo "✓ Deposit address: $ADDRESS"
echo "  Send USDC on Base to this address, then press Enter..."
read

# 3. Create agent wallet
AGENT=$(curl -s -X POST "$API/agent-wallets" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"label":"my-agent"}')
AGENT_ID=$(echo $AGENT | jq -r '.data.id')
echo "✓ Agent wallet created: $AGENT_ID"

# 4. Fund agent wallet
curl -s -X POST "$API/agent-wallets/$AGENT_ID/fund" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"amount":"50.00"}' > /dev/null
echo "✓ Funded with 50.00 USDC"

# 5. Set daily spend cap
curl -s -X POST "$API/agent-wallets/$AGENT_ID/policies" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"type":"spend_cap_daily","params":{"limit":"25.00"}}' > /dev/null
echo "✓ Daily spend cap set: 25.00 USDC"

# 6. Generate API key
KEY=$(curl -s -X POST "$API/agent-wallets/$AGENT_ID/keys" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"label":"production"}')
RAW_KEY=$(echo $KEY | jq -r '.data.rawKey')

echo ""
echo "═══════════════════════════════════════════"
echo "  Agent is ready!"
echo "  API Key: $RAW_KEY"
echo "  Wallet:  $AGENT_ID"
echo "  Budget:  50.00 USDC (25.00/day cap)"
echo "═══════════════════════════════════════════"
echo ""
echo "export BITHAVEN_API_KEY=$RAW_KEY"

Usage: bash setup.sh [email protected] your-password

Withdrawals

To withdraw USDC from your master wallet back to an external address, use the Withdraw USDC button on your dashboard, or call the API directly:

Withdraw

curl -X POST $API_URL/api/v1/wallet/withdraw \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"toAddress": "0xYOUR_EXTERNAL_WALLET", "amount": "50.00", "password": "your-password"}'

⚠

Human-only. Withdrawals require password confirmation and are intentionally not available to AI agents via MCP. This is a core security principle: agents can spend within policy, but only humans can move funds out.

8Monitor Agent Activity

Every transaction your agent makes is logged with a full policy audit trail — not just what happened, but why it was allowed. Each evaluation records which policies passed, which failed, and the remaining budget.

Fetch the transaction history for your agent wallet:

Get agent transactions

curl $API_URL/api/v1/agent-wallets/$WALLET_ID/transactions \
  -H "Authorization: Bearer $TOKEN"

# Each transaction includes a policyResult with evaluations:
# {
#   "allowed": true,
#   "evaluations": [
#     { "policyType": "spend_cap_daily", "passed": true,
#       "detail": "Daily spend cap: 0.50 USDC requested, 2.50 of 25 USDC spent today (22.50 remaining)" },
#     { "policyType": "address_whitelist", "passed": true,
#       "detail": "Address 0x1234... matched entry #1 of 3 whitelisted addresses" },
#     { "policyType": "approval_threshold", "passed": true,
#       "detail": "Auto-approved: 0.50 USDC is below 100 USDC escalation threshold" }
#   ]
# }

Or view spend analytics across all agents:

Spend by agent

curl "$API_URL/api/v1/dashboard/spend-by-agent?days=7" \
  -H "Authorization: Bearer $TOKEN"

# Returns per-agent totals:
# [{ "label": "OpenAI Agent", "totalSpent": "12.50", "transactionCount": 8 },
#  { "label": "Compute Agent", "totalSpent": "45.00", "transactionCount": 3 }]

Tip: Audit trails are compliance-grade — designed to be handed to an auditor. “Agent spent $47” is a log entry. “Agent spent $47 — passed daily cap ($200 remaining), matched address whitelist (vendor #3), auto-approved below $100 threshold” is an audit trail.

Next Steps

Claude IntegrationFull agent loop with tool_use LangChain IntegrationWrap as LangChain tools MCP Tool ReferenceAll tools and parameters Policy GuideSpending rules in depth REST API ReferenceFull endpoint documentation OpenAPI SpecMachine-readable API definition