Testing & Development

Best practices for testing your integration with the Web3 Identity API.

---

Test Environment

Single Environment

The Web3 Identity API uses a single production environment with a generous free tier for testing. There's no separate sandbox — the free 100 calls/day is your test quota.

Why No Sandbox?

Traditional APIs	Web3 Identity API
Separate test/prod environments	Single environment
Test API keys	No keys needed
Fake test data	Real blockchain data
Complex setup	Zero config

Benefits:

• Test against real data (ENS, Farcaster, prices)
• No environment mismatches
• No test key management
• What works in testing works in production

---

Free Tier for Testing

Tier	Daily Limit	Per Minute	Cost
Anonymous	100 calls	30	Free
SIWE	200 calls	60	Free

100 calls is plenty for:

• Development iteration
• Unit tests
• Integration tests
• CI/CD pipelines

---

Testing Strategies

1. Use Test Addresses

Known addresses for consistent testing:

const TEST_DATA = {
  // Well-known ENS names (always exist)
  ensNames: [
    'vitalik.eth',      // Vitalik Buterin
    'nick.eth',         // Nick Johnson (ENS)
    'brantly.eth',      // Brantly Millegan
  ],
  
  // Addresses with data
  addresses: [
    '0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045', // vitalik.eth
    '0xb8c2C29ee19D8307cb7255e1Cd9CbDE883A267d5', // nick.eth
  ],
  
  // Farcaster users
  farcaster: [
    { fid: 3, username: 'dwr.eth' },      // Dan Romero
    { fid: 2, username: 'v' },            // Varun
  ],
  
  // Token symbols (always have prices)
  tokens: ['ETH', 'BTC', 'USDC', 'USDT'],
};

2. Mock Responses in Tests

Don't hit the API in unit tests — mock responses:

// __mocks__/api.js
export const mockENSProfile = {
  name: 'test.eth',
  address: '0x1234...5678',
  avatar: 'https://example.com/avatar.png',
  records: {
    twitter: 'testuser',
    github: 'testuser',
  },
};

// test.js
jest.mock('./api');
import { mockENSProfile } from './__mocks__/api';

test('displays ENS profile', () => {
  // Use mock data instead of real API
  render(<Profile data={mockENSProfile} />);
  expect(screen.getByText('test.eth')).toBeInTheDocument();
});

3. Integration Tests with Real API

For integration tests, use the real API sparingly:

// integration.test.js
describe('API Integration', () => {
  // Run only in CI or manually
  const runIntegration = process.env.CI || process.env.RUN_INTEGRATION;
  
  (runIntegration ? test : test.skip)('resolves ENS name', async () => {
    const res = await fetch('https://api.web3identity.com/api/ens/resolve/vitalik.eth');
    const data = await res.json();
    
    expect(res.status).toBe(200);
    expect(data.address).toMatch(/^0x/);
  });
});

4. Rate Limit Awareness

// Helper to track API calls
class APITracker {
  constructor(dailyLimit = 100) {
    this.calls = 0;
    this.limit = dailyLimit;
  }
  
  async fetch(url, opts) {
    if (this.calls >= this.limit) {
      throw new Error(`Daily limit (${this.limit}) exceeded`);
    }
    this.calls++;
    console.log(`API call ${this.calls}/${this.limit}`);
    return fetch(url, opts);
  }
  
  remaining() {
    return this.limit - this.calls;
  }
}

const api = new APITracker(100);

---

CI/CD Integration

GitHub Actions Example

# .github/workflows/test.yml
name: Test
on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '20'
      
      - name: Install dependencies
        run: npm ci
      
      - name: Run unit tests
        run: npm test
      
      - name: Run integration tests
        run: npm run test:integration
        env:
          RUN_INTEGRATION: true
        # Only runs ~10 API calls per push

Cache API Responses

// For development/testing, cache responses locally
import fs from 'fs';
import path from 'path';

const CACHE_DIR = '.api-cache';

async function cachedFetch(url) {
  const cacheKey = Buffer.from(url).toString('base64');
  const cachePath = path.join(CACHE_DIR, cacheKey);
  
  // Return cached if exists and fresh
  if (fs.existsSync(cachePath)) {
    const cached = JSON.parse(fs.readFileSync(cachePath));
    if (Date.now() - cached.timestamp < 3600000) { // 1 hour
      console.log('[CACHE HIT]', url);
      return cached.data;
    }
  }
  
  // Fetch and cache
  console.log('[CACHE MISS]', url);
  const res = await fetch(url);
  const data = await res.json();
  
  fs.mkdirSync(CACHE_DIR, { recursive: true });
  fs.writeFileSync(cachePath, JSON.stringify({
    timestamp: Date.now(),
    data,
  }));
  
  return data;
}

---

Local Development

Environment Setup

# .env.local (optional - not required for basic usage)
API_BASE_URL=https://api.web3identity.com

# If using SIWE for higher limits
WALLET_PRIVATE_KEY=0x...  # Test wallet only!

Development Proxy

For local development, proxy API calls to avoid CORS:

// next.config.js (Next.js)
module.exports = {
  async rewrites() {
    return [
      {
        source: '/api/proxy/:path*',
        destination: 'https://api.web3identity.com/api/:path*',
      },
    ];
  },
};

// vite.config.js (Vite)
export default {
  server: {
    proxy: {
      '/api': {
        target: 'https://api.web3identity.com',
        changeOrigin: true,
      },
    },
  },
};

---

Testing x402 Payments

Test Wallet Setup

1. Create test wallet — New wallet for testing only
2. Fund on Base — Get Base ETH from faucet + small USDC
3. Test small amounts — Endpoints cost $0.001-$0.05

// Test payment flow
async function testPayment() {
  // 1. Make request that triggers 402
  const res = await fetch('https://api.web3identity.com/api/ens/vitalik.eth');
  
  if (res.status === 402) {
    const paymentDetails = await res.json();
    console.log('Payment required:', paymentDetails);
    
    // 2. Sign payment (using SDK)
    const client = new ATVClient({ signer: wallet });
    const data = await client.getProfile('vitalik.eth');
    
    console.log('Payment successful, data:', data);
  }
}

Monitor Test Spending

// Track spending in tests
let testSpending = 0;
const MAX_TEST_SPEND = 1.00; // $1 max for tests

async function paidFetch(url, price) {
  if (testSpending + price > MAX_TEST_SPEND) {
    throw new Error(`Test spending limit reached: $${testSpending}`);
  }
  testSpending += price;
  // ... make paid request
}

---

Debugging Tools

Postman Collection

Import our Postman collection for interactive testing:

https://api.web3identity.com/postman/Web3-Identity-API.postman_collection.json

cURL Examples

# Quick health check
curl https://api.web3identity.com/api/health

# Test ENS resolution
curl https://api.web3identity.com/api/ens/resolve/vitalik.eth | jq

# Check your usage
curl https://api.web3identity.com/api/usage

# Verbose output for debugging
curl -v https://api.web3identity.com/api/price/ETH

Browser DevTools

// Paste in browser console to test
fetch('https://api.web3identity.com/api/ens/resolve/vitalik.eth')
  .then(r => r.json())
  .then(console.log);

---

Best Practices Summary

Do	Don't
✅ Mock responses in unit tests	❌ Hit real API in every test
✅ Use well-known test addresses	❌ Use random addresses
✅ Cache responses during development	❌ Make duplicate requests
✅ Track API usage in CI	❌ Ignore rate limits
✅ Test payment flow with small amounts	❌ Test with large sums
✅ Use batch endpoints	❌ Make many individual calls

---

Need More Quota?

For extensive testing needs:

1. SIWE Authentication — 2x daily limit (200 calls)
2. API Key Credits — Purchase credits for higher volume
3. Contact us — support@web3identity.com for enterprise testing needs