@ziongateway/sdk 0.1.0

package/README.md

@@ -0,0 +1,148 @@
+# Zion SDK
+
+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.
+
+---
+
+## Installation
+
+```bash
+npm install @zion/sdk
+```
+
+---
+
+## Usage (Server-Side)
+
+### 1. Express Middleware
+Protect your API routes by adding `ZionGate` middleware.
+
+```typescript
+import express from "express";
+import { ZionGate } from "@zion/sdk";
+
+const app = express();
+
+// Initialize Zion Gate
+const zion = new ZionGate({
+    apiKey: "YOUR_DEVELOPER_API_KEY", // Get this from Zion Dashboard
+    price: 0.1,                       // Price per request in USDC
+    network: "solana-devnet",         // or "solana-mainnet"
+    facilitatorUrl: "https://your-facilitator-url.com" // Optional if using public Zion Cloud
+    resource: "ai-agent-api" // Optional, default: "api-access"
+});
+
+// Protect a specific route
+app.get("/ai-agent-api", zion.express(), (req, res) => {
+    res.json({ 
+        success: true, 
+        message: "You have paid for this content! 🚀",
+        data: "SECRET_DATA" 
+    });
+});
+
+app.listen(3000, () => console.log("Server running on port 3000"));
+```
+
+### 2. Next.js (App Router)
+Use the `nextServer` helper in your route handlers.
+
+```typescript
+import { ZionGate } from "@zion/sdk";
+
+const zion = new ZionGate({ /* config */ });
+
+export async function GET(req: Request) {
+    const authorized = await zion.nextServer(req);
+    
+    // If not authorized, 'authorized' is a 402 Response object. Return it.
+    if (authorized !== true) return authorized;
+
+    return Response.json({ success: true, data: "Paid Content" });
+}
+```
+
+---
+
+## Usage (Client-Side)
+
+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.
+
+### 1. Handling the 402 Response
+The server returns payment requirements:
+
+```json
+{
+  "recipient": "FjK...",   // Developer's Wallet
+  "amount": "100000",      // Atomic units (0.1 USDC)
+  "asset": "EPj...",       // USDC Mint Address
+  "treasury": "AgH...",    // Zion Treasury (for 1% fee)
+  "message": "Payment Required"
+}
+```
+
+### 2. Creating the Payment Header
+Use `PaymentBuilder` to generate the correct header after signing the transaction.
+
+```typescript
+import { PaymentBuilder } from "@zion/sdk";
+
+// ... Perform Solana Transaction (Split: 99% to recipient, 1% to treasury) ...
+
+// Create the Zion Payment Header
+const header = PaymentBuilder.createHeader({
+    sender: "USER_WALLET_ADDRESS",
+    recipient: "DEVELOPER_WALLET_ADDRESS",
+    amount: "100000",
+    asset: "USDC_MINT_ADDRESS",
+    timestamp: Math.floor(Date.now() / 1000),
+    nonce: "RANDOM_STRING_GT_8_CHARS",
+    signature: "TRANSACTION_SIGNATURE", // From Solana Web3.js
+    network: "solana-devnet"
+});
+
+// Retry the request with the header
+const response = await fetch("http://api.example.com/protected", {
+    headers: {
+        "Authorization": `Bearer ${header}`
+    }
+});
+```
+
+---
+
+## Webhooks
+
+Webhooks allow your application to receive **asynchronous notifications** when payments are successfully settled.
+
+### Do I need Webhooks?
+*   **No**, if you only need to gate a synchronous API response (like the example above). The SDK handles verification immediately before serving the response.
+*   **Yes**, if you need to:
+    *   Trigger a background job (e.g., generate a video, fine-tune a model).
+    *   Update a user's credit balance in your database.
+    *   Send a confirmation email.
+    *   Handle payments that might confirm slowly.
+
+### Setting up Webhooks
+1.  Register your Webhook URL in the **Facilitator Database** (table: `webhooks`).
+2.  Listen for the `payment.success` event.
+
+**Example Payload:**
+```json
+{
+  "event": "payment.success",
+  "payload": {
+    "settlementId": "stl_12345",
+    "amount": "100000",
+    "netAmount": "99000",
+    "payer": "UserAddress...",
+    "resource": "api-access"
+  }
+}
+```

package/dist/Universal.d.ts

@@ -0,0 +1,59 @@
+export interface ZionConfig {
+    apiKey: string;
+    price: number;
+    network?: "solana-mainnet" | "solana-devnet";
+    facilitatorUrl?: string;
+    resource?: string;
+}
+export interface CheckResult {
+    authorized: boolean;
+    error?: {
+        status: number;
+        body: any;
+    };
+    success?: boolean;
+    verification?: VerifyResponse;
+}
+export interface VerifyResponse {
+    valid: boolean;
+    invalidReason?: {
+        code: string;
+        message: string;
+    };
+    payer?: string;
+    transaction?: {
+        signature: string;
+        confirmedAt: string;
+    };
+}
+export interface SettleResponse {
+    success: boolean;
+    error?: {
+        code: string;
+        message: string;
+    };
+    settlement?: {
+        id: string;
+        txSignature: string;
+        network: string;
+        grossAmount: string;
+        fee: string;
+        netAmount: string;
+        feePercent: string;
+        payer: string;
+        recipient: string;
+        settledAt: string;
+    };
+}
+export declare const NETWORKS: {
+    "solana-mainnet": {
+        treasury: string;
+        usdcMint: string;
+        facilitator: string;
+    };
+    "solana-devnet": {
+        treasury: string;
+        usdcMint: string;
+        facilitator: string;
+    };
+};

package/dist/Universal.js

@@ -0,0 +1,15 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.NETWORKS = void 0;
+exports.NETWORKS = {
+    "solana-mainnet": {
+        treasury: "AgH4Eq3JYBpEt5aPgCnZsygf9tnQ5D2qMKH3eJxB5rm8",
+        usdcMint: "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
+        facilitator: "https://zion-x402-facilitator-production.up.railway.app/v1"
+    },
+    "solana-devnet": {
+        treasury: "AgH4Eq3JYBpEt5aPgCnZsygf9tnQ5D2qMKH3eJxB5rm8",
+        usdcMint: "4zMMC9srt5Ri5X14GAgXhaHii3GnPAEERYPJgZJDncDU",
+        facilitator: "https://zion-x402-facilitator-production.up.railway.app/v1"
+    }
+};

package/dist/ZionGate.d.ts

@@ -0,0 +1,35 @@
+import { ZionConfig, CheckResult } from "./Universal";
+export declare class ZionGate {
+    private static instance;
+    private config;
+    private api;
+    private developerWallet;
+    private isInitialized;
+    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.
+     */
+    init(): Promise<void>;
+    /**
+     * Core check logic generic for any framework.
+     */
+    check(headers: Record<string, string | undefined>): Promise<CheckResult>;
+    private create402Response;
+    /**
+     * Express Middleware Adapter
+     */
+    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
+     *   }
+     */
+    nextServer(req: Request): Promise<true | Response>;
+}

package/dist/ZionGate.js

@@ -0,0 +1,178 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ZionGate = void 0;
+const axios_1 = __importDefault(require("axios"));
+const Universal_1 = require("./Universal");
+class ZionGate {
+    constructor(config) {
+        this.developerWallet = null;
+        this.isInitialized = false;
+        this.config = config;
+        const defaults = Universal_1.NETWORKS[config.network || "solana-mainnet"];
+        this.api = axios_1.default.create({
+            baseURL: config.facilitatorUrl || defaults.facilitator,
+            headers: {
+                "X-API-KEY": config.apiKey,
+                "Content-Type": "application/json"
+            }
+        });
+    }
+    /**
+     * 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.
+     */
+    async init() {
+        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;
+            }
+            else {
+                throw new Error("Invalid response from Facilitator wallet endpoint");
+            }
+        }
+        catch (error) {
+            console.error("ZionGate Init Failed:", error.message);
+            throw new Error("Failed to initialize ZionGate: Could not fetch developer wallet.");
+        }
+    }
+    /**
+     * Core check logic generic for any framework.
+     */
+    async check(headers) {
+        if (!this.isInitialized) {
+            await this.init();
+        }
+        const authHeader = headers["authorization"] || headers["Authorization"];
+        // 1. If no header or invalid format -> 402 Payment Required
+        if (!authHeader || typeof authHeader !== 'string' || !authHeader.startsWith("Bearer ")) {
+            return this.create402Response();
+        }
+        const token = authHeader.replace("Bearer ", "");
+        // 2. Verify the token (which is the Payment Header) with Facilitator
+        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", {
+                paymentHeader: token,
+                paymentRequirements: {
+                    recipient: this.developerWallet,
+                    amount: atomicAmount,
+                    asset: defaults.usdcMint,
+                    network: this.config.network || "solana-mainnet",
+                    resource: this.config.resource || "api-access"
+                }
+            });
+            if (!verification.data || !verification.data.valid) {
+                return {
+                    authorized: false,
+                    error: {
+                        status: 403,
+                        body: {
+                            error: "Payment Invalid",
+                            details: verification.data
+                        }
+                    }
+                };
+            }
+            // 3. Settle
+            const settlement = await this.api.post("/v1/settle", {
+                paymentHeader: token,
+                paymentRequirements: {
+                    recipient: this.developerWallet,
+                    amount: atomicAmount,
+                    asset: defaults.usdcMint,
+                    network: this.config.network || "solana-mainnet",
+                    resource: "api-access"
+                }
+            });
+            if (!settlement.data || !settlement.data.success) {
+                return {
+                    authorized: false,
+                    error: {
+                        status: 403,
+                        body: { error: "Payment Settlement Failed", details: settlement.data }
+                    }
+                };
+            }
+            return { authorized: true, success: true, verification: verification.data };
+        }
+        catch (err) {
+            if (err.response) {
+                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
+                        body: err.response.data || { error: "Payment Validation Failed" }
+                    }
+                };
+            }
+            return {
+                authorized: false,
+                error: {
+                    status: 500,
+                    body: { error: "Facilitator Error", message: err.message }
+                }
+            };
+        }
+    }
+    create402Response() {
+        const defaults = Universal_1.NETWORKS[this.config.network || "solana-mainnet"];
+        const atomicAmount = BigInt(Math.floor(this.config.price * 1000000)).toString();
+        return {
+            authorized: false,
+            error: {
+                status: 402,
+                body: {
+                    recipient: this.developerWallet,
+                    amount: atomicAmount,
+                    asset: defaults.usdcMint,
+                    treasury: defaults.treasury,
+                    feeBps: 100, // 1%
+                    message: "Payment Required. Split transaction: 99% to recipient, 1% to treasury."
+                }
+            }
+        };
+    }
+    // Adapters
+    /**
+     * Express Middleware Adapter
+     */
+    express() {
+        return async (req, res, next) => {
+            const result = await this.check(req.headers);
+            if (result.authorized) {
+                return next();
+            }
+            return res.status(result.error.status).json(result.error.body);
+        };
+    }
+    /**
+     * 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
+     *   }
+     */
+    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);
+        if (result.authorized) {
+            return true;
+        }
+        return Response.json(result.error.body, { status: result.error.status });
+    }
+}
+exports.ZionGate = ZionGate;

package/dist/index.d.ts

@@ -0,0 +1,36 @@
+export * from "./Universal";
+export * from "./ZionGate";
+import { Connection } from "@solana/web3.js";
+export interface PaymentRequirements {
+    recipient: string;
+    amount: string;
+    asset: string;
+    resource: string;
+    name?: string;
+}
+/**
+ * Helper for AI Agents (Client-side) to construct headers
+ */
+export declare class PaymentBuilder {
+    static createHeader(payload: {
+        signature: string;
+        sender: string;
+        recipient: string;
+        amount: string;
+        asset: string;
+        timestamp: number;
+        nonce: string;
+        network?: string;
+    }): string;
+    /**
+     * Create Instructions for Atomic Split Payment (99% to Dev, 1% to Zion)
+     */
+    static createAtomicSplitInstructions(config: {
+        sender: string;
+        recipient: string;
+        treasury: string;
+        amount: string;
+        asset: string;
+        connection: Connection;
+    }): Promise<import("@solana/web3.js").TransactionInstruction[]>;
+}

package/dist/index.js

@@ -0,0 +1,85 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PaymentBuilder = void 0;
+__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
+ */
+class PaymentBuilder {
+    static createHeader(payload) {
+        const json = {
+            x402Version: 1,
+            scheme: "exact",
+            network: payload.network || "solana-mainnet",
+            payload: payload,
+        };
+        const jsonStr = JSON.stringify(json);
+        if (typeof window !== "undefined" && typeof window.btoa === "function") {
+            return window.btoa(jsonStr);
+        }
+        else {
+            return Buffer.from(jsonStr).toString("base64");
+        }
+    }
+    /**
+     * Create Instructions for Atomic Split Payment (99% to Dev, 1% to Zion)
+     */
+    static async createAtomicSplitInstructions(config) {
+        const { getAssociatedTokenAddress, createTransferInstruction } = await Promise.resolve().then(() => __importStar(require("@solana/spl-token")));
+        const total = BigInt(config.amount);
+        const fee = (total * BigInt(100)) / BigInt(10000); // 1%
+        const net = total - fee;
+        const senderPubkey = new web3_js_1.PublicKey(config.sender);
+        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
+        const senderAta = await getAssociatedTokenAddress(mintPubkey, senderPubkey);
+        const recipientAta = await getAssociatedTokenAddress(mintPubkey, recipientPubkey);
+        const treasuryAta = await getAssociatedTokenAddress(mintPubkey, treasuryPubkey);
+        // Instruction 1: 99% to Developer
+        const ix1 = createTransferInstruction(senderAta, recipientAta, senderPubkey, net);
+        // Instruction 2: 1% to Treasury
+        const ix2 = createTransferInstruction(senderAta, treasuryAta, senderPubkey, fee);
+        return [ix1, ix2];
+    }
+}
+exports.PaymentBuilder = PaymentBuilder;

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@ziongateway/sdk",
+  "version": "0.1.0",
+  "description": "TypeScript SDK for Zion x402 Facilitator",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": "./dist/index.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "solana",
+    "x402",
+    "payments",
+    "ai",
+    "agents"
+  ],
+  "author": "Zion",
+  "license": "ISC",
+  "dependencies": {
+    "@solana/spl-token": "^0.4.14",
+    "@solana/web3.js": "^1.98.4",
+    "axios": "^1.6.0"
+  },
+  "devDependencies": {
+    "@types/bs58": "^4.0.4",
+    "@types/express": "^5.0.6",
+    "@types/node": "^20.0.0",
+    "dotenv": "^17.2.3",
+    "express": "^5.2.1",
+    "typescript": "^5.0.0"
+  },
+  "files": ["dist"],
+  "homepage": "https://docs.ziongateway.xyz"
+}