@ziongateway/sdk 0.1.2 → 0.1.4

package/README.md

@@ -70,16 +70,56 @@ export async function GET(req: Request) {
 
 ---
 
+
 ## Usage (Client-Side / AI Agent)
 
-When a client receives a `402 Payment Required` response, they must:
-1. Create an **atomic split transaction** (99% to developer, 1% to treasury)
-2. Sign and send the transaction
-3. Build the payment header with the signature
-4. Retry the request with the `Authorization` header
+The SDK provides a `ZionAgent` class that makes integrating paid APIs as simple as a standard `fetch` call. It automatically handles the entire **402 Payment Required** flow, including:
+1. Detecting 402 responses
+2. Creating and signing the transaction
+3. Submitting to the Solana blockchain
+4. Retrying the request with payment proof
+
+### 1. Initialize the Agent
+Initialize the agent with your Solana private key.
+
+```typescript
+import { ZionAgent } from "@ziongateway/sdk";
+
+const agent = new ZionAgent({
+    privateKey: process.env.SOLANA_PRIVATE_KEY!, // Base58 encoded
+    rpcUrl: "https://api.mainnet-beta.solana.com" // Optional
+});
+```
+
+### 2. Make Requests
+Use `agent.fetch()` exactly like the standard `fetch` API. If payment is required, it happens automatically in the background.
+
+```typescript
+// 1. Just call fetch
+const response = await agent.fetch("https://api.merchant.com/premium-data");
+
+// 2. Handle the response
+if (response.ok) {
+    const data = await response.json();
+    console.log("Received paid content:", data);
+}
+
+// Optional: Check if a payment was responsible for this success
+if (response.paymentMade) {
+    console.log(`Paid via tx: ${response.txSignature}`);
+}
+```
+
+That's it! No transaction building, no buffer decoding, no manual retries.
+
+---
+
+## Manual Integration (Advanced)
+
+If you prefer to build the transaction manually (or are using a different language), follow these steps when you receive a `402 Payment Required` response:
 
 ### 1. Handling the 402 Response
-The server returns all payment requirements (including the correct USDC mint for the network):
+The server returns all payment requirements:
 
 ```json
 {
@@ -91,101 +131,50 @@ The server returns all payment requirements (including the correct USDC mint for
 }
 ```
 
-> **Note:** You don't need to know the USDC mint address - it's provided in the response automatically based on the network (mainnet or devnet).
-
 ### 2. Creating the Atomic Split Transaction
 
 The payment **must be split atomically** in a single transaction:
 - **99%** goes to the `recipient` (developer)
 - **1%** goes to the `treasury` (Zion fee)
 
-Use `PaymentBuilder.createAtomicSplitInstructions()` to generate the transfer instructions:
+You can use `PaymentBuilder` to generate the instructions:
 
 ```typescript
 import { PaymentBuilder } from "@ziongateway/sdk";
-import { Connection, Transaction, PublicKey } from "@solana/web3.js";
-import { getAssociatedTokenAddress, createAssociatedTokenAccountInstruction } from "@solana/spl-token";
-
-// 1. Receive 402 response with payment requirements
-const res = await fetch("/api/protected");
-if (res.status !== 402) return;
-const requirements = await res.json();
 
-// 2. Create atomic split transfer instructions
-const connection = new Connection("https://api.devnet.solana.com");
 const instructions = await PaymentBuilder.createAtomicSplitInstructions({
     sender: wallet.publicKey.toBase58(),
-    recipient: requirements.recipient,    // Developer wallet
-    treasury: requirements.treasury,      // Zion treasury
-    amount: requirements.amount,          // Total amount (fee split handled automatically)
-    asset: requirements.asset,            // USDC mint
+    recipient: requirements.recipient,
+    treasury: requirements.treasury,
+    amount: requirements.amount,
+    asset: requirements.asset,
     connection
 });
 
-// 3. Build transaction (create ATAs if needed)
-const tx = new Transaction();
-const assetMint = new PublicKey(requirements.asset);
-
-// Check if recipient/treasury ATAs exist, create if not
-const recipientAta = await getAssociatedTokenAddress(assetMint, new PublicKey(requirements.recipient));
-const treasuryAta = await getAssociatedTokenAddress(assetMint, new PublicKey(requirements.treasury));
-
-const recipientInfo = await connection.getAccountInfo(recipientAta);
-if (!recipientInfo) {
-    tx.add(createAssociatedTokenAccountInstruction(
-        wallet.publicKey, recipientAta, new PublicKey(requirements.recipient), assetMint
-    ));
-}
-
-const treasuryInfo = await connection.getAccountInfo(treasuryAta);
-if (!treasuryInfo) {
-    tx.add(createAssociatedTokenAccountInstruction(
-        wallet.publicKey, treasuryAta, new PublicKey(requirements.treasury), assetMint
-    ));
-}
-
-// Add the split transfer instructions
-tx.add(...instructions);
-
-// 4. Sign and send
-const { blockhash } = await connection.getLatestBlockhash();
-tx.recentBlockhash = blockhash;
-tx.feePayer = wallet.publicKey;
-
+const tx = new Transaction().add(...instructions);
 const signature = await wallet.sendTransaction(tx, connection);
 await connection.confirmTransaction(signature, "confirmed");
 ```
 
 ### 3. Creating the Payment Header
 
-After the transaction is confirmed, create the payment header:
+After confirmation, create the payment header and retry the request:
 
 ```typescript
 const paymentHeader = PaymentBuilder.createHeader({
-    signature,                              // Transaction signature
+    signature,
     sender: wallet.publicKey.toBase58(),
     recipient: requirements.recipient,
     amount: requirements.amount,
     asset: requirements.asset,
     timestamp: Math.floor(Date.now() / 1000),
-    nonce: crypto.randomUUID(),             // Unique per request
-    network: "solana-devnet"
+    nonce: crypto.randomUUID(),
+    network: requirements.network
 });
-```
-
-### 4. Retry with Authorization Header
 
-```typescript
 const response = await fetch("/api/protected", {
-    headers: {
-        "Authorization": `Bearer ${paymentHeader}`
-    }
+    headers: { "Authorization": `Bearer ${paymentHeader}` }
 });
-
-if (response.ok) {
-    const data = await response.json();
-    console.log("Success!", data);
-}
 ```
 
 ---

package/dist/Universal.d.ts

@@ -4,7 +4,11 @@
 export interface ZionConfig {
     /** Your API key from the Zion Dashboard */
     apiKey: string;
-    /** Price per request in USD (e.g., 0.01 for 1 cent) */
+    /**
+     * Price per request in USD (e.g., 0.01 for 1 cent).
+     * ⚠️ MAX 6 DECIMAL PLACES - USDC has 6 decimal precision.
+     * Invalid: 0.0000001 (7 decimals) | Valid: 0.000001 (6 decimals)
+     */
     price: number;
     /** Solana network to use */
     network?: "solana-mainnet" | "solana-devnet";

package/dist/ZionAgent.d.ts

@@ -0,0 +1,185 @@
+import { PublicKey } from "@solana/web3.js";
+import { NetworkName } from "./Universal";
+/**
+ * Configuration options for ZionAgent.
+ *
+ * @example
+ * ```typescript
+ * const agent = new ZionAgent({
+ *     privateKey: process.env.SOLANA_PRIVATE_KEY!,
+ *     rpcUrl: "https://mainnet.helius-rpc.com/...",
+ *     network: "solana-mainnet"
+ * });
+ * ```
+ */
+export interface ZionAgentConfig {
+    /**
+     * Base58-encoded Solana private key.
+     * Get this from your wallet (e.g., Phantom: Settings -> Security -> Export Private Key)
+     */
+    privateKey: string;
+    /**
+     * Optional Solana RPC URL.
+     * Defaults to public mainnet RPC if not provided.
+     * For production, use a dedicated RPC like Helius or QuickNode.
+     */
+    rpcUrl?: string;
+    /**
+     * Network to use for payments.
+     * @default "solana-mainnet"
+     */
+    network?: NetworkName;
+    /**
+     * Whether to log debug information.
+     * @default false
+     */
+    debug?: boolean;
+}
+/**
+ * Options for the fetch request (similar to standard fetch options).
+ */
+export interface ZionFetchOptions {
+    /** HTTP method (GET, POST, etc.) */
+    method?: string;
+    /** Request headers */
+    headers?: Record<string, string>;
+    /** Request body (will be JSON.stringify'd if object) */
+    body?: string | object;
+    /** Optional signal for request abortion */
+    signal?: AbortSignal;
+}
+/**
+ * Extended Response with additional payment metadata.
+ */
+export interface ZionResponse {
+    /** Whether the request was successful (status 200-299) */
+    ok: boolean;
+    /** HTTP status code */
+    status: number;
+    /** Status text */
+    statusText: string;
+    /** Response headers */
+    headers: Headers;
+    /** Whether a payment was made for this request */
+    paymentMade: boolean;
+    /** Transaction signature if payment was made */
+    txSignature?: string;
+    /** Parse response as JSON */
+    json(): Promise<any>;
+    /** Parse response as text */
+    text(): Promise<string>;
+    /** Raw response object */
+    raw: Response;
+}
+/**
+ * Error codes for ZionAgent errors.
+ */
+export type ZionErrorCode = 'INSUFFICIENT_FUNDS' | 'TX_FAILED' | 'TX_TIMEOUT' | 'NETWORK_ERROR' | 'INVALID_REQUIREMENTS' | 'INVALID_PRIVATE_KEY' | 'PAYMENT_REJECTED';
+/**
+ * Custom error class for ZionAgent payment errors.
+ */
+export declare class ZionPaymentError extends Error {
+    /** Error code for programmatic handling */
+    code: ZionErrorCode;
+    /** Additional error details */
+    details?: any;
+    constructor(message: string, code: ZionErrorCode, details?: any);
+}
+/**
+ * ZionAgent - Client-side SDK for AI Agents to make paid API requests.
+ *
+ * Provides a drop-in replacement for `fetch()` that automatically handles
+ * x402 payment flows. When a server responds with 402 Payment Required,
+ * ZionAgent will:
+ * 1. Parse the payment requirements
+ * 2. Create and sign a Solana transaction
+ * 3. Submit the transaction and wait for confirmation
+ * 4. Retry the request with the payment proof
+ *
+ * @example
+ * ```typescript
+ * import { ZionAgent } from "@ziongateway/sdk";
+ *
+ * const agent = new ZionAgent({
+ *     privateKey: process.env.SOLANA_PRIVATE_KEY!,
+ *     rpcUrl: "https://mainnet.helius-rpc.com/..."
+ * });
+ *
+ * // Just like fetch - payment happens automatically!
+ * const response = await agent.fetch("https://api.merchant.com/premium-data");
+ * const data = await response.json();
+ * ```
+ */
+export declare class ZionAgent {
+    private wallet;
+    private connection;
+    private network;
+    private debug;
+    /**
+     * Create a new ZionAgent instance.
+     *
+     * @param config - Configuration options
+     * @throws {ZionPaymentError} If private key is invalid
+     */
+    constructor(config: ZionAgentConfig);
+    /**
+     * Get the agent's wallet public key.
+     */
+    get publicKey(): PublicKey;
+    /**
+     * Get the agent's wallet address as a string.
+     */
+    get address(): string;
+    /**
+     * Make a fetch request with automatic x402 payment handling.
+     *
+     * This method works just like the standard `fetch()` API, but automatically
+     * handles 402 Payment Required responses by:
+     * 1. Parsing payment requirements from the response
+     * 2. Creating and signing a Solana transaction
+     * 3. Submitting the payment to the blockchain
+     * 4. Retrying the request with payment proof
+     *
+     * @param url - The URL to fetch
+     * @param options - Optional fetch options (method, headers, body)
+     * @returns A ZionResponse with the result
+     *
+     * @throws {ZionPaymentError} If payment fails (insufficient funds, tx error, etc.)
+     *
+     * @example
+     * ```typescript
+     * // Simple GET request
+     * const response = await agent.fetch("https://api.merchant.com/data");
+     *
+     * // POST request with body
+     * const response = await agent.fetch("https://api.merchant.com/action", {
+     *     method: "POST",
+     *     headers: { "Content-Type": "application/json" },
+     *     body: { query: "What is the weather?" }
+     * });
+     * ```
+     */
+    fetch(url: string, options?: ZionFetchOptions): Promise<ZionResponse>;
+    /**
+     * Parse payment requirements from a 402 response.
+     */
+    private parsePaymentRequirements;
+    /**
+     * Execute the payment transaction.
+     */
+    private executePayment;
+    /**
+     * Generate a random nonce for the payment header.
+     */
+    private generateNonce;
+    /**
+     * Wrap a Response object into a ZionResponse.
+     */
+    private wrapResponse;
+    /**
+     * Get the USDC balance for this agent's wallet.
+     *
+     * @returns The USDC balance in human-readable format (e.g., "10.50")
+     */
+    getBalance(): Promise<string>;
+}

package/dist/ZionAgent.js

@@ -0,0 +1,340 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ZionAgent = exports.ZionPaymentError = void 0;
+const web3_js_1 = require("@solana/web3.js");
+const spl_token_1 = require("@solana/spl-token");
+const bs58_1 = __importDefault(require("bs58"));
+const index_1 = require("./index");
+const Universal_1 = require("./Universal");
+/**
+ * Custom error class for ZionAgent payment errors.
+ */
+class ZionPaymentError extends Error {
+    constructor(message, code, details) {
+        super(message);
+        this.name = 'ZionPaymentError';
+        this.code = code;
+        this.details = details;
+    }
+}
+exports.ZionPaymentError = ZionPaymentError;
+// ==================== ZionAgent Class ====================
+/**
+ * ZionAgent - Client-side SDK for AI Agents to make paid API requests.
+ *
+ * Provides a drop-in replacement for `fetch()` that automatically handles
+ * x402 payment flows. When a server responds with 402 Payment Required,
+ * ZionAgent will:
+ * 1. Parse the payment requirements
+ * 2. Create and sign a Solana transaction
+ * 3. Submit the transaction and wait for confirmation
+ * 4. Retry the request with the payment proof
+ *
+ * @example
+ * ```typescript
+ * import { ZionAgent } from "@ziongateway/sdk";
+ *
+ * const agent = new ZionAgent({
+ *     privateKey: process.env.SOLANA_PRIVATE_KEY!,
+ *     rpcUrl: "https://mainnet.helius-rpc.com/..."
+ * });
+ *
+ * // Just like fetch - payment happens automatically!
+ * const response = await agent.fetch("https://api.merchant.com/premium-data");
+ * const data = await response.json();
+ * ```
+ */
+class ZionAgent {
+    /**
+     * Create a new ZionAgent instance.
+     *
+     * @param config - Configuration options
+     * @throws {ZionPaymentError} If private key is invalid
+     */
+    constructor(config) {
+        // Validate and decode private key
+        try {
+            this.wallet = web3_js_1.Keypair.fromSecretKey(bs58_1.default.decode(config.privateKey));
+        }
+        catch (error) {
+            throw new ZionPaymentError("Invalid private key. Ensure it's a valid base58-encoded Solana private key.", 'INVALID_PRIVATE_KEY');
+        }
+        // Set up connection
+        this.network = config.network || "solana-mainnet";
+        const defaultRpc = this.network === "solana-devnet"
+            ? "https://api.devnet.solana.com"
+            : "https://api.mainnet-beta.solana.com";
+        this.connection = new web3_js_1.Connection(config.rpcUrl || defaultRpc, "confirmed");
+        this.debug = config.debug || false;
+        if (this.debug) {
+            console.log(`[ZionAgent] Initialized with wallet: ${this.wallet.publicKey.toBase58()}`);
+            console.log(`[ZionAgent] Network: ${this.network}`);
+        }
+    }
+    /**
+     * Get the agent's wallet public key.
+     */
+    get publicKey() {
+        return this.wallet.publicKey;
+    }
+    /**
+     * Get the agent's wallet address as a string.
+     */
+    get address() {
+        return this.wallet.publicKey.toBase58();
+    }
+    /**
+     * Make a fetch request with automatic x402 payment handling.
+     *
+     * This method works just like the standard `fetch()` API, but automatically
+     * handles 402 Payment Required responses by:
+     * 1. Parsing payment requirements from the response
+     * 2. Creating and signing a Solana transaction
+     * 3. Submitting the payment to the blockchain
+     * 4. Retrying the request with payment proof
+     *
+     * @param url - The URL to fetch
+     * @param options - Optional fetch options (method, headers, body)
+     * @returns A ZionResponse with the result
+     *
+     * @throws {ZionPaymentError} If payment fails (insufficient funds, tx error, etc.)
+     *
+     * @example
+     * ```typescript
+     * // Simple GET request
+     * const response = await agent.fetch("https://api.merchant.com/data");
+     *
+     * // POST request with body
+     * const response = await agent.fetch("https://api.merchant.com/action", {
+     *     method: "POST",
+     *     headers: { "Content-Type": "application/json" },
+     *     body: { query: "What is the weather?" }
+     * });
+     * ```
+     */
+    async fetch(url, options = {}) {
+        // Prepare request options
+        const fetchOptions = {
+            method: options.method || "GET",
+            headers: { ...options.headers },
+            signal: options.signal
+        };
+        // Handle body
+        if (options.body) {
+            if (typeof options.body === "object") {
+                fetchOptions.body = JSON.stringify(options.body);
+                fetchOptions.headers["Content-Type"] = "application/json";
+            }
+            else {
+                fetchOptions.body = options.body;
+            }
+        }
+        if (this.debug) {
+            console.log(`[ZionAgent] Fetching: ${url}`);
+        }
+        // Make initial request
+        const initialResponse = await fetch(url, fetchOptions);
+        // If not 402, return the response as-is
+        if (initialResponse.status !== 402) {
+            return this.wrapResponse(initialResponse, false);
+        }
+        if (this.debug) {
+            console.log(`[ZionAgent] Received 402 Payment Required`);
+        }
+        // Parse payment requirements
+        const requirements = await this.parsePaymentRequirements(initialResponse);
+        if (this.debug) {
+            console.log(`[ZionAgent] Payment requirements:`, requirements);
+        }
+        // Execute payment
+        const { signature, paymentHeader } = await this.executePayment(requirements);
+        if (this.debug) {
+            console.log(`[ZionAgent] Payment successful! Signature: ${signature}`);
+        }
+        // Retry with payment proof
+        const retryOptions = {
+            ...fetchOptions,
+            headers: {
+                ...fetchOptions.headers,
+                "Authorization": `Bearer ${paymentHeader}`
+            }
+        };
+        const finalResponse = await fetch(url, retryOptions);
+        // Check if payment was rejected
+        if (finalResponse.status === 402 || finalResponse.status === 403) {
+            const errorBody = await finalResponse.text();
+            throw new ZionPaymentError(`Payment was rejected by the server: ${errorBody}`, 'PAYMENT_REJECTED', { status: finalResponse.status, body: errorBody });
+        }
+        return this.wrapResponse(finalResponse, true, signature);
+    }
+    /**
+     * Parse payment requirements from a 402 response.
+     */
+    async parsePaymentRequirements(response) {
+        let body;
+        try {
+            body = await response.json();
+        }
+        catch (error) {
+            throw new ZionPaymentError("Failed to parse payment requirements from 402 response", 'INVALID_REQUIREMENTS', { error });
+        }
+        // Validate required fields
+        const required = ['recipient', 'amount', 'asset', 'treasury'];
+        for (const field of required) {
+            if (!body[field]) {
+                throw new ZionPaymentError(`Missing required field in payment requirements: ${field}`, 'INVALID_REQUIREMENTS', { body });
+            }
+        }
+        return {
+            recipient: body.recipient,
+            amount: body.amount,
+            asset: body.asset,
+            treasury: body.treasury,
+            network: body.network || this.network,
+            feeBps: body.feeBps || 100
+        };
+    }
+    /**
+     * Execute the payment transaction.
+     */
+    async executePayment(requirements) {
+        const assetMint = new web3_js_1.PublicKey(requirements.asset);
+        const recipient = new web3_js_1.PublicKey(requirements.recipient);
+        const treasury = new web3_js_1.PublicKey(requirements.treasury);
+        // Get Associated Token Addresses
+        const senderAta = await (0, spl_token_1.getAssociatedTokenAddress)(assetMint, this.wallet.publicKey);
+        const recipientAta = await (0, spl_token_1.getAssociatedTokenAddress)(assetMint, recipient);
+        const treasuryAta = await (0, spl_token_1.getAssociatedTokenAddress)(assetMint, treasury);
+        // Check sender balance
+        try {
+            const balance = await this.connection.getTokenAccountBalance(senderAta);
+            const requiredAmount = BigInt(requirements.amount);
+            const availableAmount = BigInt(balance.value.amount);
+            if (availableAmount < requiredAmount) {
+                const requiredUsd = Number(requiredAmount) / 1000000;
+                const availableUsd = Number(availableAmount) / 1000000;
+                throw new ZionPaymentError(`Insufficient USDC balance. Required: $${requiredUsd.toFixed(6)}, Available: $${availableUsd.toFixed(6)}`, 'INSUFFICIENT_FUNDS', { required: requiredAmount.toString(), available: availableAmount.toString() });
+            }
+            if (this.debug) {
+                console.log(`[ZionAgent] Balance check passed. Available: ${balance.value.uiAmountString} USDC`);
+            }
+        }
+        catch (error) {
+            if (error instanceof ZionPaymentError)
+                throw error;
+            throw new ZionPaymentError("No USDC token account found. Fund your wallet with USDC first.", 'INSUFFICIENT_FUNDS', { wallet: this.wallet.publicKey.toBase58() });
+        }
+        // Build transaction
+        const tx = new web3_js_1.Transaction();
+        // Create recipient ATA if needed
+        const recipientInfo = await this.connection.getAccountInfo(recipientAta);
+        if (!recipientInfo) {
+            if (this.debug)
+                console.log(`[ZionAgent] Creating recipient ATA...`);
+            tx.add((0, spl_token_1.createAssociatedTokenAccountInstruction)(this.wallet.publicKey, recipientAta, recipient, assetMint));
+        }
+        // Create treasury ATA if needed
+        const treasuryInfo = await this.connection.getAccountInfo(treasuryAta);
+        if (!treasuryInfo) {
+            if (this.debug)
+                console.log(`[ZionAgent] Creating treasury ATA...`);
+            tx.add((0, spl_token_1.createAssociatedTokenAccountInstruction)(this.wallet.publicKey, treasuryAta, treasury, assetMint));
+        }
+        // Add transfer instructions (atomic split)
+        const instructions = await index_1.PaymentBuilder.createAtomicSplitInstructions({
+            sender: this.wallet.publicKey.toBase58(),
+            recipient: requirements.recipient,
+            treasury: requirements.treasury,
+            amount: requirements.amount,
+            asset: requirements.asset,
+            connection: this.connection
+        });
+        tx.add(...instructions);
+        // Sign and send
+        try {
+            const { blockhash, lastValidBlockHeight } = await this.connection.getLatestBlockhash();
+            tx.recentBlockhash = blockhash;
+            tx.feePayer = this.wallet.publicKey;
+            tx.sign(this.wallet);
+            if (this.debug)
+                console.log(`[ZionAgent] Sending transaction...`);
+            const signature = await this.connection.sendRawTransaction(tx.serialize());
+            if (this.debug)
+                console.log(`[ZionAgent] Confirming transaction: ${signature}`);
+            // Wait for confirmation with timeout
+            const confirmation = await this.connection.confirmTransaction({
+                signature,
+                blockhash,
+                lastValidBlockHeight
+            }, "confirmed");
+            if (confirmation.value.err) {
+                throw new ZionPaymentError(`Transaction failed: ${JSON.stringify(confirmation.value.err)}`, 'TX_FAILED', { signature, error: confirmation.value.err });
+            }
+            // Create payment header
+            const paymentHeader = index_1.PaymentBuilder.createHeader({
+                signature,
+                sender: this.wallet.publicKey.toBase58(),
+                recipient: requirements.recipient,
+                amount: requirements.amount,
+                asset: requirements.asset,
+                timestamp: Math.floor(Date.now() / 1000),
+                nonce: this.generateNonce(),
+                network: requirements.network || this.network
+            });
+            return { signature, paymentHeader };
+        }
+        catch (error) {
+            if (error instanceof ZionPaymentError)
+                throw error;
+            const message = error instanceof Error ? error.message : String(error);
+            if (message.includes('timeout') || message.includes('expired')) {
+                throw new ZionPaymentError(`Transaction timed out. It may still succeed - check: ${message}`, 'TX_TIMEOUT', { error: message });
+            }
+            throw new ZionPaymentError(`Transaction failed: ${message}`, 'TX_FAILED', { error: message });
+        }
+    }
+    /**
+     * Generate a random nonce for the payment header.
+     */
+    generateNonce() {
+        return Math.random().toString(36).substring(2, 15) +
+            Math.random().toString(36).substring(2, 15);
+    }
+    /**
+     * Wrap a Response object into a ZionResponse.
+     */
+    wrapResponse(response, paymentMade, txSignature) {
+        return {
+            ok: response.ok,
+            status: response.status,
+            statusText: response.statusText,
+            headers: response.headers,
+            paymentMade,
+            txSignature,
+            json: () => response.json(),
+            text: () => response.text(),
+            raw: response
+        };
+    }
+    /**
+     * Get the USDC balance for this agent's wallet.
+     *
+     * @returns The USDC balance in human-readable format (e.g., "10.50")
+     */
+    async getBalance() {
+        const networkConfig = Universal_1.NETWORKS[this.network];
+        const mintPubkey = new web3_js_1.PublicKey(networkConfig.usdcMint);
+        const ata = await (0, spl_token_1.getAssociatedTokenAddress)(mintPubkey, this.wallet.publicKey);
+        try {
+            const balance = await this.connection.getTokenAccountBalance(ata);
+            return balance.value.uiAmountString || "0";
+        }
+        catch {
+            return "0";
+        }
+    }
+}
+exports.ZionAgent = ZionAgent;

package/dist/ZionGate.d.ts

@@ -26,7 +26,7 @@ export declare class ZionGate {
     /**
      * Create a new ZionGate instance.
      * @param config - Configuration options
-     * @throws Error if price is not positive
+     * @throws Error if price is not positive or has more than 6 decimal places
      */
     constructor(config: ZionConfig);
     /**

package/dist/ZionGate.js

@@ -29,15 +29,24 @@ class ZionGate {
     /**
      * Create a new ZionGate instance.
      * @param config - Configuration options
-     * @throws Error if price is not positive
+     * @throws Error if price is not positive or has more than 6 decimal places
      */
     constructor(config) {
         this.developerWallet = null;
         this.isInitialized = false;
-        // Validate price
+        // Validate price is positive
         if (!config.price || config.price <= 0) {
             throw new Error("ZionGate: Price must be a positive number");
         }
+        // Validate price has max 6 decimal places (USDC precision)
+        const priceStr = config.price.toString();
+        const decimalIndex = priceStr.indexOf('.');
+        if (decimalIndex !== -1) {
+            const decimals = priceStr.length - decimalIndex - 1;
+            if (decimals > 6) {
+                throw new Error("ZionGate: Price cannot have more than 6 decimal places (USDC precision)");
+            }
+        }
         this.config = config;
         const defaults = Universal_1.NETWORKS[config.network || "solana-mainnet"];
         this.api = axios_1.default.create({

package/dist/index.d.ts

@@ -1,5 +1,6 @@
 export * from "./Universal";
 export * from "./ZionGate";
+export * from "./ZionAgent";
 import { Connection } from "@solana/web3.js";
 /**
  * Payment requirements returned in a 402 response.

package/dist/index.js

@@ -39,6 +39,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.PaymentBuilder = void 0;
 __exportStar(require("./Universal"), exports);
 __exportStar(require("./ZionGate"), exports);
+__exportStar(require("./ZionAgent"), exports);
 const web3_js_1 = require("@solana/web3.js");
 /**
  * PaymentBuilder - Client-side utilities for AI Agents and wallets.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ziongateway/sdk",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "description": "TypeScript SDK for Zion x402 Facilitator",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -23,7 +23,8 @@
   "dependencies": {
     "@solana/spl-token": "^0.4.14",
     "@solana/web3.js": "^1.98.4",
-    "axios": "^1.6.0"
+    "axios": "^1.6.0",
+    "bs58": "^6.0.0"
   },
   "devDependencies": {
     "@types/bs58": "^4.0.4",
@@ -38,4 +39,4 @@
     "README.md"
   ],
   "homepage": "https://docs.ziongateway.xyz"
-}
+}