# Introduction

Turn any API into a paid service — No registration, no API Key, AI Agents pay and consume autonomously.

## What is ZAN x402?

ZAN x402 is an AI Agent payment gateway platform launched by ZAN, built on the <a href="https://x402.org" target="_blank" style={{color: "#1196db", fontSize: "14px", textDecoration: "none"}}>x402 protocol</a> — 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

| Feature                         | Description                                                                                |
| ------------------------------- | ------------------------------------------------------------------------------------------ |
| 🎯 **No Registration Required** | Wallet as identity — start with just one signature                                         |
| 🔐 **On-Chain Settlement**      | Transparent, verifiable USDC settlement on Base and Solana                                 |
| 🤖 **Agent-Native**             | Designed for AI Agents with single-session primitives and machine-parseable 402 challenges |
| 💳 **Credit System**            | Purchase once, use anywhere — one balance across the entire platform                       |
| 🌐 **Multi-Chain RPC**          | Supports 30+ networks: ETH, Solana, Bitcoin, Base, Arbitrum, and more                      |

***

## Why Choose ZAN x402?

### 1. Traditional API Payments vs ZAN x402

| Comparison             | Traditional API Payments                    | ZAN x402                                        |
| ---------------------- | ------------------------------------------- | ----------------------------------------------- |
| Integration            | Register account, apply for API Key, top up | Connect wallet, purchase credits, call directly |
| Payment Method         | Prepaid/postpaid cycle settlement           | Real-time on-chain USDC settlement              |
| Agent Support          | Requires human intervention                 | Agent autonomous payment, no human needed       |
| Multi-provider Billing | Need separate integration                   | Unified balance, one top-up for entire platform |

### 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:

* <a href="https://x402.org" target="_blank" style={{color: "#1196db", fontSize: "14px", textDecoration: "none"}}>Coinbase x402 Protocol</a> — Open payment protocol enabling AI Agents to make autonomous stablecoin micropayments
* <a href="https://www.galaxy.com/insights/research/x402-ai-agents-crypto-payments" target="_blank" style={{color: "#1196db", fontSize: "14px", textDecoration: "none"}}>Galaxy Research</a> — x402 makes AI Agents economic actors
* <a href="https://zuplo.com/blog/mcp-api-payments-with-x402/" target="_blank" style={{color: "#1196db", fontSize: "14px", textDecoration: "none"}}>Zuplo MCP Payments</a> — 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

| Category | Supported Networks                                                          |
| -------- | --------------------------------------------------------------------------- |
| EVM      | Ethereum, Base, Arbitrum, Optimism, Polygon, Avalanche, BNB Chain, and more |
| SVM      | Solana                                                                      |
| Others   | Bitcoin and more                                                            |

### 📈 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

```bash
# Install
npm install @zan_team/x402 viem
```

```typescript
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 <a href="./quickstart-guide-x402.md" target="_blank" style={{color: "#1196db", fontSize: "14px", textDecoration: "none"}}>Quickstart Guide</a>

***

## 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

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

***

## Configuration Options

```typescript
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

| Error Type                 | HTTP Status | Scenario                            |
| -------------------------- | ----------- | ----------------------------------- |
| `AuthenticationError`      | 401         | SIWE/SIWS signature rejected        |
| `SessionExpiredError`      | 401         | JWT session expired                 |
| `InsufficientCreditsError` | 402         | Insufficient credits                |
| `InsufficientFundsError`   | 402         | On-chain USDC balance insufficient  |
| `PaymentRejectedError`     | 402         | Payment rejected                    |
| `MethodNotAllowedError`    | 403         | Method not allowed for current tier |
| `ProviderNotFoundError`    | 404         | No matching provider found          |
| `UpstreamError`            | 504         | Provider failed                     |
| `NetworkError`             | —           | Network/timeout error               |

***

## 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

| Item            | Requirement       |
| --------------- | ----------------- |
| Node.js         | >= 18             |
| Package Manager | npm / pnpm / yarn |

***

## Related Links

* <a href="https://github.com/ZanTeam/zanx402-sdk" target="_blank" style={{color: "#1196db", fontSize: "14px", textDecoration: "none"}}>GitHub Repository</a>
* <a href="https://x402.org" target="_blank" style={{color: "#1196db", fontSize: "14px", textDecoration: "none"}}>x402 Protocol Website</a>
* <a href="https://zan.top" target="_blank" style={{color: "#1196db", fontSize: "14px", textDecoration: "none"}}>ZAN Website</a>

***