Skip to main content

SDK Overview

The official SDK handles authentication, payments, and API calls.

Installation​

npm install @atv-eth/x402-sdk
Package Info

Note: The npmjs.com web UI may show 403 (Cloudflare protection), but npm install works fine.

Quick Start​

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

// Initialize with your wallet (for payments)
const client = new ATVClient({
  privateKey: process.env.WALLET_KEY, // optional
});

// Make API calls
const profile = await client.getProfile('vitalik.eth');
console.log(profile.address);

Features​

FeatureDescription
Auto-paymentHandles 402 → sign → retry automatically
SIWE AuthBuilt-in Sign-In with Ethereum
Type SafetyFull TypeScript definitions
Batch OperationsEfficient multi-item requests
Error HandlingStructured error types

Configuration​

const client = new ATVClient({
  // Wallet for payments and SIWE
  privateKey: process.env.WALLET_KEY,
  
  // Custom API URL (default: api.web3identity.com)
  baseUrl: 'https://api.web3identity.com',
  
  // Auto-pay when 402 received (default: true)
  autoPayment: true,
  
  // Max price to auto-pay (default: $0.10)
  maxAutoPayment: 0.10,
});

Authentication​

Anonymous (Default)​

No setup required. 100 calls/day free tier.

const client = new ATVClient();
const profile = await client.getProfile('vitalik.eth');

SIWE Authentication​

Sign in for 2x rate limits (200 calls/day).

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

// Sign in
await client.signIn();
console.log(client.isAuthenticated); // true

// Check session
const session = await client.sessionStatus();
console.log(session.address);

// Sign out
await client.signOut();

Payment Handling​

The SDK automatically handles x402 payments:

const client = new ATVClient({
  privateKey: process.env.WALLET_KEY,
  autoPayment: true,      // Auto-sign payments
  maxAutoPayment: 0.10,   // Max $0.10 per call
});

// First 100 calls: free
// After that: auto-pays from your wallet
const profile = await client.getProfile('nick.eth');

Manual Payment Control​

const client = new ATVClient({
  autoPayment: false,  // Disable auto-pay
});

try {
  const profile = await client.getProfile('nick.eth');
} catch (error) {
  if (error.code === 'PAYMENT_REQUIRED') {
    console.log(`Price: ${error.price}`);
    // Decide whether to pay...
    const profile = await client.payAndRetry(error);
  }
}

Error Handling​

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

try {
  const profile = await client.getProfile('notexist.eth');
} catch (error) {
  if (error instanceof ATVError) {
    console.log(error.code);    // "ENS_NOT_FOUND"
    console.log(error.status);  // 404
    console.log(error.message); // "ENS name not registered"
  }
}

Usage Tracking​

// Check remaining calls
const usage = await client.getUsage();
console.log(`${usage.remaining}/${usage.limit} calls remaining`);
console.log(`Resets at: ${usage.resetsAt}`);

// If authenticated
const myUsage = await client.myUsage();
console.log(`Tier: ${myUsage.tier}`);

TypeScript​

Full type definitions included:

import { ATVClient, ENSProfile, FarcasterUser, PriceData } from '@atv-eth/x402-sdk';

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

const profile: ENSProfile = await client.getProfile('vitalik.eth');
const user: FarcasterUser = await client.getFarcasterUser('dwr.eth');
const price: PriceData = await client.getPrice('ETH');

Next Steps​