Agent Integration Guide

Humans buy identities. Agents rent certainty.

This guide explains how AI agents can integrate with Web3 Identity API to resolve identities, establish trust, and make autonomous decisions.

Why Agents Need Identity Infrastructure

When an AI agent encounters an ENS name or wallet address, it needs to answer:

• "Can I trust this entity?"
• "Is this address linked to a human, DAO, or service?"
• "What claims are authoritative?"
• "Should I allow access, deny, or escalate?"

The agent doesn't want identity. It wants certainty.

What We Provide

Agent Need	Our Solution
Identity resolution	ENS + Farcaster + Lens + Gitcoin Passport
Trust verification	Cryptographically signed CCIP responses
Payment	x402 micropayments (no API keys needed)
Caching	Deterministic, reproducible results
Schema stability	OpenAPI documented, versioned

The Trust Model

Traditional API Trust

Agent → API Key → Provider → Response
         ↓
    Trust required at every step

Problems:

• API keys are secrets to manage
• Account setup requires human in the loop
• Trust is reputation-based

Our Model: Verifiable Trust

Agent → Query → CCIP Gateway → Signed Response
                                    ↓
                    Agent verifies signature on-chain
                                    ↓
                         Trust verified mathematically

The agent doesn't trust us. It trusts math.

Integration Patterns

Pattern 1: Identity Resolution

Resolve an ENS name to rich identity metadata:

curl https://api.web3identity.com/api/ens/resolve/garypalmerjr.eth

Response:

{
  "name": "garypalmerjr.eth",
  "address": "0x701B4937e6c943789ffA74CC8601813b2D87B454",
  "avatar": "https://...",
  "records": {
    "description": "...",
    "url": "...",
    "twitter": "GaryPalmerJr"
  },
  "resolved": true
}

Pattern 2: Multi-Platform Identity

Get identity across ENS, Farcaster, and Lens in one call:

curl https://api.web3identity.com/api/identity/0x701B4937e6c943789ffA74CC8601813b2D87B454

Pattern 3: Trust Scoring

Check Gitcoin Passport score for Sybil resistance:

curl https://api.web3identity.com/api/gitcoin/passport/score/0x...

Pattern 4: CCIP-Read Resolution

For agents that want cryptographic verification, query via CCIP-Read:

1. Query on-chain resolver for *.aboutme.eth
2. Resolver returns OffchainLookup with gateway URL
3. Agent queries gateway
4. Gateway returns signed response
5. Agent verifies signature matches resolver's signer

This provides the strongest trust guarantee.

Payment: x402 Protocol

Agents can pay for API access without API keys:

How It Works

1. Agent makes request
2. If over free tier (100/day), server returns 402 Payment Required
3. Response includes payment details (amount, address, chain)
4. Agent signs EIP-712 typed data with its wallet
5. Agent retries with payment header
6. Server verifies payment, returns data

Code Example

import { createWalletClient } from 'viem';
import { privateKeyToAccount } from 'viem/accounts';
import { base } from 'viem/chains';

const account = privateKeyToAccount(AGENT_PRIVATE_KEY);

// 1. Make initial request
const response = await fetch('https://api.web3identity.com/api/ens/resolve/vitalik.eth');

if (response.status === 402) {
  // 2. Get payment requirements from response
  const paymentInfo = response.headers.get('X-Payment-Required');
  
  // 3. Sign payment authorization
  const signature = await account.signTypedData({
    // EIP-712 typed data for x402 payment
    domain: { name: 'x402', chainId: 8453 },
    types: { Payment: [/* ... */] },
    message: { amount: '1000', recipient: '0x...' }
  });
  
  // 4. Retry with payment
  const paidResponse = await fetch(url, {
    headers: { 'X-Payment': signature }
  });
}

Payment Economics

Tier	Daily Calls	Cost
Free	100	$0.00
x402	Unlimited	$0.005 - $0.08 per call

No subscriptions. No accounts. Just wallet + signature.

Agent Auth Flow

Example: Verifying a user's identity claim

async function verifyIdentityClaim(claimedName) {
  // 1. User claims "I am garypalmerjr.eth"
  
  // 2. Agent queries our gateway
  const identity = await fetch(
    `https://api.web3identity.com/api/ens/resolve/${claimedName}`
  ).then(r => r.json());
  
  // 3. Agent checks claims
  const hasVerifiedTwitter = identity.records?.twitter;
  const hasGitcoinPassport = await checkPassport(identity.address);
  const accountAge = await checkFirstTx(identity.address);
  
  // 4. Agent decides
  if (hasVerifiedTwitter && hasGitcoinPassport && accountAge > 180) {
    return { decision: 'ALLOW', confidence: 0.95 };
  } else if (accountAge > 30) {
    return { decision: 'ALLOW', confidence: 0.7 };
  } else {
    return { decision: 'ESCALATE', reason: 'New account, low verification' };
  }
}

Schema Stability

We guarantee:

• Versioned API — Breaking changes only in major versions
• OpenAPI spec — Machine-readable schema at /openapi.json
• Consistent responses — Same query = same response structure
• Deprecation notices — 90 days before removing endpoints

Agents can cache our schema and rely on it.

Discovery

Agents can discover our capabilities via:

Method	URL
OpenAPI spec	https://api.web3identity.com/openapi.json
AI plugin manifest	https://api.web3identity.com/.well-known/ai-plugin.json
Agent info	https://api.web3identity.com/api/agent-info
Health check	https://api.web3identity.com/api/health

Best Practices

1. Cache Deterministic Results

Identity data changes slowly. Cache for 5-15 minutes:

const CACHE_TTL = 10 * 60 * 1000; // 10 minutes
const cache = new Map();

async function resolveWithCache(name) {
  const cached = cache.get(name);
  if (cached && Date.now() - cached.time < CACHE_TTL) {
    return cached.data;
  }
  const data = await resolve(name);
  cache.set(name, { data, time: Date.now() });
  return data;
}

2. Use Batch Endpoints

Resolve multiple names in one request:

POST /api/ens/batch
Content-Type: application/json

{
  "names": ["vitalik.eth", "nick.eth", "brantly.eth"]
}

3. Handle Rate Limits Gracefully

if (response.status === 429) {
  const retryAfter = response.headers.get('Retry-After');
  await sleep(retryAfter * 1000);
  return retry();
}

4. Verify Critical Data On-Chain

For high-stakes decisions, verify our response against on-chain data:

// Our API response
const apiResult = await fetch('.../ens/resolve/name.eth');

// Verify on-chain
const onChainAddress = await ensContract.read.addr([namehash('name.eth')]);

if (apiResult.address !== onChainAddress) {
  throw new Error('Data mismatch - escalate to human');
}

Example: Complete Agent Integration

class IdentityAgent {
  constructor(walletClient) {
    this.wallet = walletClient;
    this.apiBase = 'https://api.web3identity.com';
  }

  async resolveIdentity(nameOrAddress) {
    const endpoint = nameOrAddress.endsWith('.eth')
      ? `/api/ens/resolve/${nameOrAddress}`
      : `/api/identity/${nameOrAddress}`;
    
    return this.fetchWithPayment(endpoint);
  }

  async assessTrust(address) {
    const [identity, passport, history] = await Promise.all([
      this.resolveIdentity(address),
      this.fetchWithPayment(`/api/gitcoin/passport/score/${address}`),
      this.fetchWithPayment(`/api/wallet/first-tx/${address}`)
    ]);

    return {
      hasENS: !!identity.name,
      hasSocials: !!(identity.records?.twitter || identity.farcaster),
      passportScore: passport.score,
      accountAgeDays: this.daysSince(history.timestamp),
      trustLevel: this.calculateTrust(identity, passport, history)
    };
  }

  async fetchWithPayment(endpoint) {
    let response = await fetch(this.apiBase + endpoint);
    
    if (response.status === 402) {
      const payment = await this.signPayment(response);
      response = await fetch(this.apiBase + endpoint, {
        headers: { 'X-Payment': payment }
      });
    }
    
    return response.json();
  }

  calculateTrust(identity, passport, history) {
    let score = 0;
    if (identity.name) score += 20;
    if (identity.records?.twitter) score += 15;
    if (identity.farcaster) score += 15;
    if (passport.score > 20) score += 25;
    if (this.daysSince(history.timestamp) > 365) score += 25;
    return score;
  }
}

Support

• Docs: docs.web3identity.com
• API Reference: api.web3identity.com/docs
• Status: status.web3identity.com
• Contact: support@web3identity.com

---

Built for the agent economy. Humans buy identities. Agents rent certainty.