SDK Reference

npm install @zan_team/x402 viem

npm install @solana/web3.js @solana/spl-token bs58 tweetnacl

import { createX402Client } from '@zan_team/x402';

// EVM wallet
const client = await createX402Client({
  gatewayUrl: 'https://x402.zan.top',
  privateKey: process.env.PRIVATE_KEY as `0x${string}`,
  autoPayment: true,
  preAuth: true,
});

// Solana wallet
const svmClient = await createX402Client({
  gatewayUrl: 'https://x402.zan.top',
  svmPrivateKey: process.env.SOLANA_KEY, // Base58
  chainType: 'SVM',
  autoPayment: true,
  preAuth: true,
});

interface X402ClientConfig {
  gatewayUrl: string;
  // EVM
  wallet?: WalletClient;
  privateKey?: `0x${string}`;
  // SVM
  svmPrivateKey?: string;       // Base58
  paymentNetwork?: string;      // CAIP-2, e.g. "eip155:8453"
  solanaRpcUrl?: string;
  // Behavior
  chainType?: 'EVM' | 'SVM';   // auto-detected from keys
  autoPayment?: boolean;        // default: false
  defaultBundle?: BundleType;   // default: 'default'
  preAuth?: boolean;            // pre-authenticate on creation
  timeout?: number;             // ms, default: 30000
  aiTimeout?: number;           // ms, default: 120000 (AI calls)
  fetch?: typeof fetch;         // custom fetch implementation
}

const client = await createX402Client({ gatewayUrl, privateKey, autoPayment: true, preAuth: true });

const block = await client.call('eth', 'mainnet', 'eth_blockNumber');
const balance = await client.call('eth', 'mainnet', 'eth_getBalance', ['0x...', 'latest']);
const slot = await client.call('solana', 'mainnet', 'getSlot');

const response = await client.chat('deepseek-v4-flash', {
  messages: [{ role: 'user', content: 'Hello' }],
  max_tokens: 1024,
});

console.log(response.data.content);       // AI response text
console.log(response.data.model);         // model used
console.log(response.data.usage);         // { prompt_tokens, completion_tokens, total_tokens }
console.log(response.data.finish_reason); // "stop"
console.log(response.txHash);            // payment tx hash (null on first call)
console.log(response.paymentNetwork);    // "eip155:8453" (null on first call)

const bal = await client.getBalance();
console.log(bal.balance);         // current credits
console.log(bal.totalPurchased);  // lifetime purchased
console.log(bal.totalConsumed);   // lifetime consumed
console.log(bal.wallet);          // wallet address
console.log(bal.tier);            // "trial" | "standard"

const receipt = await client.purchaseCredits('default');
console.log(receipt.creditsPurchased); // 100000
console.log(receipt.balance);          // new balance
console.log(receipt.txHash);           // on-chain tx hash
console.log(receipt.paymentNetwork);   // "eip155:8453"

const { bundles } = await client.listBundles();
// [{ name: 'default', credits: 100000, price: '0.015', description: '~5,000 RPC calls' }]

const response = await client.fetch('/credits/usage?limit=50', { method: 'GET' });

const health = await client.discovery.health();
// { status: "ok", uptime: 3600 }

const { providers } = await client.discovery.listProviders();
// [{ id: "zan-rpc", name: "ZAN Multi-chain RPC", type: "PROXY", routes: [...] }]

const { networks } = await client.discovery.listNetworks();
// [{ ecosystem: "eth", network: "mainnet", providerId: "zan-rpc" }, ...]

const { bundles } = await client.discovery.listBundles();

const { models } = await client.discovery.listAiModels();
models.forEach(m => {
  console.log(`${m.id}: input=${m.inputPricePerToken}, output=${m.outputPricePerToken}`);
});

import { X402Error, AuthenticationError, InsufficientCreditsError } from '@zan_team/x402';

try {
  await client.call('eth', 'mainnet', 'eth_blockNumber');
} catch (err) {
  if (err instanceof InsufficientCreditsError) {
    console.log(`Need ${err.required} credits, have ${err.balance}`);
  } else if (err instanceof X402Error) {
    console.log(`x402 error: ${err.code} (HTTP ${err.statusCode})`);
  }
}

const client = await createX402Client({
  gatewayUrl: 'https://x402.zan.top',
  privateKey: '0x...',
  autoPayment: true,
  paymentNetwork: 'eip155:8453', // Base Mainnet
});

const client = await createX402Client({
  gatewayUrl: 'https://x402.zan.top',
  svmPrivateKey: '<Base58 secret key>',
  chainType: 'SVM',
  paymentNetwork: 'solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp', // Mainnet
  solanaRpcUrl: 'https://api.mainnet-beta.solana.com',
  autoPayment: true,
  preAuth: true,
});

const client = await createX402Client({
  gatewayUrl: 'https://x402.zan.top',
  privateKey: '0x...',
  autoPayment: false, // handle payments yourself
  preAuth: true,
});

// Check balance before calling
const { balance } = await client.getBalance();
if (balance < 100) {
  await client.purchaseCredits('default');
}

// Now call (will throw InsufficientCreditsError if still not enough)
const block = await client.call('eth', 'mainnet', 'eth_blockNumber');

import {
  InsufficientFundsError,
  AiUpstreamError,
  NetworkError,
} from '@zan_team/x402';

async function reliableCall(client, model, messages) {
  try {
    return await client.chat(model, { messages, max_tokens: 1024 });
  } catch (err) {
    if (err instanceof InsufficientFundsError) {
      // Wallet needs more USDC — alert user
      console.error('Wallet USDC balance too low for payment');
      throw err;
    }
    if (err instanceof AiUpstreamError) {
      // Upstream model failed — not charged, safe to retry with different model
      return await client.chat('deepseek-v4-flash', { messages, max_tokens: 1024 });
    }
    if (err instanceof NetworkError) {
      // Transient network issue — retry after delay
      await new Promise(r => setTimeout(r, 2000));
      return await client.chat(model, { messages, max_tokens: 1024 });
    }
    throw err;
  }
}