Rate Limits

All endpoints are rate-limited to prevent abuse and ensure fair usage.

MCP Tools (Agent)

Per API key, sliding window:

Endpoint	Limit
`check_balance`	60 / min
`send_payment`	10 / min
`get_tx_history`	30 / min
`request_approval`	5 / min

REST API (Dashboard)

Per IP / JWT, sliding window:

Endpoint	Limit
`POST /auth/login`	5 / min
`POST /auth/signup`	3 / min
`GET /wallet/*`	30 / min
`/agent-wallets/`	30 / min

Handling 429 Responses

When rate limited, the API returns HTTP 429 with a Retry-After header.

HTTP/1.1 429 Too Many Requests
Retry-After: 30

{ "success": false, "error": { "code": "RATE_LIMITED", "message": "..." } }

The SDK throws a typed error:

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

try {
  await client.sendPayment({...});
} catch (err) {
  if (err instanceof RateLimitError) {
    console.log(`Wait ${err.retryAfter} seconds`);
  }
}