@ziongateway/sdk 0.1.0 → 0.1.1

package/README.md

@@ -3,17 +3,17 @@
 The **Zion SDK** allows AI Agents and developers to easily monetize their APIs using the **Zion X-402 Facilitator**. It handles the **HTTP 402 Payment Required** protocol, standardizing payment requests, verification, and settlement on the Solana blockchain.
 
 ## Features
-- 🛡️ **Middleware Protection**: Automatically blocks unpaid requests with a `402` status.
-- 💰 **Flexible Pricing**: Set prices in USDC (or other assets).
-- ⚡ **Instant Settlement**: Verifies and settles payments via the Facilitator.
-- 🔗 **Framework Agnostic**: Works with Express, Next.js, NestJS, etc.
+- **Middleware Protection**: Automatically blocks unpaid requests with a `402` status.
+- **Flexible Pricing**: Set prices in USDC (or other assets).
+- **Instant Settlement**: Verifies and settles payments via the Facilitator.
+- **Framework Agnostic**: Works with Express, Next.js, NestJS, etc.
 
 ---
 
 ## Installation
 
 ```bash
-npm install @zion/sdk
+npm install @ziongateway/sdk
 ```
 
 ---
@@ -25,7 +25,7 @@ Protect your API routes by adding `ZionGate` middleware.
 
 ```typescript
 import express from "express";
-import { ZionGate } from "@zion/sdk";
+import { ZionGate } from "@ziongateway/sdk";
 
 const app = express();
 
@@ -54,7 +54,7 @@ app.listen(3000, () => console.log("Server running on port 3000"));
 Use the `nextServer` helper in your route handlers.
 
 ```typescript
-import { ZionGate } from "@zion/sdk";
+import { ZionGate } from "@ziongateway/sdk";
 
 const zion = new ZionGate({ /* config */ });
 
@@ -70,49 +70,122 @@ export async function GET(req: Request) {
 
 ---
 
-## Usage (Client-Side)
+## Usage (Client-Side / AI Agent)
 
-When a client receives a `402 Payment Required` response, they must perform the payment on-chain and send the proof back in the `Authorization` header.
+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
 
 ### 1. Handling the 402 Response
-The server returns payment requirements:
+The server returns all payment requirements (including the correct USDC mint for the network):
 
 ```json
 {
-  "recipient": "FjK...",   // Developer's Wallet
+  "recipient": "FjK...",   // Developer's Wallet (auto-fetched)
   "amount": "100000",      // Atomic units (0.1 USDC)
-  "asset": "EPj...",       // USDC Mint Address
-  "treasury": "AgH...",    // Zion Treasury (for 1% fee)
-  "message": "Payment Required"
+  "asset": "EPj...",       // USDC Mint (automatic based on network)
+  "treasury": "AgH...",    // Zion Treasury
+  "network": "solana-devnet"
 }
 ```
 
-### 2. Creating the Payment Header
-Use `PaymentBuilder` to generate the correct header after signing the transaction.
+> **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:
 
 ```typescript
-import { PaymentBuilder } from "@zion/sdk";
+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
+    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);
 
-// ... Perform Solana Transaction (Split: 99% to recipient, 1% to treasury) ...
+// 4. Sign and send
+const { blockhash } = await connection.getLatestBlockhash();
+tx.recentBlockhash = blockhash;
+tx.feePayer = wallet.publicKey;
 
-// Create the Zion Payment Header
-const header = PaymentBuilder.createHeader({
-    sender: "USER_WALLET_ADDRESS",
-    recipient: "DEVELOPER_WALLET_ADDRESS",
-    amount: "100000",
-    asset: "USDC_MINT_ADDRESS",
+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:
+
+```typescript
+const paymentHeader = PaymentBuilder.createHeader({
+    signature,                              // Transaction signature
+    sender: wallet.publicKey.toBase58(),
+    recipient: requirements.recipient,
+    amount: requirements.amount,
+    asset: requirements.asset,
     timestamp: Math.floor(Date.now() / 1000),
-    nonce: "RANDOM_STRING_GT_8_CHARS",
-    signature: "TRANSACTION_SIGNATURE", // From Solana Web3.js
+    nonce: crypto.randomUUID(),             // Unique per request
     network: "solana-devnet"
 });
+```
+
+### 4. Retry with Authorization Header
 
-// Retry the request with the header
-const response = await fetch("http://api.example.com/protected", {
+```typescript
+const response = await fetch("/api/protected", {
     headers: {
-        "Authorization": `Bearer ${header}`
+        "Authorization": `Bearer ${paymentHeader}`
     }
 });
+
+if (response.ok) {
+    const data = await response.json();
+    console.log("Success!", data);
+}
 ```
 
 ---

package/dist/Universal.d.ts

@@ -1,10 +1,19 @@
+/**
+ * Configuration options for ZionGate.
+ */
 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: number;
+    /** Solana network to use */
     network?: "solana-mainnet" | "solana-devnet";
-    facilitatorUrl?: string;
+    /** Resource identifier for analytics (default: "api-access") */
     resource?: string;
 }
+/**
+ * Result from the payment check.
+ */
 export interface CheckResult {
     authorized: boolean;
     error?: {
@@ -14,6 +23,9 @@ export interface CheckResult {
     success?: boolean;
     verification?: VerifyResponse;
 }
+/**
+ * Response from the Facilitator's verify endpoint.
+ */
 export interface VerifyResponse {
     valid: boolean;
     invalidReason?: {
@@ -26,6 +38,9 @@ export interface VerifyResponse {
         confirmedAt: string;
     };
 }
+/**
+ * Response from the Facilitator's settle endpoint.
+ */
 export interface SettleResponse {
     success: boolean;
     error?: {
@@ -45,15 +60,27 @@ export interface SettleResponse {
         settledAt: string;
     };
 }
+/**
+ * Network configuration for Solana mainnet and devnet.
+ * Contains treasury addresses, USDC mint addresses, and facilitator URLs.
+ */
 export declare const NETWORKS: {
-    "solana-mainnet": {
-        treasury: string;
-        usdcMint: string;
-        facilitator: string;
+    readonly "solana-mainnet": {
+        /** Zion treasury wallet for fee collection */
+        readonly treasury: "AgH4Eq3JYBpEt5aPgCnZsygf9tnQ5D2qMKH3eJxB5rm8";
+        /** USDC SPL Token mint on mainnet */
+        readonly usdcMint: "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v";
+        /** Zion Facilitator API URL */
+        readonly facilitator: "https://zion-x402-facilitator-production.up.railway.app/v1";
     };
-    "solana-devnet": {
-        treasury: string;
-        usdcMint: string;
-        facilitator: string;
+    readonly "solana-devnet": {
+        /** Zion treasury wallet for fee collection */
+        readonly treasury: "AgH4Eq3JYBpEt5aPgCnZsygf9tnQ5D2qMKH3eJxB5rm8";
+        /** USDC SPL Token mint on devnet */
+        readonly usdcMint: "4zMMC9srt5Ri5X14GAgXhaHii3GnPAEERYPJgZJDncDU";
+        /** Zion Facilitator API URL */
+        readonly facilitator: "https://zion-x402-facilitator-production.up.railway.app/v1";
     };
 };
+/** Type for supported network names */
+export type NetworkName = keyof typeof NETWORKS;

package/dist/Universal.js

@@ -1,15 +1,25 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.NETWORKS = void 0;
+/**
+ * Network configuration for Solana mainnet and devnet.
+ * Contains treasury addresses, USDC mint addresses, and facilitator URLs.
+ */
 exports.NETWORKS = {
     "solana-mainnet": {
+        /** Zion treasury wallet for fee collection */
         treasury: "AgH4Eq3JYBpEt5aPgCnZsygf9tnQ5D2qMKH3eJxB5rm8",
+        /** USDC SPL Token mint on mainnet */
         usdcMint: "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
+        /** Zion Facilitator API URL */
         facilitator: "https://zion-x402-facilitator-production.up.railway.app/v1"
     },
     "solana-devnet": {
+        /** Zion treasury wallet for fee collection */
         treasury: "AgH4Eq3JYBpEt5aPgCnZsygf9tnQ5D2qMKH3eJxB5rm8",
+        /** USDC SPL Token mint on devnet */
         usdcMint: "4zMMC9srt5Ri5X14GAgXhaHii3GnPAEERYPJgZJDncDU",
+        /** Zion Facilitator API URL */
         facilitator: "https://zion-x402-facilitator-production.up.railway.app/v1"
     }
 };

package/dist/ZionGate.d.ts

@@ -1,35 +1,76 @@
 import { ZionConfig, CheckResult } from "./Universal";
+/**
+ * ZionGate - Server-side SDK for protecting API routes with x402 payments.
+ *
+ * @example
+ * ```typescript
+ * const zion = new ZionGate({
+ *     apiKey: "your_api_key",
+ *     price: 0.01,
+ *     network: "solana-devnet"
+ * });
+ *
+ * // Express
+ * app.get("/api", zion.express(), (req, res) => res.json({ data: "paid content" }));
+ *
+ * // Next.js
+ * const auth = await zion.nextServer(req);
+ * if (auth !== true) return auth;
+ * ```
+ */
 export declare class ZionGate {
-    private static instance;
     private config;
     private api;
     private developerWallet;
     private isInitialized;
+    /**
+     * Create a new ZionGate instance.
+     * @param config - Configuration options
+     * @throws Error if price is not positive
+     */
     constructor(config: ZionConfig);
     /**
      * Initialize the SDK by fetching the developer's wallet address from the Facilitator.
-     * This is required because we don't want the developer to hardcode their receiving address,
-     * to ensure funds go to their specific embedded wallet or chosen payout address.
+     * This is called automatically on first request, but can be called manually.
+     * Includes retry logic for transient failures.
+     *
+     * @param retries - Number of retry attempts (default: 3)
+     * @param delayMs - Delay between retries in ms (default: 1000)
      */
-    init(): Promise<void>;
+    init(retries?: number, delayMs?: number): Promise<void>;
     /**
-     * Core check logic generic for any framework.
+     * Core payment verification logic. Framework-agnostic.
+     * @param headers - Request headers object
+     * @returns CheckResult indicating if request is authorized
      */
     check(headers: Record<string, string | undefined>): Promise<CheckResult>;
+    /**
+     * Generate a 402 Payment Required response with all payment details.
+     */
     private create402Response;
     /**
-     * Express Middleware Adapter
+     * Express.js middleware adapter.
+     *
+     * @example
+     * ```typescript
+     * app.get("/api/premium", zion.express(), (req, res) => {
+     *     res.json({ data: "Premium content" });
+     * });
+     * ```
      */
     express(): (req: any, res: any, next: any) => Promise<any>;
     /**
-     * NextJS API Route / App Router Helper
-     * Usage:
-     *   const zion = new ZionGate(...);
-     *   export async function GET(req: Request) {
-     *      const authorized = await zion.nextServer(req);
-     *      if (authorized !== true) return authorized; // Returns Response object
-     *      // ... logic
-     *   }
+     * Next.js App Router helper.
+     * Returns `true` if authorized, or a Response object to return if not.
+     *
+     * @example
+     * ```typescript
+     * export async function GET(req: Request) {
+     *     const auth = await zion.nextServer(req);
+     *     if (auth !== true) return auth;
+     *     return Response.json({ data: "Premium content" });
+     * }
+     * ```
      */
     nextServer(req: Request): Promise<true | Response>;
 }

package/dist/ZionGate.js

@@ -6,45 +6,87 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.ZionGate = void 0;
 const axios_1 = __importDefault(require("axios"));
 const Universal_1 = require("./Universal");
+/**
+ * ZionGate - Server-side SDK for protecting API routes with x402 payments.
+ *
+ * @example
+ * ```typescript
+ * const zion = new ZionGate({
+ *     apiKey: "your_api_key",
+ *     price: 0.01,
+ *     network: "solana-devnet"
+ * });
+ *
+ * // Express
+ * app.get("/api", zion.express(), (req, res) => res.json({ data: "paid content" }));
+ *
+ * // Next.js
+ * const auth = await zion.nextServer(req);
+ * if (auth !== true) return auth;
+ * ```
+ */
 class ZionGate {
+    /**
+     * Create a new ZionGate instance.
+     * @param config - Configuration options
+     * @throws Error if price is not positive
+     */
     constructor(config) {
         this.developerWallet = null;
         this.isInitialized = false;
+        // Validate price
+        if (!config.price || config.price <= 0) {
+            throw new Error("ZionGate: Price must be a positive number");
+        }
         this.config = config;
         const defaults = Universal_1.NETWORKS[config.network || "solana-mainnet"];
         this.api = axios_1.default.create({
-            baseURL: config.facilitatorUrl || defaults.facilitator,
+            baseURL: defaults.facilitator,
             headers: {
                 "X-API-KEY": config.apiKey,
                 "Content-Type": "application/json"
-            }
+            },
+            timeout: 10000 // 10 second timeout
         });
     }
     /**
      * Initialize the SDK by fetching the developer's wallet address from the Facilitator.
-     * This is required because we don't want the developer to hardcode their receiving address,
-     * to ensure funds go to their specific embedded wallet or chosen payout address.
+     * This is called automatically on first request, but can be called manually.
+     * Includes retry logic for transient failures.
+     *
+     * @param retries - Number of retry attempts (default: 3)
+     * @param delayMs - Delay between retries in ms (default: 1000)
      */
-    async init() {
+    async init(retries = 3, delayMs = 1000) {
         if (this.isInitialized)
             return;
-        try {
-            const res = await this.api.get("/v1/wallet");
-            if (res.data && res.data.address) {
-                this.developerWallet = res.data.address;
-                this.isInitialized = true;
+        let lastError = null;
+        for (let attempt = 1; attempt <= retries; attempt++) {
+            try {
+                const res = await this.api.get("/wallet");
+                if (res.data && res.data.address) {
+                    this.developerWallet = res.data.address;
+                    this.isInitialized = true;
+                    return;
+                }
+                else {
+                    throw new Error("Invalid response from Facilitator wallet endpoint");
+                }
             }
-            else {
-                throw new Error("Invalid response from Facilitator wallet endpoint");
+            catch (error) {
+                lastError = error;
+                console.warn(`ZionGate init attempt ${attempt}/${retries} failed:`, error.message);
+                if (attempt < retries) {
+                    await new Promise(resolve => setTimeout(resolve, delayMs));
+                }
             }
         }
-        catch (error) {
-            console.error("ZionGate Init Failed:", error.message);
-            throw new Error("Failed to initialize ZionGate: Could not fetch developer wallet.");
-        }
+        throw new Error(`ZionGate: Failed to initialize after ${retries} attempts. ${lastError?.message}`);
     }
     /**
-     * Core check logic generic for any framework.
+     * Core payment verification logic. Framework-agnostic.
+     * @param headers - Request headers object
+     * @returns CheckResult indicating if request is authorized
      */
     async check(headers) {
         if (!this.isInitialized) {
@@ -60,7 +102,7 @@ class ZionGate {
         try {
             const atomicAmount = BigInt(Math.floor(this.config.price * 1000000)).toString();
             const defaults = Universal_1.NETWORKS[this.config.network || "solana-mainnet"];
-            const verification = await this.api.post("/v1/verify", {
+            const verification = await this.api.post("/verify", {
                 paymentHeader: token,
                 paymentRequirements: {
                     recipient: this.developerWallet,
@@ -83,14 +125,14 @@ class ZionGate {
                 };
             }
             // 3. Settle
-            const settlement = await this.api.post("/v1/settle", {
+            const settlement = await this.api.post("/settle", {
                 paymentHeader: token,
                 paymentRequirements: {
                     recipient: this.developerWallet,
                     amount: atomicAmount,
                     asset: defaults.usdcMint,
                     network: this.config.network || "solana-mainnet",
-                    resource: "api-access"
+                    resource: this.config.resource || "api-access"
                 }
             });
             if (!settlement.data || !settlement.data.success) {
@@ -109,7 +151,7 @@ class ZionGate {
                 return {
                     authorized: false,
                     error: {
-                        status: err.response.status === 400 ? 402 : err.response.status, // Map 400 Bad Request (Validation) to 402 if convenient, or keep 400
+                        status: err.response.status === 400 ? 402 : err.response.status,
                         body: err.response.data || { error: "Payment Validation Failed" }
                     }
                 };
@@ -123,6 +165,9 @@ class ZionGate {
             };
         }
     }
+    /**
+     * Generate a 402 Payment Required response with all payment details.
+     */
     create402Response() {
         const defaults = Universal_1.NETWORKS[this.config.network || "solana-mainnet"];
         const atomicAmount = BigInt(Math.floor(this.config.price * 1000000)).toString();
@@ -135,15 +180,23 @@ class ZionGate {
                     amount: atomicAmount,
                     asset: defaults.usdcMint,
                     treasury: defaults.treasury,
+                    network: this.config.network || "solana-mainnet",
                     feeBps: 100, // 1%
                     message: "Payment Required. Split transaction: 99% to recipient, 1% to treasury."
                 }
             }
         };
     }
-    // Adapters
+    // ==================== Framework Adapters ====================
     /**
-     * Express Middleware Adapter
+     * Express.js middleware adapter.
+     *
+     * @example
+     * ```typescript
+     * app.get("/api/premium", zion.express(), (req, res) => {
+     *     res.json({ data: "Premium content" });
+     * });
+     * ```
      */
     express() {
         return async (req, res, next) => {
@@ -155,17 +208,19 @@ class ZionGate {
         };
     }
     /**
-     * NextJS API Route / App Router Helper
-     * Usage:
-     *   const zion = new ZionGate(...);
-     *   export async function GET(req: Request) {
-     *      const authorized = await zion.nextServer(req);
-     *      if (authorized !== true) return authorized; // Returns Response object
-     *      // ... logic
-     *   }
+     * Next.js App Router helper.
+     * Returns `true` if authorized, or a Response object to return if not.
+     *
+     * @example
+     * ```typescript
+     * export async function GET(req: Request) {
+     *     const auth = await zion.nextServer(req);
+     *     if (auth !== true) return auth;
+     *     return Response.json({ data: "Premium content" });
+     * }
+     * ```
      */
     async nextServer(req) {
-        // Convert Request headers to Record<string, string>
         const headers = {};
         req.headers.forEach((v, k) => (headers[k] = v));
         const result = await this.check(headers);

package/dist/index.d.ts

@@ -1,17 +1,48 @@
 export * from "./Universal";
 export * from "./ZionGate";
 import { Connection } from "@solana/web3.js";
+/**
+ * Payment requirements returned in a 402 response.
+ */
 export interface PaymentRequirements {
     recipient: string;
     amount: string;
     asset: string;
-    resource: string;
-    name?: string;
+    treasury: string;
+    network: string;
+    feeBps: number;
 }
 /**
- * Helper for AI Agents (Client-side) to construct headers
+ * PaymentBuilder - Client-side utilities for AI Agents and wallets.
+ * Provides methods to create payment transactions and headers.
+ *
+ * @example
+ * ```typescript
+ * // Create atomic split instructions
+ * const instructions = await PaymentBuilder.createAtomicSplitInstructions({
+ *     sender: wallet.publicKey.toBase58(),
+ *     recipient: requirements.recipient,
+ *     treasury: requirements.treasury,
+ *     amount: requirements.amount,
+ *     asset: requirements.asset,
+ *     connection
+ * });
+ *
+ * // Create payment header after transaction
+ * const header = PaymentBuilder.createHeader({
+ *     signature: txSignature,
+ *     sender: wallet.publicKey.toBase58(),
+ *     ...requirements
+ * });
+ * ```
  */
 export declare class PaymentBuilder {
+    /**
+     * Create the Base64-encoded payment header for the Authorization header.
+     *
+     * @param payload - Payment details including signature and sender info
+     * @returns Base64-encoded payment header string
+     */
     static createHeader(payload: {
         signature: string;
         sender: string;
@@ -23,14 +54,39 @@ export declare class PaymentBuilder {
         network?: string;
     }): string;
     /**
-     * Create Instructions for Atomic Split Payment (99% to Dev, 1% to Zion)
+     * Create transfer instructions for an atomic split payment.
+     * Splits the payment: 99% to developer, 1% to Zion treasury.
+     *
+     * @param config - Configuration for the split transfer
+     * @returns Array of transfer instructions to add to a transaction
+     *
+     * @example
+     * ```typescript
+     * const instructions = await PaymentBuilder.createAtomicSplitInstructions({
+     *     sender: publicKey.toBase58(),
+     *     recipient: "DeveloperWalletAddress",
+     *     treasury: "ZionTreasuryAddress",
+     *     amount: "100000", // 0.1 USDC in atomic units
+     *     asset: "USDCMintAddress",
+     *     connection
+     * });
+     *
+     * const tx = new Transaction();
+     * tx.add(...instructions);
+     * ```
      */
     static createAtomicSplitInstructions(config: {
+        /** Sender's wallet address */
         sender: string;
+        /** Developer's wallet address (receives 99%) */
         recipient: string;
+        /** Zion treasury address (receives 1%) */
         treasury: string;
+        /** Total amount in atomic units */
         amount: string;
+        /** Token mint address (USDC) */
         asset: string;
+        /** Solana connection instance */
         connection: Connection;
     }): Promise<import("@solana/web3.js").TransactionInstruction[]>;
 }

package/dist/index.js

@@ -41,9 +41,36 @@ __exportStar(require("./Universal"), exports);
 __exportStar(require("./ZionGate"), exports);
 const web3_js_1 = require("@solana/web3.js");
 /**
- * Helper for AI Agents (Client-side) to construct headers
+ * PaymentBuilder - Client-side utilities for AI Agents and wallets.
+ * Provides methods to create payment transactions and headers.
+ *
+ * @example
+ * ```typescript
+ * // Create atomic split instructions
+ * const instructions = await PaymentBuilder.createAtomicSplitInstructions({
+ *     sender: wallet.publicKey.toBase58(),
+ *     recipient: requirements.recipient,
+ *     treasury: requirements.treasury,
+ *     amount: requirements.amount,
+ *     asset: requirements.asset,
+ *     connection
+ * });
+ *
+ * // Create payment header after transaction
+ * const header = PaymentBuilder.createHeader({
+ *     signature: txSignature,
+ *     sender: wallet.publicKey.toBase58(),
+ *     ...requirements
+ * });
+ * ```
  */
 class PaymentBuilder {
+    /**
+     * Create the Base64-encoded payment header for the Authorization header.
+     *
+     * @param payload - Payment details including signature and sender info
+     * @returns Base64-encoded payment header string
+     */
     static createHeader(payload) {
         const json = {
             x402Version: 1,
@@ -60,7 +87,26 @@ class PaymentBuilder {
         }
     }
     /**
-     * Create Instructions for Atomic Split Payment (99% to Dev, 1% to Zion)
+     * Create transfer instructions for an atomic split payment.
+     * Splits the payment: 99% to developer, 1% to Zion treasury.
+     *
+     * @param config - Configuration for the split transfer
+     * @returns Array of transfer instructions to add to a transaction
+     *
+     * @example
+     * ```typescript
+     * const instructions = await PaymentBuilder.createAtomicSplitInstructions({
+     *     sender: publicKey.toBase58(),
+     *     recipient: "DeveloperWalletAddress",
+     *     treasury: "ZionTreasuryAddress",
+     *     amount: "100000", // 0.1 USDC in atomic units
+     *     asset: "USDCMintAddress",
+     *     connection
+     * });
+     *
+     * const tx = new Transaction();
+     * tx.add(...instructions);
+     * ```
      */
     static async createAtomicSplitInstructions(config) {
         const { getAssociatedTokenAddress, createTransferInstruction } = await Promise.resolve().then(() => __importStar(require("@solana/spl-token")));
@@ -71,7 +117,7 @@ class PaymentBuilder {
         const recipientPubkey = new web3_js_1.PublicKey(config.recipient);
         const treasuryPubkey = new web3_js_1.PublicKey(config.treasury);
         const mintPubkey = new web3_js_1.PublicKey(config.asset);
-        // Get ATAs
+        // Get Associated Token Addresses
         const senderAta = await getAssociatedTokenAddress(mintPubkey, senderPubkey);
         const recipientAta = await getAssociatedTokenAddress(mintPubkey, recipientPubkey);
         const treasuryAta = await getAssociatedTokenAddress(mintPubkey, treasuryPubkey);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ziongateway/sdk",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "TypeScript SDK for Zion x402 Facilitator",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",