@atv-eth/x402-sdk 1.0.0

package/README.md

@@ -0,0 +1,195 @@
+# @atv/x402-sdk
+
+Official SDK for the **ATV x402 Premium API** — ENS resolution, identity profiles, social graphs, and wallet analytics with automatic USDC payments on Base.
+
+## Installation
+
+```bash
+npm install @atv/x402-sdk viem
+```
+
+## Quick Start
+
+```javascript
+import { ATVClient } from '@atv/x402-sdk';
+
+// With x402 payments (USDC on Base)
+const client = new ATVClient({
+  privateKey: process.env.WALLET_KEY,
+});
+
+// Or with API key (prepaid credits)
+const client = new ATVClient({
+  apiKey: 'atv_your_api_key',
+});
+
+// Resolve ENS name
+const result = await client.resolveENS('vitalik.eth');
+console.log(result.address);
+// → 0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045
+```
+
+## Features
+
+- **Automatic x402 payments** — Signs and pays with USDC on Base
+- **Full TypeScript support** — Complete type definitions included
+- **All API endpoints** — Identity, social, wallet, and utilities
+- **Free tier support** — Works without wallet for 100 calls/day
+
+## API Reference
+
+### Identity & ENS
+
+```javascript
+// Resolve ENS name ($0.01)
+await client.resolveENS('vitalik.eth');
+
+// Reverse resolve ($0.01)
+await client.reverseResolve('0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045');
+
+// Full profile ($0.05)
+await client.getProfile('nick.eth');
+
+// ENS valuation ($0.02)
+await client.getENSValue('eth.eth');
+
+// Expiration info ($0.01)
+await client.getExpiration('myname.eth');
+
+// Batch resolve ($0.08)
+await client.batchENS(['vitalik.eth', 'nick.eth', 'brantly.eth']);
+```
+
+### Social Graph
+
+```javascript
+// Follower counts ($0.01)
+await client.getSocialStats('garypalmerjr.eth');
+
+// Followers list ($0.02)
+await client.getFollowers('nick.eth', 50);
+
+// Following list ($0.02)
+await client.getFollowing('nick.eth', 50);
+
+// Mutual connections ($0.03)
+await client.getMutuals('nick.eth');
+
+// Reputation score ($0.03)
+await client.getReputation('vitalik.eth');
+```
+
+### Wallet Analytics
+
+```javascript
+// ETH balance - multi-chain ($0.01)
+await client.getBalance('0x...');
+
+// ERC20 tokens ($0.02)
+await client.getTokens('0x...');
+
+// Transaction history ($0.02)
+await client.getTransactions('0x...');
+
+// NFT holdings ($0.03)
+await client.getNFTs('0x...');
+
+// ENS portfolio ($0.05)
+await client.getPortfolio('0x...');
+```
+
+### Utilities
+
+```javascript
+// Gas prices - free tier ($0.001)
+await client.getGas();
+
+// Contract ABI ($0.02)
+await client.getABI('0x...');
+
+// Trending ENS ($0.02)
+await client.getTrending();
+
+// Leaderboard ($0.02)
+await client.getLeaderboard();
+```
+
+### Free Endpoints
+
+```javascript
+// No payment required
+await client.health();
+await client.usage();
+await client.discovery();
+```
+
+## Payment Methods
+
+### x402 (USDC on Base)
+
+Payments are handled automatically. You need:
+- Wallet private key
+- USDC on Base (chain ID 8453)
+
+```javascript
+const client = new ATVClient({
+  privateKey: '0x...',
+});
+```
+
+### API Key (Prepaid Credits)
+
+Contact atv@web3domains.com for API key provisioning.
+
+```javascript
+const client = new ATVClient({
+  apiKey: 'atv_yourkey',
+});
+```
+
+### Check Balance
+
+```javascript
+const balance = await client.getUSDCBalance();
+console.log(`USDC Balance: ${balance}`);
+```
+
+## Configuration
+
+```javascript
+const client = new ATVClient({
+  // API endpoint (default: https://api.web3domains.com)
+  baseUrl: 'https://api.web3domains.com',
+  
+  // For x402 payments
+  privateKey: '0x...',
+  
+  // OR for prepaid credits
+  apiKey: 'atv_...',
+});
+```
+
+## Error Handling
+
+```javascript
+try {
+  const result = await client.resolveENS('nonexistent.eth');
+} catch (error) {
+  if (error.message.includes('not found')) {
+    console.log('Name not registered');
+  } else if (error.message.includes('Payment required')) {
+    console.log('Insufficient USDC balance');
+  }
+}
+```
+
+## Links
+
+- **API Docs:** https://api.web3domains.com/docs
+- **OpenAPI:** https://api.web3domains.com/openapi.json
+- **Support:** atv@web3domains.com
+- **X/Twitter:** [@ATV_eth](https://twitter.com/ATV_eth)
+
+## License
+
+MIT © ATV (Agent Trust Vector)

package/index.d.ts

@@ -0,0 +1,144 @@
+/**
+ * @atv/x402-sdk - ATV Premium API Client
+ * TypeScript definitions
+ */
+
+import type { Hex } from 'viem';
+
+export interface ATVClientOptions {
+  /** API base URL (default: https://api.web3domains.com) */
+  baseUrl?: string;
+  /** Wallet private key for x402 payments */
+  privateKey?: Hex;
+  /** API key for prepaid credits */
+  apiKey?: string;
+}
+
+export interface ENSRecord {
+  name: string;
+  address: string;
+  records: {
+    avatar?: string | null;
+    twitter?: string | null;
+    url?: string | null;
+    description?: string | null;
+    [key: string]: string | null | undefined;
+  };
+  timestamp: string;
+}
+
+export interface ReverseRecord {
+  address: string;
+  name: string | null;
+  timestamp: string;
+}
+
+export interface Profile {
+  name: string;
+  address: string;
+  avatar?: string | null;
+  records: Record<string, string>;
+  followers: number;
+  following: number;
+  timestamp: string;
+}
+
+export interface ENSValuation {
+  name: string;
+  estimatedUSD: number;
+  range: { low: number; high: number };
+  confidence: 'low' | 'medium' | 'high';
+  factors: string[];
+  length: number;
+  isNumeric: boolean;
+  renewal: string;
+  disclaimer: string;
+}
+
+export interface ENSExpiration {
+  name: string;
+  expiresAt: string;
+  daysUntilExpiry: number;
+  isExpired: boolean;
+  isGracePeriod: boolean;
+  renewalCost: string;
+}
+
+export interface SocialStats {
+  query: string;
+  followers: number;
+  following: number;
+}
+
+export interface GasPrices {
+  mainnet: { wei: string; gwei: string };
+  base: { wei: string; gwei: string };
+  optimism?: { wei: string; gwei: string };
+  arbitrum?: { wei: string; gwei: string };
+  timestamp: string;
+}
+
+export interface HealthStatus {
+  status: string;
+  version: string;
+  uptime: number;
+}
+
+export interface UsageStats {
+  used: number;
+  remaining: number;
+  limit: number;
+  resetIn: string;
+}
+
+export declare class ATVClient {
+  constructor(options?: ATVClientOptions);
+  
+  /** Wallet address (if configured) */
+  readonly address: Hex | undefined;
+  
+  /** Check USDC balance on Base */
+  getUSDCBalance(): Promise<string | null>;
+  
+  /** Make a raw API request */
+  request<T = any>(endpoint: string, options?: RequestInit): Promise<T>;
+  
+  // Free endpoints
+  health(): Promise<HealthStatus>;
+  usage(): Promise<UsageStats>;
+  discovery(): Promise<any>;
+  
+  // Identity & ENS
+  resolveENS(name: string): Promise<ENSRecord>;
+  reverseResolve(address: string): Promise<ReverseRecord>;
+  getProfile(name: string): Promise<Profile>;
+  getAvatar(name: string): Promise<{ name: string; avatar: string | null }>;
+  getENSValue(name: string): Promise<ENSValuation>;
+  getExpiration(name: string): Promise<ENSExpiration>;
+  batchENS(names: string[]): Promise<ENSRecord[]>;
+  getPortfolio(address: string): Promise<any>;
+  
+  // Social Graph
+  getSocialStats(name: string): Promise<SocialStats>;
+  getFollowers(name: string, limit?: number): Promise<any>;
+  getFollowing(name: string, limit?: number): Promise<any>;
+  getMutuals(name: string): Promise<any>;
+  getReputation(name: string): Promise<any>;
+  
+  // Wallet Analytics
+  getBalance(address: string): Promise<any>;
+  getTokens(address: string): Promise<any>;
+  getTransactions(address: string): Promise<any>;
+  getTransfers(address: string): Promise<any>;
+  getNFTs(address: string): Promise<any>;
+  
+  // Utilities
+  getGas(): Promise<GasPrices>;
+  getABI(address: string): Promise<any>;
+  getTrending(): Promise<any>;
+  getLeaderboard(): Promise<any>;
+  getATVInfo(): Promise<any>;
+  getFortune(): Promise<{ fortune: string }>;
+}
+
+export default ATVClient;

package/index.mjs

@@ -0,0 +1,359 @@
+/**
+ * @atv/x402-sdk - ATV Premium API Client
+ * 
+ * Official SDK for the ATV x402 Premium API.
+ * Handles x402 payment flow automatically with USDC on Base.
+ * 
+ * @example
+ * ```javascript
+ * import { ATVClient } from '@atv/x402-sdk';
+ * 
+ * const client = new ATVClient({
+ *   privateKey: process.env.WALLET_KEY,
+ * });
+ * 
+ * const profile = await client.getProfile('vitalik.eth');
+ * ```
+ * 
+ * @version 1.0.0
+ * @license MIT
+ */
+
+import { createWalletClient, createPublicClient, http, getAddress, formatUnits } from 'viem';
+import { privateKeyToAccount } from 'viem/accounts';
+import { base } from 'viem/chains';
+import crypto from 'crypto';
+
+const DEFAULT_BASE_URL = 'https://api.web3domains.com';
+const USDC_BASE = '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913';
+
+/**
+ * ATV x402 API Client
+ */
+export class ATVClient {
+  /**
+   * Create a new ATV client
+   * @param {Object} options - Configuration options
+   * @param {string} [options.baseUrl] - API base URL (default: https://api.web3domains.com)
+   * @param {string} [options.privateKey] - Wallet private key for payments
+   * @param {string} [options.apiKey] - API key for prepaid credits (alternative to x402)
+   */
+  constructor({ baseUrl, privateKey, apiKey } = {}) {
+    this.baseUrl = baseUrl || DEFAULT_BASE_URL;
+    this.apiKey = apiKey;
+    
+    if (privateKey) {
+      this.account = privateKeyToAccount(privateKey);
+      this.walletClient = createWalletClient({
+        account: this.account,
+        chain: base,
+        transport: http(),
+      });
+      this.publicClient = createPublicClient({
+        chain: base,
+        transport: http(),
+      });
+    }
+  }
+
+  /**
+   * Get wallet address (if configured)
+   */
+  get address() {
+    return this.account?.address;
+  }
+
+  /**
+   * Check USDC balance
+   */
+  async getUSDCBalance() {
+    if (!this.publicClient || !this.account) return null;
+    
+    const balance = await this.publicClient.readContract({
+      address: USDC_BASE,
+      abi: [{ name: 'balanceOf', type: 'function', inputs: [{ name: '', type: 'address' }], outputs: [{ name: '', type: 'uint256' }] }],
+      functionName: 'balanceOf',
+      args: [this.account.address],
+    });
+    
+    return formatUnits(balance, 6);
+  }
+
+  /**
+   * Make an API request with automatic x402 payment handling
+   * @param {string} endpoint - API endpoint
+   * @param {Object} [options] - Fetch options
+   * @returns {Promise<any>} - API response
+   */
+  async request(endpoint, options = {}) {
+    const url = `${this.baseUrl}${endpoint}`;
+    const headers = { ...options.headers };
+    
+    // Add API key if configured
+    if (this.apiKey) {
+      headers['X-API-Key'] = this.apiKey;
+    }
+    
+    const response = await fetch(url, { ...options, headers });
+    
+    // Handle 402 Payment Required
+    if (response.status === 402) {
+      if (!this.walletClient) {
+        throw new Error('Payment required but no wallet configured. Provide privateKey or apiKey.');
+      }
+      
+      return this._handlePayment(endpoint, response, options);
+    }
+    
+    if (!response.ok) {
+      const error = await response.json().catch(() => ({ error: response.statusText }));
+      throw new Error(error.error || `HTTP ${response.status}`);
+    }
+    
+    return response.json();
+  }
+
+  /**
+   * Handle x402 payment flow
+   * @private
+   */
+  async _handlePayment(endpoint, initialResponse, options) {
+    const prHeader = initialResponse.headers.get('payment-required');
+    if (!prHeader) throw new Error('No PAYMENT-REQUIRED header');
+    
+    const pr = JSON.parse(Buffer.from(prHeader, 'base64').toString());
+    const requirements = pr.accepts[0];
+    
+    // Create EIP-3009 authorization
+    const nonce = '0x' + crypto.randomBytes(32).toString('hex');
+    const now = Math.floor(Date.now() / 1000);
+    
+    const authorization = {
+      from: this.account.address,
+      to: requirements.payTo,
+      value: requirements.amount,
+      validAfter: (now - 60).toString(),
+      validBefore: (now + requirements.maxTimeoutSeconds).toString(),
+      nonce,
+    };
+    
+    // Sign with EIP-712
+    const chainId = parseInt(requirements.network.split(':')[1]);
+    
+    const signature = await this.walletClient.signTypedData({
+      domain: {
+        name: requirements.extra.name,
+        version: requirements.extra.version,
+        chainId,
+        verifyingContract: getAddress(requirements.asset),
+      },
+      types: {
+        TransferWithAuthorization: [
+          { name: 'from', type: 'address' },
+          { name: 'to', type: 'address' },
+          { name: 'value', type: 'uint256' },
+          { name: 'validAfter', type: 'uint256' },
+          { name: 'validBefore', type: 'uint256' },
+          { name: 'nonce', type: 'bytes32' },
+        ],
+      },
+      primaryType: 'TransferWithAuthorization',
+      message: {
+        from: getAddress(authorization.from),
+        to: getAddress(authorization.to),
+        value: BigInt(authorization.value),
+        validAfter: BigInt(authorization.validAfter),
+        validBefore: BigInt(authorization.validBefore),
+        nonce: authorization.nonce,
+      },
+    });
+    
+    // Create x402 v2 payload
+    const payload = {
+      x402Version: 2,
+      scheme: 'exact',
+      network: requirements.network,
+      accepted: requirements,
+      payload: { signature, authorization },
+    };
+    
+    // Retry with payment
+    const paymentHeader = Buffer.from(JSON.stringify(payload)).toString('base64');
+    const paidResponse = await fetch(`${this.baseUrl}${endpoint}`, {
+      ...options,
+      headers: {
+        ...options.headers,
+        'PAYMENT-SIGNATURE': paymentHeader,
+      },
+    });
+    
+    if (!paidResponse.ok) {
+      const error = await paidResponse.json().catch(() => ({}));
+      throw new Error(error.error || `Payment failed: ${paidResponse.status}`);
+    }
+    
+    return paidResponse.json();
+  }
+
+  // ═══════════════════════════════════════════════════════════════
+  // FREE ENDPOINTS
+  // ═══════════════════════════════════════════════════════════════
+
+  /** Health check */
+  async health() {
+    return this.request('/health');
+  }
+
+  /** Check free tier usage */
+  async usage() {
+    return this.request('/api/usage');
+  }
+
+  /** API discovery */
+  async discovery() {
+    return this.request('/.well-known/x402');
+  }
+
+  // ═══════════════════════════════════════════════════════════════
+  // IDENTITY & ENS ($0.01 - $0.05)
+  // ═══════════════════════════════════════════════════════════════
+
+  /** Resolve ENS name to address */
+  async resolveENS(name) {
+    return this.request(`/api/ens/${encodeURIComponent(name)}`);
+  }
+
+  /** Reverse resolve address to ENS */
+  async reverseResolve(address) {
+    return this.request(`/api/reverse/${address}`);
+  }
+
+  /** Get full identity profile */
+  async getProfile(name) {
+    return this.request(`/api/profile/${encodeURIComponent(name)}`);
+  }
+
+  /** Get avatar URL */
+  async getAvatar(name) {
+    return this.request(`/api/avatar/${encodeURIComponent(name)}`);
+  }
+
+  /** Estimate ENS name value */
+  async getENSValue(name) {
+    return this.request(`/api/ens-value/${encodeURIComponent(name)}`);
+  }
+
+  /** Get ENS expiration info */
+  async getExpiration(name) {
+    return this.request(`/api/expiration/${encodeURIComponent(name)}`);
+  }
+
+  /** Batch resolve multiple ENS names */
+  async batchENS(names) {
+    return this.request('/api/batch/ens', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ names }),
+    });
+  }
+
+  /** Get ENS portfolio for address */
+  async getPortfolio(address) {
+    return this.request(`/api/portfolio/${address}`);
+  }
+
+  // ═══════════════════════════════════════════════════════════════
+  // SOCIAL GRAPH ($0.01 - $0.03)
+  // ═══════════════════════════════════════════════════════════════
+
+  /** Get follower/following counts */
+  async getSocialStats(name) {
+    return this.request(`/api/social/${encodeURIComponent(name)}`);
+  }
+
+  /** Get followers list */
+  async getFollowers(name, limit = 20) {
+    return this.request(`/api/followers/${encodeURIComponent(name)}?limit=${limit}`);
+  }
+
+  /** Get following list */
+  async getFollowing(name, limit = 20) {
+    return this.request(`/api/following/${encodeURIComponent(name)}?limit=${limit}`);
+  }
+
+  /** Get mutual followers */
+  async getMutuals(name) {
+    return this.request(`/api/mutuals/${encodeURIComponent(name)}`);
+  }
+
+  /** Get reputation score */
+  async getReputation(name) {
+    return this.request(`/api/reputation/${encodeURIComponent(name)}`);
+  }
+
+  // ═══════════════════════════════════════════════════════════════
+  // WALLET ANALYTICS ($0.01 - $0.03)
+  // ═══════════════════════════════════════════════════════════════
+
+  /** Get ETH balance (multi-chain) */
+  async getBalance(address) {
+    return this.request(`/api/balance/${address}`);
+  }
+
+  /** Get ERC20 token balances */
+  async getTokens(address) {
+    return this.request(`/api/tokens/${address}`);
+  }
+
+  /** Get transaction history */
+  async getTransactions(address) {
+    return this.request(`/api/txs/${address}`);
+  }
+
+  /** Get token transfers */
+  async getTransfers(address) {
+    return this.request(`/api/transfers/${address}`);
+  }
+
+  /** Get NFT holdings */
+  async getNFTs(address) {
+    return this.request(`/api/nfts/${address}`);
+  }
+
+  // ═══════════════════════════════════════════════════════════════
+  // UTILITIES ($0.001 - $0.02)
+  // ═══════════════════════════════════════════════════════════════
+
+  /** Get current gas prices */
+  async getGas() {
+    return this.request('/api/gas');
+  }
+
+  /** Get contract ABI */
+  async getABI(address) {
+    return this.request(`/api/abi/${address}`);
+  }
+
+  /** Get trending ENS activity */
+  async getTrending() {
+    return this.request('/api/trending');
+  }
+
+  /** Get top accounts leaderboard */
+  async getLeaderboard() {
+    return this.request('/api/leaderboard');
+  }
+
+  /** Get ATV agent info */
+  async getATVInfo() {
+    return this.request('/api/atv');
+  }
+
+  /** Get random security wisdom */
+  async getFortune() {
+    return this.request('/api/fortune');
+  }
+}
+
+// Default export
+export default ATVClient;

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@atv-eth/x402-sdk",
+  "version": "1.0.0",
+  "description": "Official SDK for the ATV x402 Premium API - ENS, identity, social graphs, and wallet analytics with automatic USDC payments on Base",
+  "type": "module",
+  "main": "index.mjs",
+  "types": "index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./index.mjs",
+      "types": "./index.d.ts"
+    }
+  },
+  "files": [
+    "index.mjs",
+    "index.d.ts",
+    "README.md"
+  ],
+  "keywords": [
+    "x402",
+    "ens",
+    "ethereum",
+    "web3",
+    "identity",
+    "api",
+    "usdc",
+    "base",
+    "payments",
+    "atv"
+  ],
+  "author": "ATV (Agent Trust Vector) <atv@web3domains.com>",
+  "license": "MIT",
+  "homepage": "https://api.web3domains.com",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/ATV-eth/x402-sdk"
+  },
+  "bugs": {
+    "url": "https://github.com/ATV-eth/x402-sdk/issues"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "viem": "^2.0.0"
+  },
+  "peerDependencies": {
+    "viem": "^2.0.0"
+  }
+}