Skip to main content

Frequently Asked Questions

Quick answers to common questions about the Web3 Identity API.

General​

What is the Web3 Identity API?​

The Web3 Identity API provides 966 endpoints for ENS, Farcaster, DeFi, token prices, and more — all without API keys. It's designed for developers who want to add web3 identity features without managing authentication credentials.

Key features:

  • No signup, no API keys
  • 100 free calls per day
  • Pay-per-use after free tier (x402 protocol)
  • Single API for ENS + Farcaster + DeFi + prices

What is x402?​

x402 is a protocol for pay-per-request API payments using cryptocurrency. It's named after the HTTP 402 "Payment Required" status code.

How it works:

  1. You make a request
  2. If you've exceeded the free tier, API returns 402 Payment Required
  3. You sign a USDC transfer authorization
  4. Retry the request with the payment header
  5. API settles the payment and returns data

Why x402?

  • No monthly subscriptions
  • Pay only for what you use
  • Works with any wallet
  • No API key management

Learn more: x402 Payments Concept

How much does it cost?​

Endpoint TypePriceExample
ENS Resolution$0.01/api/ens/vitalik.eth
Token Prices$0.001/api/price/ETH
Farcaster$0.01/api/farcaster/user/dwr
Batch Operations$0.02/api/ens/batch
Historical Data$0.05/api/price/history/ETH

Free tier: 100 calls/day, no payment needed.

Full pricing: Pricing Page

Free Tier​

How do I get more than 100 calls/day?​

Option 1: Sign in with Ethereum (SIWE)

  • Authenticate with your wallet
  • Get 200 calls/day (2x the anonymous limit)
  • No cost, just a signature
import { ATVClient } from '@atv-eth/x402-sdk';

const client = new ATVClient({ privateKey: process.env.WALLET_KEY });
await client.signIn();
// Now you have 200 free calls/day

Option 2: Pay per request

  • After free tier, pay with USDC on Base
  • Prices start at $0.001 per call
  • No subscription needed

Option 3: Enterprise plan

How do I check my usage?​

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

Response:

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

When does the free tier reset?​

Daily at midnight UTC. Check resetsAt in the /api/usage response.

Which endpoints are always free?​

EndpointDescription
/api/healthAPI health check
/api/usageYour usage stats
/api/sources/healthData source status
/api/gasEthereum gas prices
/docsSwagger documentation

Authentication​

Do I need an API key?​

No! The Web3 Identity API doesn't use API keys. Authentication is optional.

Anonymous users:

  • 100 calls/day
  • IP-based rate limiting

Authenticated users (SIWE):

  • 200 calls/day
  • Wallet-based rate limiting
  • Persists across IPs

How do I authenticate?​

Sign in with Ethereum (SIWE):

import { ATVClient } from '@atv-eth/x402-sdk';

const client = new ATVClient({
  privateKey: process.env.WALLET_KEY
});

// Sign a message to prove wallet ownership
await client.signIn();

// All subsequent requests are authenticated
const profile = await client.getProfile('vitalik.eth');

Learn more: Authentication Guide

What wallet do I need for payments?​

Any wallet with USDC on Base (Chain ID 8453):

  • MetaMask
  • Rainbow
  • Coinbase Wallet
  • Any WalletConnect wallet

You need enough USDC to cover your API calls (typical: $0.001-$0.02 per call).

Chains & Networks​

What chains are supported?​

ChainIDENSPricesDeFiGas
Ethereum1✅✅✅✅
Base8453✅*✅✅✅
Arbitrum42161—✅✅✅
Optimism10—✅✅✅
Polygon137—✅✅✅

*Base names (name.base.eth) supported

Do you support testnets?​

Not currently. We focus on production data for mainnet chains. For testing, use the free tier on mainnet with minimal real data.

What about Solana?​

Not yet, but it's on our roadmap. The API currently focuses on EVM chains.

Technical​

What's the base URL?​

https://api.web3identity.com

All endpoints are relative to this base.

Is there a rate limit?​

TierLimitPeriod
Anonymous100 callsPer day
SIWE Authenticated200 callsPer day
Paid (no limit)—Pay per call

Rate limit headers are included in every response:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 58
X-RateLimit-Reset: 2026-02-09T00:00:00Z

Is there an SDK?​

Yes! Install via npm:

npm install @atv-eth/x402-sdk viem

The SDK handles:

  • Automatic payment for 402 responses
  • SIWE authentication
  • Type-safe methods

Learn more: SDK Overview

What data formats are supported?​

Response: Always JSON (except image endpoints like QR codes)

Request: Query parameters for GET, JSON body for POST

How fresh is the data?​

Data TypeFreshness
ENS recordsReal-time (on-chain)
Token prices30 seconds
Farcaster1-5 minutes
DeFi TVL5 minutes
Gas prices12 seconds (per block)

Common Issues​

I'm getting 402 errors​

This means you've exceeded your free tier. Options:

  1. Wait — Free tier resets at midnight UTC
  2. Authenticate — SIWE gives you 200 calls/day
  3. Pay — Use the SDK with a funded wallet
// SDK handles 402 automatically
const client = new ATVClient({
  privateKey: process.env.WALLET_KEY  // Needs USDC on Base
});

ENS name returns 404​

Possible causes:

  • Name not registered
  • Name expired
  • Typo in the name

Check the name on app.ens.domains to verify.

Prices seem wrong​

We aggregate from multiple sources. If you see discrepancies:

  1. Use /api/price/smart/{symbol} — Multi-source median
  2. Check the source field — Know where data comes from
  3. Report issues — Email support@web3identity.com

My IP changed, lost my free tier​

Free tier is tracked by IP for anonymous users. Solutions:

  1. Authenticate with SIWE — Tied to wallet, not IP
  2. Use a static IP — For production deployments

API Documentation​

Where can I try endpoints?​

Swagger UI: api.web3identity.com/api

Interactive documentation where you can:

  • Browse all 966 endpoints
  • See request/response schemas
  • Test endpoints live
  • Generate code snippets

Is there a Postman collection?​

Yes! Download Postman Collection

Where's the OpenAPI spec?​

https://api.web3identity.com/api/openapi.yaml

Import into Postman, Insomnia, or any OpenAPI-compatible tool.

Support​

How do I report a bug?​

Include:

  • Endpoint URL
  • Request parameters
  • Expected vs actual response
  • Timestamp (UTC)

Is there an SLA?​

Current uptime: 99.95%

We monitor 24/7 but don't offer formal SLAs for the public API. Enterprise customers can negotiate SLAs.

Can I get a custom plan?​

Yes! Contact support@web3identity.com for:

  • Higher rate limits
  • Dedicated infrastructure
  • Custom endpoints
  • White-label options

Still Have Questions?​