Introduction

What is ZAN x402?

ZAN x402 is an AI Agent payment gateway platform launched by ZAN, built on the x402 protocol — an open payment standard initiated by Coinbase. It enables any API to easily implement paid access, where AI Agents can use wallet identity and on-chain USDC for autonomous payments.

Core Value

Why Choose ZAN x402?

1. Traditional API Payments vs ZAN x402

2. Built for the Agent Economy

In the AI Agent era, services need to be autonomously discovered, verified, and paid for by machines. ZAN x402 provides:

• Wallet Identity Authentication: EVM (MetaMask) and SVM (Phantom) wallet signatures replace traditional account registration
• Transparent Payments: On-chain USDC settlement, every transaction verifiable
• Discovery-First: Automatically detect available networks and bundles at startup, seamless integration with dynamic tool catalogs

3. Industry Trend

The x402 protocol was launched by Coinbase in May 2025 and is becoming the standard for AI Agent payments:

• Coinbase x402 Protocol — Open payment protocol enabling AI Agents to make autonomous stablecoin micropayments
• Galaxy Research — x402 makes AI Agents economic actors
• Zuplo MCP Payments — AI Agents autonomously pay for APIs and MCP Servers

Core Features

🔑 Wallet Identity Authentication

• EVM Wallets: MetaMask and other wallet signatures (SIWE)
• SVM Wallets: Phantom and other wallet signatures (SIWS)
• Automatic JWT session acquisition with auto-refresh support

💳 USDC On-Chain Payment

• Settlement Currency: USDC
• Supported Chains: Base, Solana
• Transparent & Verifiable: Every transaction traceable on-chain

📊 Credit System

• Purchase once, use anywhere
• Unified balance management
• Real-time usage tracking

🌐 Multi-Chain RPC Service

📈 Real-time Monitoring

• Track every call and credit change in real-time
• Detailed usage records available

How It Works

┌─────────────┐     ┌─────────────┐     ┌─────────────┐
│   Client    │     │   Gateway   │     │ Facilitator │
│  (AI Agent) │     │  (ZAN x402) │     │ (On-Chain)  │
└──────┬──────┘     └──────┬──────┘     └──────┬──────┘
       │                   │                   │
       │── POST /rpc ─────>│                   │
       │<── 402 ───────────│                   │
       │                   │                   │
       │── POST /purchase ────────────────────>│
       │<── 402 + PAYMENT-REQUIRED ────────────│
       │  [Sign EIP-3009 / Solana SPL]         │
       │                   │                   │
       │── POST /purchase (+signature) ───────>│
       │                   │── POST /verify ──>│
       │                   │<── valid, txHash ─│
       │<── 200 + credits ─│                   │
       │                   │                   │
       │── POST /rpc ─────>│  [Retry]          │
       │<── 200 + result ──│                   │

Three Steps to Get Started:

1. Connect Wallet: MetaMask or Phantom, one signature
2. Purchase Credits: USDC on-chain, instant settlement
3. Call APIs: Credits unlock every API on the platform

Quick Start

# Install
npm install @zan_team/x402 viem

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

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

// Call RPC
const block = await client.call('eth', 'mainnet', 'eth_blockNumber');
console.log('Latest block:', block.result);

For detailed steps, see the Quickstart Guide

SDK Architecture

X402Client
├── auth       AuthModule      SIWE/SIWS + JWT session management
├── credits    CreditsModule   Balance · Purchase · Usage · Payment status
├── rpc        RpcModule       JSON-RPC · Batch calls · Provider forwarding
└── discovery  DiscoveryModule Health check · Network list · Bundle list · x402 capability detection

Subpath Exports

import { AuthModule } from '@zan_team/x402/auth';
import { CreditsModule } from '@zan_team/x402/credits';
import { RpcModule } from '@zan_team/x402/rpc';

Configuration Options

interface X402ClientConfig {
  gatewayUrl: string;           // Gateway URL

  // EVM
  wallet?: WalletClient;        // viem WalletClient
  privateKey?: `0x${string}`;   // Hex private key

  // SVM
  svmPrivateKey?: string;       // Base58 private key
  paymentNetwork?: string;      // CAIP-2, e.g. "eip155:8453"
  solanaRpcUrl?: string;        // Solana RPC URL

  // Behavior config
  chainType?: 'EVM' | 'SVM';    // Auto-detected
  autoPayment?: boolean;        // Auto-purchase when credits insufficient
  defaultBundle?: BundleType;   // Default bundle
  preAuth?: boolean;            // Pre-authenticate on creation
  timeout?: number;             // Timeout in ms, default 30000
  fetch?: typeof fetch;         // Custom fetch implementation
}

Error Handling

Project Structure

zanx402-sdk/
├── src/
│   ├── index.ts                # Public API exports
│   ├── client.ts               # X402Client + createX402Client
│   ├── constants.ts            # Endpoint configuration
│   ├── types/                  # Type definitions
│   ├── modules/                # Feature modules
│   │   ├── auth.ts             # SIWE/SIWS + JWT
│   │   ├── credits.ts          # Credit management
│   │   ├── rpc.ts              # JSON-RPC
│   │   └── discovery.ts        # Discovery module
│   ├── errors/                 # Error types
│   └── utils/                  # Utility functions
├── docs/
│   └── quickstart.md           # Quickstart guide
├── tests/                      # Unit tests
└── package.json

Environment Requirements

Related Links

• GitHub Repository
• x402 Protocol Website
• ZAN Website