How It Works
Understanding the API architecture helps you build better integrations.
Architecture Overview
┌─────────────┐ ┌─────────────────────┐ ┌─────────────────┐
│ Client │ ──────► │ Web3 Identity API │ ──────► │ Data Sources │
│ (Your App) │ ◄────── │ (api.web3...) │ ◄────── │ (DefiLlama, │
└─────────────┘ └─────────────────────┘ │ Neynar, etc) │
│ │ └─────────────────┘
│ │
│ ▼
│ ┌─────────────────────┐
│ │ CDP Facilitator │
└───────────────►│ (Base Network) │
│ USDC Settlement │
└─────────────────────┘
Request Flow
1. Free Tier
Client → API → Response (if under 100 calls/day)
2. Paid Request (x402)
Client → API → 402 Response
Client → Sign Payment → API → Settle on Base → Response
Payment Protocol (x402)
The x402 protocol enables HTTP-native micropayments:
- Request — You call an endpoint
- 402 Response — If free tier exhausted, API returns payment requirements
- Sign — You sign an EIP-712 authorization to transfer USDC
- Retry — Send the same request with the signed payment
- Settle — API settles the payment on Base via CDP
- Response — You receive the data
Payment Flow Diagram
┌──────────┐ ┌──────────┐ ┌──────────┐
│ Client │ │ API │ │ Base │
└────┬─────┘ └────┬─────┘ └────┬─────┘
│ │ │
│ 1. GET /api/ens/nick.eth │ │
│──────────────────────────────►│ │
│ │ │
│ 2. 402 Payment Required │ │
│◄──────────────────────────────│ │
│ (price, recipient, etc) │ │
│ │ │
│ 3. Sign EIP-712 │ │
│ (local, no network) │ │
│ │ │
│ 4. Retry with X-PAYMENT │ │
│──────────────────────────────►│ │
│ │ 5. Verify + Settle │
│ │──────────────────────────────►│
│ │ │
│ │ 6. Confirmed │
│ │◄──────────────────────────────│
│ │ │
│ 7. 200 OK + Data │ │
│◄──────────────────────────────│ │
│ │ │
Data Sources
The API aggregates data from multiple sources with automatic fallbacks:
| Category | Primary Source | Fallbacks |
|---|---|---|
| Prices | DefiLlama | CoinGecko, CoinCap, CoinPaprika |
| ENS | ENS Subgraph | Direct RPC |
| Farcaster | Neynar | — |
| DeFi | DefiLlama | — |
| Wallet | Alchemy | Etherscan |
Caching
Responses are cached based on data volatility:
| Data Type | Cache TTL |
|---|---|
| Prices | 30 seconds |
| Gas | 15 seconds |
| ENS records | 5 minutes |
| DeFi TVL | 5 minutes |
| Fear & Greed | 1 hour |
Rate Limiting
| Tier | Daily Limit | Per Minute |
|---|---|---|
| Anonymous | 100 | 30 |
| SIWE | 200 | 60 |
| API Key | 500 | 30 |
Next Steps
- Features — See all capabilities
- Pricing — Understand the cost model
- Quick Start — Start building