MCP Tools

The MCP server exposes four tools at /mcp/v1/tools/. All require API key authentication.

Base URL

https://api.bithaven.ai/mcp/v1

Authentication

All MCP endpoints require a Bearer token with your agent wallet API key:

Authorization: Bearer bh_live_your_key_here
Content-Type: application/json
POST/mcp/v1/tools/check_balancescope: read

Returns the agent wallet's current USDC balance and remaining spend caps from active policies.

Request
{}
Response
{
  "success": true,
  "tool": "check_balance",
  "data": {
    "walletId": "uuid",
    "balance": "150.000000",
    "currency": "USDC",
    "dailyCapRemaining": "45.000000",
    "totalCapRemaining": "350.000000"
  }
}
POST/mcp/v1/tools/send_paymentscope: write

Initiates a USDC transfer. The transaction is evaluated against all active policies. If approved, it's signed and broadcast on-chain. If denied, you receive the specific policy violations.

Request
{
  "params": {
    "toAddress": "0x742d35Cc6634C0532925a3b844Bc9e7595f2bD68",
    "amount": "10.00",
    "memo": "API credits"      // optional
  }
}
Response
// Success
{
  "success": true,
  "tool": "send_payment",
  "data": {
    "txId": "uuid",
    "status": "completed",
    "txHash": "0xabc123...",
    "amount": "10.000000",
    "toAddress": "0x742d...2bD68",
    "rejectionReason": null
  }
}

// Policy denial (still HTTP 200)
{
  "success": false,
  "tool": "send_payment",
  "error": {
    "code": "POLICY_DENIED",
    "message": "Exceeds daily spend cap of 50.00 USDC",
    "violations": [
      {
        "policyId": "uuid",
        "policyType": "spend_cap_daily",
        "reason": "Exceeds daily spend cap of 50.00 USDC"
      }
    ]
  },
  "data": { "txId": "uuid", "status": "rejected" }
}
POST/mcp/v1/tools/get_tx_historyscope: read

Returns paginated transaction history for the agent wallet.

Request
{
  "params": {
    "page": 1,      // optional, default 1
    "limit": 20     // optional, default 20, max 100
  }
}
Response
{
  "success": true,
  "tool": "get_tx_history",
  "data": {
    "transactions": [
      {
        "id": "uuid",
        "toAddress": "0x742d...2bD68",
        "amount": "10.000000",
        "memo": "API credits",
        "status": "completed",
        "txHash": "0xabc123...",
        "createdAt": "2026-02-09T15:30:00.000Z"
      }
    ],
    "total": 42,
    "page": 1,
    "limit": 20
  }
}
POST/mcp/v1/tools/request_approvalscope: write

Queues a transaction for human approval. The wallet owner is notified via email and dashboard. They can approve or reject from the approvals page.

Request
{
  "params": {
    "toAddress": "0x742d35Cc6634C0532925a3b844Bc9e7595f2bD68",
    "amount": "500.00",
    "memo": "Cloud compute",     // optional
    "reason": "Exceeds daily cap" // optional
  }
}
Response
{
  "success": true,
  "tool": "request_approval",
  "data": {
    "txId": "uuid",
    "status": "pending",
    "message": "Approval request submitted. The wallet owner has been notified."
  }
}

Tool Discovery

List all available tools and their parameter schemas:

GET/mcp/v1/tools

No authentication required.