Authentication Overview
Web3 Identity API offers flexible authentication options designed for both Web3-native and traditional applications. Choose the method that best fits your use case and scale requirements.
Quick Comparison
| Method | Daily Limit | Rate Limit | Payment Model | Setup Complexity | Best For |
|---|---|---|---|---|---|
| Anonymous | 100 calls | 100/min | x402 after limit | None | Testing, prototypes |
| SIWE | 200 calls | 200/min | x402 after limit | Wallet signature | Web3 dApps |
| API Key | 10,000+ calls | 1,000/min | Prepaid credits | Key generation | Production backends |
How It Works
Anonymous Access
The simplest way to get started. No authentication required—just make requests.
How It Works
- 100 requests per day per IP address
- 100 requests per minute rate limit
- After daily limit: Pay-per-request via x402
Example
# No auth needed
curl https://api.web3identity.com/api/ens/resolve/vitalik.eth
Response Headers
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 99
X-RateLimit-Reset: 1707350400
When to Use
- ✅ Quick testing and exploration
- ✅ Low-volume personal projects
- ✅ Prototyping and development
- ❌ Production applications (use SIWE or API keys)
SIWE Authentication
Sign-In with Ethereum (EIP-4361) provides wallet-based authentication with enhanced limits.
Benefits
- 2x daily limits (200 calls/day vs 100)
- Wallet-verified identity for audit trails
- No API key management — uses your existing wallet
- Web3-native authentication flow
Authentication Flow
Implementation
import { SiweMessage } from 'siwe';
// 1. Get nonce
const { nonce } = await fetch('/api/auth/nonce').then(r => r.json());
// 2. Create and sign message
const message = new SiweMessage({
domain: 'yourapp.com',
address: walletAddress,
statement: 'Sign in to Web3 Identity API',
uri: 'https://api.web3identity.com',
version: '1',
chainId: 1,
nonce
});
const signature = await wallet.signMessage(message.prepareMessage());
// 3. Verify and get token
const { token } = await fetch('/api/auth/verify', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ message: message.prepareMessage(), signature })
}).then(r => r.json());
// 4. Use token in requests
const data = await fetch('/api/ens/resolve/vitalik.eth', {
headers: { 'Authorization': `Bearer ${token}` }
}).then(r => r.json());
When to Use
- ✅ Web3 dApps with wallet connections
- ✅ User-facing applications
- ✅ When you need 2x free tier limits
- ❌ Server-to-server integrations (use API keys)
API Key Authentication
Traditional API key authentication for high-volume production use.
Benefits
- 10,000+ requests/day depending on tier
- 1,000 requests/minute rate limit
- Prepaid credits — predictable costs
- Server-side friendly — no wallet required
Tiers
| Tier | Daily Limit | Rate Limit | Price |
|---|---|---|---|
| Developer | 10,000 | 500/min | $9/mo |
| Pro | 50,000 | 1,000/min | $29/mo |
| Enterprise | Unlimited | Custom | Contact us |
Implementation
# Include API key in header
curl -H "X-API-Key: atv_live_abc123xyz" \
https://api.web3identity.com/api/ens/resolve/vitalik.eth
const response = await fetch('https://api.web3identity.com/api/ens/resolve/vitalik.eth', {
headers: {
'X-API-Key': process.env.WEB3_IDENTITY_API_KEY
}
});
Security Best Practices
Keep Your Keys Safe
- Never expose API keys in client-side code
- Use environment variables for storage
- Rotate keys periodically
- Use separate keys for dev/staging/production
When to Use
- ✅ Backend services and servers
- ✅ High-volume production applications
- ✅ Traditional web applications
- ❌ Client-side JavaScript (keys will be exposed)
x402 Micropayments
When you exceed free tier limits, pay-per-request with x402 protocol.
How It Works
- Request exceeds daily limit
- API returns
402 Payment Required - Client signs USDC payment on Base
- Include payment proof in retry
- Request succeeds
Pricing
| Endpoint Category | Price per Request |
|---|---|
| Basic (ENS, prices) | $0.005 |
| Standard (DeFi, social) | $0.01 |
| Premium (batch, analytics) | $0.02-0.05 |
Choosing the Right Method
Decision Matrix
| Scenario | Recommended Auth |
|---|---|
| "I'm just exploring the API" | Anonymous |
| "Building a dApp with wallet connect" | SIWE |
| "Need reliable production access" | API Key |
| "Unpredictable traffic spikes" | SIWE + x402 fallback |
| "Enterprise with SLA requirements" | API Key (Enterprise) |