# Web3 Identity API

> Web3 Identity API is a RESTful API providing 1,634 endpoints for blockchain identity resolution, DeFi analytics, social graph data, and real-time token prices. It features a free tier (100 calls/day), SIWE authentication, and x402 micropayments for unlimited access. Payments are settled in USDC on Base network.

Important notes:

- Base URL: `https://api.web3identity.com/api/`
- Free tier: 100 requests/day (anonymous), 200/day (SIWE authenticated)
- x402 micropayments: $0.005-$0.05 per call for unlimited access
- All endpoints return JSON
- No API key required for free tier
- CORS enabled for browser requests

## Authentication

There are four authentication tiers:

1. **Anonymous**: 100 calls/day, no auth required
2. **SIWE (Sign-In With Ethereum)**: 200 calls/day, wallet signature
3. **API Key**: 250 calls/day, issued after SIWE registration
4. **x402 Payments**: Unlimited, pay-per-call with USDC on Base

## Core Endpoints

- [ENS Resolution](https://api.web3identity.com/api/ens/vitalik.eth): Resolve ENS name to address, avatar, records — `GET /api/ens/{name}`
- [Reverse Lookup](https://api.web3identity.com/api/ens/reverse/0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045): Address to ENS name — `GET /api/ens/reverse/{address}`
- [Full Profile](https://api.web3identity.com/api/profile/vitalik.eth): Combined ENS + Farcaster + Lens data — `GET /api/profile/{identifier}`
- [Token Price](https://api.web3identity.com/api/price/eth): Real-time prices from 5 sources — `GET /api/price/{symbol}`
- [DeFi TVL](https://api.web3identity.com/api/defi/tvl/aave): Protocol TVL from DefiLlama — `GET /api/defi/tvl/{protocol}`
- [Wallet Balance](https://api.web3identity.com/api/balance/0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045): ETH balance for address — `GET /api/balance/{address}`

## Social Endpoints

- [Farcaster Profile](https://api.web3identity.com/api/farcaster/user/vitalik.eth): User profile, followers, following — `GET /api/farcaster/user/{identifier}`
- [Farcaster Casts](https://api.web3identity.com/api/farcaster/casts/vitalik.eth): Recent casts from user — `GET /api/farcaster/casts/{identifier}`
- [Lens Profile](https://api.web3identity.com/api/lens/profile/stani): Lens Protocol profile — `GET /api/lens/profile/{handle}`
- [EFP Following](https://api.web3identity.com/api/efp/following/vitalik.eth): Ethereum Follow Protocol data — `GET /api/efp/following/{identifier}`

## DeFi & Market Data

- [Protocol List](https://api.web3identity.com/api/defi/protocols): All tracked DeFi protocols — `GET /api/defi/protocols`
- [Yields](https://api.web3identity.com/api/defi/yields): Current DeFi yields — `GET /api/defi/yields`
- [Gas Prices](https://api.web3identity.com/api/gas): Current Ethereum gas prices — `GET /api/gas`
- [Token Info](https://api.web3identity.com/api/token/eth): Token metadata and market data — `GET /api/token/{symbol}`

## Agent Identity Registration (aboutme.eth Subnames)

AI agents and users can register their own `.aboutme.eth` subname as a decentralized identity. Cost: **$0.97/year** via x402 micropayment (USDC on Base).

### Registration Flow for Agents

**Step 1: Check availability**
```
GET /api/subnames/aboutme.eth/{label}/available
```
Response: `{ "available": true, "label": "myagent", "parent": "aboutme.eth" }`

**Step 2: Get pricing**
```
GET /api/subnames/aboutme.eth/{label}/pricing
```
Response: `{ "price": "0.97", "currency": "USD", "duration": "1 year" }`

**Step 3: Register with x402 payment**
```
POST /api/subnames/aboutme.eth/register
Content-Type: application/json
X-Payment: <signed-x402-payment-header>

{
  "label": "myagent",
  "owner": "0xYourWalletAddress",
  "duration": 1,
  "records": {
    "description": "AI agent for task automation",
    "url": "https://myagent.example.com",
    "avatar": "https://example.com/avatar.png"
  }
}
```

**Step 4: Verify registration**
```
GET /api/ens/myagent.aboutme.eth
```
Response includes address, avatar, and text records.

### x402 Payment for Subnames

When calling `/register`, the endpoint returns HTTP 402 with payment requirements:

```
HTTP/1.1 402 Payment Required
X-Payment: {"price":"0.97","currency":"USDC","network":"base","recipient":"0xF499102c8707c6501CaAdD2028c6DF1c6C6E813b"}
```

Sign an EIP-712 `TransferWithAuthorization` message authorizing $0.97 USDC transfer, then retry with the signed payment header.

### Subname Endpoints

- [Check Availability](https://api.web3identity.com/api/subnames/aboutme.eth/yourname/available): `GET /api/subnames/aboutme.eth/{label}/available`
- [Get Pricing](https://api.web3identity.com/api/subnames/aboutme.eth/yourname/pricing): `GET /api/subnames/aboutme.eth/{label}/pricing`
- [Register](https://api.web3identity.com/api/subnames/aboutme.eth/register): `POST /api/subnames/aboutme.eth/register` (requires x402)
- [Renew](https://api.web3identity.com/api/subnames/aboutme.eth/renew): `POST /api/subnames/aboutme.eth/renew` (requires x402)
- [Update Records](https://api.web3identity.com/api/subnames/aboutme.eth/records): `POST /api/subnames/aboutme.eth/records` (requires SIWE)

### Web Interface

Humans can register at: https://aboutme.eth.limo

## Documentation

- [OpenAPI Specification](https://api.web3identity.com/openapi.json): Full OpenAPI 3.0 spec with all 1,634 endpoints
- [Interactive Playground](https://api.web3identity.com/playground/): Swagger UI for testing endpoints
- [Documentation Site](https://docs.web3identity.com): Guides, tutorials, and API reference
- [Quick Start Guide](https://docs.web3identity.com/quick-start): Get started in 5 minutes

## Code Examples

```javascript
// ENS Resolution
const response = await fetch('https://api.web3identity.com/api/ens/vitalik.eth');
const data = await response.json();
console.log(data.address); // 0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045

// Full Profile (ENS + Farcaster + Lens)
const profile = await fetch('https://api.web3identity.com/api/profile/vitalik.eth');
const user = await profile.json();
console.log(user.farcaster.followerCount); // 500000+

// Check subname availability
const avail = await fetch('https://api.web3identity.com/api/subnames/aboutme.eth/myagent/available');
const { available } = await avail.json();
console.log(available); // true or false
```

## x402 Payment Flow

When free tier is exhausted or for paid endpoints (like subname registration), endpoints return HTTP 402:

```javascript
// 1. Request returns 402 with payment header
const res = await fetch('https://api.web3identity.com/api/subnames/aboutme.eth/register', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ label: 'myagent', owner: '0x...', duration: 1 })
});

if (res.status === 402) {
  const paymentInfo = JSON.parse(res.headers.get('x-payment'));
  // paymentInfo = { price: "0.97", currency: "USDC", network: "base", recipient: "0x..." }
  
  // 2. Sign EIP-712 TransferWithAuthorization for USDC on Base
  const signature = await wallet.signTypedData(eip712Domain, eip712Types, eip712Value);
  
  // 3. Retry with signed payment
  const paid = await fetch('https://api.web3identity.com/api/subnames/aboutme.eth/register', {
    method: 'POST',
    headers: { 
      'Content-Type': 'application/json',
      'X-Payment': signature,
      'Payment-Signature': signature  // Required for @x402/express
    },
    body: JSON.stringify({ label: 'myagent', owner: '0x...', duration: 1 })
  });
  
  const result = await paid.json();
  console.log(result.name); // myagent.aboutme.eth
}
```

## Optional

- [Health Check](https://api.web3identity.com/api/health): API health and endpoint count — `GET /api/health`
- [Agent Info](https://api.web3identity.com/agent-info): Machine-readable API capabilities for AI agents
- [AI Plugin Manifest](https://api.web3identity.com/.well-known/ai-plugin.json): ChatGPT plugin format manifest
- [Bitcoin Stats](https://api.web3identity.com/api/bitcoin/stats): Bitcoin network statistics
- [NFT Metadata](https://api.web3identity.com/api/nft/ethereum/0xbc4ca0eda7647a8ab7c2061c2e118a18a936f13d/1): NFT collection and token data
- [npm SDK](https://www.npmjs.com/package/@atv-eth/x402-sdk): JavaScript SDK for x402 payments