Rate Limits

Limits protect the API and ensure fair usage for everyone.

Daily Limits

Tier	Daily Calls	How to Get
Anonymous	100	Default (no auth needed)
SIWE Authenticated	200	Sign in with Ethereum
API Key	250	Get an API key
x402 Payment	Unlimited	Pay per request

Need More?

After your daily limit, use x402 micropayments for unlimited access at ~$0.005/call.

Check Your Usage

curl https://api.web3identity.com/api/usage

{
  "used": 27,
  "limit": 100,
  "remaining": 73,
  "resetsAt": "2026-02-09T00:00:00Z",
  "tier": "anonymous"
}

Rate Limit Headers

Every response includes rate limit info:

HTTP/1.1 200 OK
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 73
X-RateLimit-Reset: 1707440400

Header	Description
X-RateLimit-Limit	Your daily limit
X-RateLimit-Remaining	Calls remaining today
X-RateLimit-Reset	When limit resets (Unix timestamp)

When You Hit the Limit

The API returns HTTP 429 with retry information:

{
  "error": true,
  "code": "RATE_LIMITED",
  "message": "Rate limit exceeded",
  "retryAfter": 60,
  "remaining": 0
}

Handling 429 Responses

async function fetchWithRetry(url, maxRetries = 3) {
  for (let attempt = 0; attempt <= maxRetries; attempt++) {
    const response = await fetch(url);
    
    if (response.status === 429) {
      const retryAfter = parseInt(response.headers.get('Retry-After')) || 60;
      console.log(`Rate limited. Waiting ${retryAfter}s...`);
      await new Promise(r => setTimeout(r, retryAfter * 1000));
      continue;
    }
    
    return response;
  }
  throw new Error('Rate limit exceeded after retries');
}

warning

Always respect Retry-After. Ignoring it may result in extended rate limiting.

Free Endpoints

These never count against your limit:

Endpoint	Purpose
/api/health	Server health
/api/usage	Check your usage
/api/sources/health	Data source status
/.well-known/x402	Payment discovery

Best Practices

1. Check /api/usage before starting batch operations
2. Authenticate with SIWE for 2x daily limit
3. Use batch endpoints when available
4. Cache responses client-side when appropriate
5. Use x402 payments for unlimited access

Upgrade Paths

Need	Solution
2x daily limit	SIWE Authentication
Predictable billing	API Keys
Unlimited calls	x402 Payments

---

Related: x402 Payments · Error Handling · API Keys