@warppay402/sdk 1.0.0

package/README.md

@@ -0,0 +1,53 @@
+# @warppay402/sdk
+
+Official TypeScript SDK for **WarpPay402**—pay-per-use AI tools monetized via x402 USDC micropayments on Base Mainnet.
+
+## 📦 Installation
+
+```bash
+npm install @warppay402/sdk
+```
+## 🚀 Quickstart
+```typescript
+import { WarpPayClient } from "@warppay402/sdk";
+
+// Initialize with your AI agent's Base wallet private key
+const client = new WarpPayClient({
+  privateKey: process.env.CUSTOMER_PRIVATE_KEY as `0x${string}`,
+});
+
+async function main() {
+  // Scrapes any URL into clean Markdown ($0.01 USDC)
+  const page = await client.scrapeWeb("https://news.ycombinator.com");
+  console.log("Title:", page.title);
+  console.log("Markdown:", page.markdown);
+
+  // Fetch Base wallet analytics ($0.02 USDC)
+  const analytics = await client.getBaseAnalytics("0x556c77792642E8ff95eC930FFb8D46a76579126E");
+  console.log("ETH Balance:", analytics.ethBalance);
+
+  // Extract PDF text preview ($0.05 USDC)
+  const pdf = await client.extractPdf("https://example.com/document.pdf");
+  console.log("Preview:", pdf.textPreview);
+}
+
+main();
+```
+## 🛠️ LangChain Integration
+```typescript
+import { WarpPayClient, createWarpPayLangChainTools } from "@warppay402/sdk";
+
+const client = new WarpPayClient({
+  privateKey: process.env.CUSTOMER_PRIVATE_KEY as `0x${string}`,
+});
+
+// Pass directly into your LangChain or AutoGen agent setup
+const tools = createWarpPayLangChainTools(client);
+```
+## 🌐 API Gateway & Specs
+
+Gateway: https://api.warppay402.com
+
+MCP Manifest: https://api.warppay402.com/.well-known/mcp.json
+
+OpenAPI Spec: https://api.warppay402.com/openapi.json

package/dist/index.d.ts

@@ -0,0 +1,48 @@
+export interface WarpPayConfig {
+    /** Base Mainnet private key of the agent's wallet funding the micro-payments */
+    privateKey: `0x${string}`;
+    /** Custom gateway URL (Defaults to https://api.warppay402.com) */
+    baseUrl?: string;
+}
+export interface ScrapeResponse {
+    success: boolean;
+    title: string;
+    markdown: string;
+    truncated: boolean;
+}
+export interface BaseAnalyticsResponse {
+    success: boolean;
+    network: string;
+    address: string;
+    ethBalance: string;
+    nonce: number;
+    timestamp: string;
+}
+export interface PdfExtractorResponse {
+    success: boolean;
+    pages: number;
+    info: Record<string, any>;
+    textPreview: string;
+}
+export declare class WarpPayClient {
+    private baseUrl;
+    private account;
+    constructor(config: WarpPayConfig);
+    /**
+     * Internal helper handling the initial HTTP request, 402 Payment Required challenge,
+     * EIP-712 signing, and automated retry with x402 payment authorization headers.
+     */
+    private executePaidRequest;
+    /**
+     * Scrapes any Web URL into clean Markdown for AI context ($0.01 USDC on Base)
+     */
+    scrapeWeb(url: string): Promise<ScrapeResponse>;
+    /**
+     * Fetches Base Mainnet balance and transaction stats for any 0x wallet ($0.02 USDC on Base)
+     */
+    getBaseAnalytics(address: string): Promise<BaseAnalyticsResponse>;
+    /**
+     * Downloads and extracts text preview from a public PDF URL ($0.05 USDC on Base)
+     */
+    extractPdf(pdfUrl: string): Promise<PdfExtractorResponse>;
+}

package/dist/index.js

@@ -0,0 +1,125 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WarpPayClient = void 0;
+const node_crypto_1 = __importDefault(require("node:crypto"));
+const node_buffer_1 = require("node:buffer");
+const accounts_1 = require("viem/accounts");
+class WarpPayClient {
+    baseUrl;
+    account;
+    constructor(config) {
+        this.baseUrl = (config.baseUrl || "https://api.warppay402.com").replace(/\/$/, "");
+        const rawKey = config.privateKey.trim();
+        const formattedKey = (rawKey.startsWith("0x") ? rawKey : `0x${rawKey}`);
+        this.account = (0, accounts_1.privateKeyToAccount)(formattedKey);
+    }
+    /**
+     * Internal helper handling the initial HTTP request, 402 Payment Required challenge,
+     * EIP-712 signing, and automated retry with x402 payment authorization headers.
+     */
+    async executePaidRequest(endpoint, payload) {
+        const url = `${this.baseUrl}${endpoint}`;
+        // 1. Initial Request
+        let response = await fetch(url, {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify(payload),
+        });
+        // 2. Handle x402 V2 Payment Challenge if HTTP 402 returned
+        if (response.status === 402) {
+            const challenge = await response.json();
+            const req = challenge.x402?.accepts?.[0] || challenge.accepts?.[0] || {};
+            const payTo = (req.payToAddress || req.payTo || "0x0000000000000000000000000000000000000000");
+            const assetContract = (req.asset || req.usdcAddress || "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913");
+            const value = BigInt(req.maxAmountRequired || req.amount || "10000");
+            const domain = {
+                name: req.extra?.name || "USD Coin",
+                version: req.extra?.version || "2",
+                chainId: 8453,
+                verifyingContract: assetContract,
+            };
+            const types = {
+                TransferWithAuthorization: [
+                    { name: "from", type: "address" },
+                    { name: "to", type: "address" },
+                    { name: "value", type: "uint256" },
+                    { name: "validAfter", type: "uint256" },
+                    { name: "validBefore", type: "uint256" },
+                    { name: "nonce", type: "bytes32" },
+                ],
+            };
+            const now = Math.floor(Date.now() / 1000);
+            const nonce = `0x${node_crypto_1.default.randomBytes(32).toString("hex")}`;
+            const message = {
+                from: this.account.address,
+                to: payTo,
+                value,
+                validAfter: BigInt(0),
+                validBefore: BigInt(now + 3600),
+                nonce,
+            };
+            // Sign typed EIP-712 USDC TransferWithAuthorization data
+            const signature = await this.account.signTypedData({
+                domain,
+                types,
+                primaryType: "TransferWithAuthorization",
+                message,
+            });
+            const paymentPayload = {
+                x402Version: 2,
+                scheme: req.scheme || "exact",
+                network: req.network || "eip155:8453",
+                payload: {
+                    authorization: {
+                        from: this.account.address,
+                        to: payTo,
+                        value: value.toString(),
+                        validAfter: "0",
+                        validBefore: (now + 3600).toString(),
+                        nonce,
+                    },
+                    signature,
+                },
+            };
+            const encodedPayload = node_buffer_1.Buffer.from(JSON.stringify(paymentPayload)).toString("base64");
+            // Retry request with signed x402 headers
+            response = await fetch(url, {
+                method: "POST",
+                headers: {
+                    "Content-Type": "application/json",
+                    "X-PAYMENT": encodedPayload,
+                    "PAYMENT-SIGNATURE": encodedPayload,
+                    "X-PAYMENT-SIGNATURE": signature,
+                },
+                body: JSON.stringify(payload),
+            });
+        }
+        if (!response.ok) {
+            const errText = await response.text();
+            throw new Error(`WarpPay API Error (${response.status}): ${errText}`);
+        }
+        return (await response.json());
+    }
+    /**
+     * Scrapes any Web URL into clean Markdown for AI context ($0.01 USDC on Base)
+     */
+    async scrapeWeb(url) {
+        return this.executePaidRequest("/api/v1/tools/web-scraper", { url });
+    }
+    /**
+     * Fetches Base Mainnet balance and transaction stats for any 0x wallet ($0.02 USDC on Base)
+     */
+    async getBaseAnalytics(address) {
+        return this.executePaidRequest("/api/v1/tools/base-analytics", { address });
+    }
+    /**
+     * Downloads and extracts text preview from a public PDF URL ($0.05 USDC on Base)
+     */
+    async extractPdf(pdfUrl) {
+        return this.executePaidRequest("/api/v1/tools/pdf-extractor", { pdfUrl });
+    }
+}
+exports.WarpPayClient = WarpPayClient;

package/dist/langchain.d.ts

@@ -0,0 +1,23 @@
+import { WarpPayClient } from "./index.js";
+/**
+ * Generates LangChain-compatible tool definitions initialized with WarpPay402
+ */
+export declare function createWarpPayLangChainTools(client: WarpPayClient): ({
+    name: string;
+    description: string;
+    func: ({ url }: {
+        url: string;
+    }) => Promise<string>;
+} | {
+    name: string;
+    description: string;
+    func: ({ address }: {
+        address: string;
+    }) => Promise<string>;
+} | {
+    name: string;
+    description: string;
+    func: ({ pdfUrl }: {
+        pdfUrl: string;
+    }) => Promise<string>;
+})[];

package/dist/langchain.js

@@ -0,0 +1,34 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createWarpPayLangChainTools = createWarpPayLangChainTools;
+/**
+ * Generates LangChain-compatible tool definitions initialized with WarpPay402
+ */
+function createWarpPayLangChainTools(client) {
+    return [
+        {
+            name: "web_scraper",
+            description: "Scrapes a web page URL and returns clean markdown content. Costs $0.01 USDC on Base.",
+            func: async ({ url }) => {
+                const result = await client.scrapeWeb(url);
+                return result.markdown;
+            },
+        },
+        {
+            name: "base_analytics",
+            description: "Fetches ETH balance and nonce for a Base 0x wallet address. Costs $0.02 USDC on Base.",
+            func: async ({ address }) => {
+                const result = await client.getBaseAnalytics(address);
+                return JSON.stringify(result);
+            },
+        },
+        {
+            name: "pdf_extractor",
+            description: "Extracts text preview from a public PDF URL. Costs $0.05 USDC on Base.",
+            func: async ({ pdfUrl }) => {
+                const result = await client.extractPdf(pdfUrl);
+                return result.textPreview;
+            },
+        },
+    ];
+}

package/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "@warppay402/sdk",
+  "version": "1.0.0",
+  "description": "Official TypeScript SDK for WarpPay402 pay-per-use AI tools on Base Mainnet",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "scripts": {
+    "build": "tsc"
+  },
+  "keywords": [
+    "x402",
+    "base",
+    "ai-agents",
+    "mcp",
+    "monetization",
+    "langchain"
+  ],
+  "dependencies": {
+    "@golfgolfgolf200/x402-monetize": "^1.0.2",
+    "viem": "^2.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^26.2.0",
+    "typescript": "^5.0.0"
+  }
+}

package/src/index.ts

@@ -0,0 +1,168 @@
+import crypto from "node:crypto";
+import { Buffer } from "node:buffer";
+import { privateKeyToAccount } from "viem/accounts";
+
+export interface WarpPayConfig {
+  /** Base Mainnet private key of the agent's wallet funding the micro-payments */
+  privateKey: `0x${string}`;
+  /** Custom gateway URL (Defaults to https://api.warppay402.com) */
+  baseUrl?: string;
+}
+
+export interface ScrapeResponse {
+  success: boolean;
+  title: string;
+  markdown: string;
+  truncated: boolean;
+}
+
+export interface BaseAnalyticsResponse {
+  success: boolean;
+  network: string;
+  address: string;
+  ethBalance: string;
+  nonce: number;
+  timestamp: string;
+}
+
+export interface PdfExtractorResponse {
+  success: boolean;
+  pages: number;
+  info: Record<string, any>;
+  textPreview: string;
+}
+
+export class WarpPayClient {
+  private baseUrl: string;
+  private account;
+
+  constructor(config: WarpPayConfig) {
+    this.baseUrl = (config.baseUrl || "https://api.warppay402.com").replace(/\/$/, "");
+    
+    const rawKey = config.privateKey.trim();
+    const formattedKey = (rawKey.startsWith("0x") ? rawKey : `0x${rawKey}`) as `0x${string}`;
+    this.account = privateKeyToAccount(formattedKey);
+  }
+
+  /**
+   * Internal helper handling the initial HTTP request, 402 Payment Required challenge,
+   * EIP-712 signing, and automated retry with x402 payment authorization headers.
+   */
+  private async executePaidRequest<T>(endpoint: string, payload: Record<string, any>): Promise<T> {
+    const url = `${this.baseUrl}${endpoint}`;
+
+    // 1. Initial Request
+    let response = await fetch(url, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify(payload),
+    });
+
+    // 2. Handle x402 V2 Payment Challenge if HTTP 402 returned
+    if (response.status === 402) {
+      const challenge = await response.json();
+
+      const req = challenge.x402?.accepts?.[0] || challenge.accepts?.[0] || {};
+      const payTo = (req.payToAddress || req.payTo || "0x0000000000000000000000000000000000000000") as `0x${string}`;
+      const assetContract = (req.asset || req.usdcAddress || "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913") as `0x${string}`;
+      const value = BigInt(req.maxAmountRequired || req.amount || "10000");
+
+      const domain = {
+        name: req.extra?.name || "USD Coin",
+        version: req.extra?.version || "2",
+        chainId: 8453,
+        verifyingContract: assetContract,
+      };
+
+      const types = {
+        TransferWithAuthorization: [
+          { name: "from", type: "address" },
+          { name: "to", type: "address" },
+          { name: "value", type: "uint256" },
+          { name: "validAfter", type: "uint256" },
+          { name: "validBefore", type: "uint256" },
+          { name: "nonce", type: "bytes32" },
+        ],
+      };
+
+      const now = Math.floor(Date.now() / 1000);
+      const nonce = `0x${crypto.randomBytes(32).toString("hex")}` as `0x${string}`;
+
+      const message = {
+        from: this.account.address,
+        to: payTo,
+        value,
+        validAfter: BigInt(0),
+        validBefore: BigInt(now + 3600),
+        nonce,
+      };
+
+      // Sign typed EIP-712 USDC TransferWithAuthorization data
+      const signature = await this.account.signTypedData({
+        domain,
+        types,
+        primaryType: "TransferWithAuthorization",
+        message,
+      });
+
+      const paymentPayload = {
+        x402Version: 2,
+        scheme: req.scheme || "exact",
+        network: req.network || "eip155:8453",
+        payload: {
+          authorization: {
+            from: this.account.address,
+            to: payTo,
+            value: value.toString(),
+            validAfter: "0",
+            validBefore: (now + 3600).toString(),
+            nonce,
+          },
+          signature,
+        },
+      };
+
+      const encodedPayload = Buffer.from(JSON.stringify(paymentPayload)).toString("base64");
+
+      // Retry request with signed x402 headers
+      response = await fetch(url, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          "X-PAYMENT": encodedPayload,
+          "PAYMENT-SIGNATURE": encodedPayload,
+          "X-PAYMENT-SIGNATURE": signature,
+        },
+        body: JSON.stringify(payload),
+      });
+    }
+
+    if (!response.ok) {
+      const errText = await response.text();
+      throw new Error(`WarpPay API Error (${response.status}): ${errText}`);
+    }
+
+    return (await response.json()) as T;
+  }
+
+  /**
+   * Scrapes any Web URL into clean Markdown for AI context ($0.01 USDC on Base)
+   */
+  public async scrapeWeb(url: string): Promise<ScrapeResponse> {
+    return this.executePaidRequest<ScrapeResponse>("/api/v1/tools/web-scraper", { url });
+  }
+
+  /**
+   * Fetches Base Mainnet balance and transaction stats for any 0x wallet ($0.02 USDC on Base)
+   */
+  public async getBaseAnalytics(address: string): Promise<BaseAnalyticsResponse> {
+    return this.executePaidRequest<BaseAnalyticsResponse>("/api/v1/tools/base-analytics", { address });
+  }
+
+  /**
+   * Downloads and extracts text preview from a public PDF URL ($0.05 USDC on Base)
+   */
+  public async extractPdf(pdfUrl: string): Promise<PdfExtractorResponse> {
+    return this.executePaidRequest<PdfExtractorResponse>("/api/v1/tools/pdf-extractor", { pdfUrl });
+  }
+}

package/src/langchain.ts

@@ -0,0 +1,33 @@
+import { WarpPayClient } from "./index.js";
+
+/**
+ * Generates LangChain-compatible tool definitions initialized with WarpPay402
+ */
+export function createWarpPayLangChainTools(client: WarpPayClient) {
+  return [
+    {
+      name: "web_scraper",
+      description: "Scrapes a web page URL and returns clean markdown content. Costs $0.01 USDC on Base.",
+      func: async ({ url }: { url: string }) => {
+        const result = await client.scrapeWeb(url);
+        return result.markdown;
+      },
+    },
+    {
+      name: "base_analytics",
+      description: "Fetches ETH balance and nonce for a Base 0x wallet address. Costs $0.02 USDC on Base.",
+      func: async ({ address }: { address: string }) => {
+        const result = await client.getBaseAnalytics(address);
+        return JSON.stringify(result);
+      },
+    },
+    {
+      name: "pdf_extractor",
+      description: "Extracts text preview from a public PDF URL. Costs $0.05 USDC on Base.",
+      func: async ({ pdfUrl }: { pdfUrl: string }) => {
+        const result = await client.extractPdf(pdfUrl);
+        return result.textPreview;
+      },
+    },
+  ];
+}

package/tsconfig.json

@@ -0,0 +1,14 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "declaration": true,
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true
+  },
+  "include": ["src/**/*"]
+}