@payroute/x402-sdk 1.0.0

package/README.md

@@ -0,0 +1,110 @@
+# Payroute x402 SDK
+
+The official Node.js and TypeScript SDK for the **Payroute Protocol** on Mantle Network.
+
+This SDK abstracts the complexity of **HTTP 402 Pay-Per-Hit** workflows, enabling seamless autonomous payments for premium APIs, static content, and AI Agents. It handles wallet management, token approvals, on-chain escrow transactions, and automatic request retries.
+
+## Features
+
+- 🚀 **Full x402 Abstraction**: Automates the HTTP 402 -> Payment -> Retry loop.
+- 💸 **Mantle Network Support**: Built for Mantle Mainnet and Sepolia Testnet.
+- 🤖 **AI Agent Ready**: Dedicated methods for interacting with Payroute-enabled AI Agents.
+- 📦 **Token Management**: Automatically handles ERC20 (MUSD) approvals and transfers.
+- 🛡️ **Type-Safe**: Written in TypeScript with full type definitions.
+
+## Installation
+
+```bash
+npm install payroute-x402-sdk ethers
+```
+
+_Note: `ethers` peer dependency (v6) is required._
+
+## Quick Start
+
+### 1. Initialize the Service
+
+```typescript
+import { PaymentService } from "payroute-x402-sdk";
+
+const service = new PaymentService({
+  privateKey: process.env.WALLET_PRIVATE_KEY, // Your EVM private key
+  network: "mantle", // 'mantle' | 'mantleTestnet' | 'localhost'
+});
+```
+
+### 2. Consume a Paid Proxy Endpoint
+
+Access premium content served behind a Payroute gateway.
+
+```typescript
+try {
+  const content = await service.getProxyEndpoint("my-premium-blog-post");
+  console.log("Accessed Content:", content);
+} catch (error) {
+  console.error("Payment or Fetch Failed:", error);
+}
+```
+
+### 3. Interact with a Paid AI Agent
+
+Send messages to an AI agent that requires per-message payments.
+
+```typescript
+try {
+  const response = await service.generateAIResponse(
+    "finance-advisor-agent",
+    "What is the outlook for MNT?"
+  );
+  console.log("AI Response:", response);
+} catch (error) {
+  console.error("Agent Interaction Failed:", error);
+}
+```
+
+## Advanced Usage
+
+### Custom RPC Provider
+
+You can override the default RPC URLs for custom configuration.
+
+```typescript
+const service = new PaymentService({
+  privateKey: "...",
+  rpcUrl: "https://rpc.ankr.com/mantle",
+});
+```
+
+### Generic Pay-And-Retry
+
+If you are building a custom integration that follows the x402 generic pattern but doesn't fit the standard gateway/agent flow, you can use the low-level `payAndRetry` method.
+
+```typescript
+const response = await service.payAndRetry({
+  paymentData: {
+    amount: "1000000000000000000", // 1 ETH/MNT in wei
+    recipient: "0x123...",
+  },
+  retryRequest: async (headers) => {
+    // Perform your custom retry logic here using the provided headers
+    // headers['X-Payment-Tx'] will contain the transaction hash
+    return fetch("https://api.custom.com/resource", { headers });
+  },
+});
+```
+
+## Architecture
+
+The SDK implements the **Payroute x402 Protocol**:
+
+1.  **Request**: SDK attempts to access a resource.
+2.  **Challenge (402)**: Server responds with `402 Payment Required` and payment details (Escrow contract, Amount, Transaction ID).
+3.  **Approval**: SDK approves the required token (MUSD) for the escrow contract.
+4.  **Payment**: SDK calls the Escrow contract's `createTx` function.
+5.  **Confirmation**: SDK waits for blockchain confirmation.
+6.  **Retry**: SDK retries the original request with the transaction hash in the `x-payment-tx` header.
+7.  **Response**: Server validates the transaction and returns the content.
+
+## License
+
+MIT © [Payroute Protocol](https://github.com/payroute-protocol)

package/dist/index.d.mts

@@ -0,0 +1,56 @@
+/**
+ * PaymentData interface for transaction details
+ */
+interface PaymentData {
+    amount: string;
+    recipient: string;
+    currency?: string;
+}
+/**
+ * Configuration options for the PaymentService
+ */
+interface PaymentServiceConfig {
+    privateKey: string;
+    network?: 'mantle' | 'mantleTestnet' | 'localhost';
+    rpcUrl?: string;
+}
+/**
+ * PaymentService class
+ * Handles EVM wallet initialization, transaction signing, and payment flow with retries.
+ */
+declare class PaymentService {
+    private wallet;
+    private provider;
+    constructor(config: PaymentServiceConfig);
+    /**
+     * Performs a payment on-chain and retries the original request with proof of payment.
+     *
+     * @param params.paymentData - The payment details (amount, recipient).
+     * @param params.retryRequest - A callback that performs the HTTP request. Must accept headers.
+     * @returns The response from the retried request.
+     */
+    payAndRetry<T>(params: {
+        paymentData: PaymentData;
+        retryRequest: (headers: Record<string, string>) => Promise<T>;
+    }): Promise<T>;
+    /**
+     * Get AI response
+     *
+     * @param agentSlug
+     * @returns
+     */
+    generateAIResponse<T = any>(agentSlug: string, message: string): Promise<T>;
+    /**
+     * Get proxy endpoint
+     *
+     * @param gatewaySlug
+     * @returns
+     */
+    getProxyEndpoint<T = any>(gatewaySlug: string): Promise<T>;
+    /**
+     * Helper to get the current wallet address
+     */
+    getAddress(): string;
+}
+
+export { type PaymentData, PaymentService, type PaymentServiceConfig };

package/dist/index.d.ts

@@ -0,0 +1,56 @@
+/**
+ * PaymentData interface for transaction details
+ */
+interface PaymentData {
+    amount: string;
+    recipient: string;
+    currency?: string;
+}
+/**
+ * Configuration options for the PaymentService
+ */
+interface PaymentServiceConfig {
+    privateKey: string;
+    network?: 'mantle' | 'mantleTestnet' | 'localhost';
+    rpcUrl?: string;
+}
+/**
+ * PaymentService class
+ * Handles EVM wallet initialization, transaction signing, and payment flow with retries.
+ */
+declare class PaymentService {
+    private wallet;
+    private provider;
+    constructor(config: PaymentServiceConfig);
+    /**
+     * Performs a payment on-chain and retries the original request with proof of payment.
+     *
+     * @param params.paymentData - The payment details (amount, recipient).
+     * @param params.retryRequest - A callback that performs the HTTP request. Must accept headers.
+     * @returns The response from the retried request.
+     */
+    payAndRetry<T>(params: {
+        paymentData: PaymentData;
+        retryRequest: (headers: Record<string, string>) => Promise<T>;
+    }): Promise<T>;
+    /**
+     * Get AI response
+     *
+     * @param agentSlug
+     * @returns
+     */
+    generateAIResponse<T = any>(agentSlug: string, message: string): Promise<T>;
+    /**
+     * Get proxy endpoint
+     *
+     * @param gatewaySlug
+     * @returns
+     */
+    getProxyEndpoint<T = any>(gatewaySlug: string): Promise<T>;
+    /**
+     * Helper to get the current wallet address
+     */
+    getAddress(): string;
+}
+
+export { type PaymentData, PaymentService, type PaymentServiceConfig };

package/dist/index.js

@@ -0,0 +1,234 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  PaymentService: () => PaymentService
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/PaymentService.ts
+var import_ethers = require("ethers");
+var NETWORKS = {
+  mantle: {
+    name: "Mantle Mainnet",
+    rpc: "https://rpc.mantle.xyz",
+    chainId: 5e3
+  },
+  mantleTestnet: {
+    name: "Mantle Testnet",
+    rpc: "https://rpc.sepolia.mantle.xyz",
+    chainId: 5003
+  },
+  localhost: {
+    name: "Localhost",
+    rpc: "http://127.0.0.1:8545",
+    chainId: 31337
+  }
+};
+var BASE_ENDPOINT = "https://x402-services.vercel.app";
+var ESCROW_ABI = [
+  "function createTx(string txId, address creator, uint256 amount) external payable"
+];
+var MUSD_ADDRESS = "0x4dABf45C8cF333Ef1e874c3FDFC3C86799af80c8";
+var ERC20_ABI = [
+  "function approve(address spender, uint256 amount) external returns (bool)"
+];
+var PaymentService = class {
+  wallet;
+  provider;
+  constructor(config) {
+    const networkKey = config.network || "mantle";
+    const networkConfig = NETWORKS[networkKey];
+    if (!networkConfig && !config.rpcUrl) {
+      throw new Error(`Invalid network: ${networkKey} and no RPC URL provided.`);
+    }
+    const rpcUrl = config.rpcUrl || networkConfig?.rpc;
+    this.provider = new import_ethers.ethers.JsonRpcProvider(rpcUrl);
+    try {
+      this.wallet = new import_ethers.ethers.Wallet(config.privateKey, this.provider);
+    } catch (error) {
+      throw new Error("Invalid private key provided.");
+    }
+  }
+  /**
+   * Performs a payment on-chain and retries the original request with proof of payment.
+   * 
+   * @param params.paymentData - The payment details (amount, recipient).
+   * @param params.retryRequest - A callback that performs the HTTP request. Must accept headers.
+   * @returns The response from the retried request.
+   */
+  async payAndRetry(params) {
+    const { paymentData, retryRequest } = params;
+    try {
+      if (!import_ethers.ethers.isAddress(paymentData.recipient)) {
+        throw new Error(`Invalid recipient address: ${paymentData.recipient}`);
+      }
+      const txRequest = {
+        to: paymentData.recipient,
+        value: BigInt(paymentData.amount)
+        // Gas limit/price will be estimated by provider/wallet
+      };
+      const txResponse = await this.wallet.sendTransaction(txRequest);
+      const receipt = await txResponse.wait(1);
+      if (!receipt || receipt.status !== 1) {
+        throw new Error("Transaction failed or was reverted on-chain.");
+      }
+      const txHash = receipt.hash;
+      const headers = {
+        "X-Payment-Tx": txHash,
+        "Content-Type": "application/json"
+        // Default content type, extendable if needed
+      };
+      return await retryRequest(headers);
+    } catch (error) {
+      const errorMessage = error instanceof Error ? error.message : "Unknown error occurred during payment flow";
+      throw new Error(`PaymentService Failed: ${errorMessage}`);
+    }
+  }
+  /**
+   * Get AI response
+   * 
+   * @param agentSlug
+   * @returns
+   */
+  async generateAIResponse(agentSlug, message) {
+    try {
+      const initialResponse = await fetch(`${BASE_ENDPOINT}/agent/${agentSlug}/chat`, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json"
+        },
+        body: JSON.stringify({
+          message
+        })
+      });
+      if (!initialResponse.ok && initialResponse.status !== 402) {
+        throw new Error(`Unexpected status code: ${initialResponse.status}`);
+      }
+      const paymentDetail = await initialResponse.json();
+      const txId = paymentDetail.transactionId;
+      const escrowAddress = paymentDetail.escrowAddress;
+      const amountPayment = paymentDetail.amountPayment;
+      const contractAddress = paymentDetail.contractAddress;
+      if (!contractAddress) {
+        throw new Error("Contract address not found in payment details.");
+      }
+      const musdContract = new import_ethers.ethers.Contract(MUSD_ADDRESS, ERC20_ABI, this.wallet);
+      const approveTx = await musdContract.approve(contractAddress, amountPayment);
+      await approveTx.wait(1);
+      const contract = new import_ethers.ethers.Contract(contractAddress, ESCROW_ABI, this.wallet);
+      const txResponse = await contract.createTx(
+        txId,
+        escrowAddress,
+        amountPayment
+      );
+      const receipt = await txResponse.wait(1);
+      if (!receipt || receipt.status !== 1) {
+        throw new Error("Escrow transaction failed.");
+      }
+      const finalTxHash = receipt.hash;
+      const headers = {
+        "x-payment-tx": finalTxHash,
+        "Content-Type": "application/json"
+      };
+      const retryResponse = await fetch(`${BASE_ENDPOINT}/agent/${agentSlug}/chat`, {
+        method: "POST",
+        headers,
+        body: JSON.stringify({
+          message
+        })
+      });
+      if (!retryResponse.ok) {
+        const errorText = await retryResponse.text();
+        throw new Error(`Retry failed: ${retryResponse.status} - ${errorText}`);
+      }
+      return await retryResponse.json();
+    } catch (error) {
+      const errorMessage = error instanceof Error ? error.message : "Unknown error occurred during payment flow";
+      throw new Error(`PaymentService Failed: ${errorMessage}`);
+    }
+  }
+  /**
+   * Get proxy endpoint
+   * 
+   * @param gatewaySlug 
+   * @returns 
+   */
+  async getProxyEndpoint(gatewaySlug) {
+    try {
+      const initialResponse = await fetch(`${BASE_ENDPOINT}/escrow/${gatewaySlug}`);
+      if (initialResponse.ok) {
+        return await initialResponse.json();
+      }
+      if (initialResponse.status !== 402) {
+        throw new Error(`Unexpected status code: ${initialResponse.status}`);
+      }
+      const paymentDetail = await initialResponse.json();
+      const txId = paymentDetail.transactionId;
+      const escrowAddress = paymentDetail.escrowAddress;
+      const amountPayment = paymentDetail.amountPayment;
+      const contractAddress = paymentDetail.contractAddress;
+      if (!contractAddress) {
+        throw new Error("Contract address not found in payment details.");
+      }
+      const musdContract = new import_ethers.ethers.Contract(MUSD_ADDRESS, ERC20_ABI, this.wallet);
+      const approveTx = await musdContract.approve(contractAddress, amountPayment);
+      await approveTx.wait(1);
+      const contract = new import_ethers.ethers.Contract(contractAddress, ESCROW_ABI, this.wallet);
+      const txResponse = await contract.createTx(
+        txId,
+        escrowAddress,
+        amountPayment
+      );
+      const receipt = await txResponse.wait(1);
+      if (!receipt || receipt.status !== 1) {
+        throw new Error("Escrow transaction failed.");
+      }
+      const finalTxHash = receipt.hash;
+      const headers = {
+        "x-payment-tx": finalTxHash,
+        "Content-Type": "application/json"
+      };
+      const retryResponse = await fetch(`${BASE_ENDPOINT}/${gatewaySlug}`, {
+        method: "GET",
+        headers
+      });
+      if (!retryResponse.ok) {
+        const errorText = await retryResponse.text();
+        throw new Error(`Retry failed: ${retryResponse.status} - ${errorText}`);
+      }
+      return await retryResponse.json();
+    } catch (error) {
+      const errorMessage = error instanceof Error ? error.message : "Unknown error in getProxyEndpoint";
+      throw new Error(`Proxy Endpoint Failed: ${errorMessage}`);
+    }
+  }
+  /**
+   * Helper to get the current wallet address
+   */
+  getAddress() {
+    return this.wallet.address;
+  }
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  PaymentService
+});

package/dist/index.mjs

@@ -0,0 +1,207 @@
+// src/PaymentService.ts
+import { ethers } from "ethers";
+var NETWORKS = {
+  mantle: {
+    name: "Mantle Mainnet",
+    rpc: "https://rpc.mantle.xyz",
+    chainId: 5e3
+  },
+  mantleTestnet: {
+    name: "Mantle Testnet",
+    rpc: "https://rpc.sepolia.mantle.xyz",
+    chainId: 5003
+  },
+  localhost: {
+    name: "Localhost",
+    rpc: "http://127.0.0.1:8545",
+    chainId: 31337
+  }
+};
+var BASE_ENDPOINT = "https://x402-services.vercel.app";
+var ESCROW_ABI = [
+  "function createTx(string txId, address creator, uint256 amount) external payable"
+];
+var MUSD_ADDRESS = "0x4dABf45C8cF333Ef1e874c3FDFC3C86799af80c8";
+var ERC20_ABI = [
+  "function approve(address spender, uint256 amount) external returns (bool)"
+];
+var PaymentService = class {
+  wallet;
+  provider;
+  constructor(config) {
+    const networkKey = config.network || "mantle";
+    const networkConfig = NETWORKS[networkKey];
+    if (!networkConfig && !config.rpcUrl) {
+      throw new Error(`Invalid network: ${networkKey} and no RPC URL provided.`);
+    }
+    const rpcUrl = config.rpcUrl || networkConfig?.rpc;
+    this.provider = new ethers.JsonRpcProvider(rpcUrl);
+    try {
+      this.wallet = new ethers.Wallet(config.privateKey, this.provider);
+    } catch (error) {
+      throw new Error("Invalid private key provided.");
+    }
+  }
+  /**
+   * Performs a payment on-chain and retries the original request with proof of payment.
+   * 
+   * @param params.paymentData - The payment details (amount, recipient).
+   * @param params.retryRequest - A callback that performs the HTTP request. Must accept headers.
+   * @returns The response from the retried request.
+   */
+  async payAndRetry(params) {
+    const { paymentData, retryRequest } = params;
+    try {
+      if (!ethers.isAddress(paymentData.recipient)) {
+        throw new Error(`Invalid recipient address: ${paymentData.recipient}`);
+      }
+      const txRequest = {
+        to: paymentData.recipient,
+        value: BigInt(paymentData.amount)
+        // Gas limit/price will be estimated by provider/wallet
+      };
+      const txResponse = await this.wallet.sendTransaction(txRequest);
+      const receipt = await txResponse.wait(1);
+      if (!receipt || receipt.status !== 1) {
+        throw new Error("Transaction failed or was reverted on-chain.");
+      }
+      const txHash = receipt.hash;
+      const headers = {
+        "X-Payment-Tx": txHash,
+        "Content-Type": "application/json"
+        // Default content type, extendable if needed
+      };
+      return await retryRequest(headers);
+    } catch (error) {
+      const errorMessage = error instanceof Error ? error.message : "Unknown error occurred during payment flow";
+      throw new Error(`PaymentService Failed: ${errorMessage}`);
+    }
+  }
+  /**
+   * Get AI response
+   * 
+   * @param agentSlug
+   * @returns
+   */
+  async generateAIResponse(agentSlug, message) {
+    try {
+      const initialResponse = await fetch(`${BASE_ENDPOINT}/agent/${agentSlug}/chat`, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json"
+        },
+        body: JSON.stringify({
+          message
+        })
+      });
+      if (!initialResponse.ok && initialResponse.status !== 402) {
+        throw new Error(`Unexpected status code: ${initialResponse.status}`);
+      }
+      const paymentDetail = await initialResponse.json();
+      const txId = paymentDetail.transactionId;
+      const escrowAddress = paymentDetail.escrowAddress;
+      const amountPayment = paymentDetail.amountPayment;
+      const contractAddress = paymentDetail.contractAddress;
+      if (!contractAddress) {
+        throw new Error("Contract address not found in payment details.");
+      }
+      const musdContract = new ethers.Contract(MUSD_ADDRESS, ERC20_ABI, this.wallet);
+      const approveTx = await musdContract.approve(contractAddress, amountPayment);
+      await approveTx.wait(1);
+      const contract = new ethers.Contract(contractAddress, ESCROW_ABI, this.wallet);
+      const txResponse = await contract.createTx(
+        txId,
+        escrowAddress,
+        amountPayment
+      );
+      const receipt = await txResponse.wait(1);
+      if (!receipt || receipt.status !== 1) {
+        throw new Error("Escrow transaction failed.");
+      }
+      const finalTxHash = receipt.hash;
+      const headers = {
+        "x-payment-tx": finalTxHash,
+        "Content-Type": "application/json"
+      };
+      const retryResponse = await fetch(`${BASE_ENDPOINT}/agent/${agentSlug}/chat`, {
+        method: "POST",
+        headers,
+        body: JSON.stringify({
+          message
+        })
+      });
+      if (!retryResponse.ok) {
+        const errorText = await retryResponse.text();
+        throw new Error(`Retry failed: ${retryResponse.status} - ${errorText}`);
+      }
+      return await retryResponse.json();
+    } catch (error) {
+      const errorMessage = error instanceof Error ? error.message : "Unknown error occurred during payment flow";
+      throw new Error(`PaymentService Failed: ${errorMessage}`);
+    }
+  }
+  /**
+   * Get proxy endpoint
+   * 
+   * @param gatewaySlug 
+   * @returns 
+   */
+  async getProxyEndpoint(gatewaySlug) {
+    try {
+      const initialResponse = await fetch(`${BASE_ENDPOINT}/escrow/${gatewaySlug}`);
+      if (initialResponse.ok) {
+        return await initialResponse.json();
+      }
+      if (initialResponse.status !== 402) {
+        throw new Error(`Unexpected status code: ${initialResponse.status}`);
+      }
+      const paymentDetail = await initialResponse.json();
+      const txId = paymentDetail.transactionId;
+      const escrowAddress = paymentDetail.escrowAddress;
+      const amountPayment = paymentDetail.amountPayment;
+      const contractAddress = paymentDetail.contractAddress;
+      if (!contractAddress) {
+        throw new Error("Contract address not found in payment details.");
+      }
+      const musdContract = new ethers.Contract(MUSD_ADDRESS, ERC20_ABI, this.wallet);
+      const approveTx = await musdContract.approve(contractAddress, amountPayment);
+      await approveTx.wait(1);
+      const contract = new ethers.Contract(contractAddress, ESCROW_ABI, this.wallet);
+      const txResponse = await contract.createTx(
+        txId,
+        escrowAddress,
+        amountPayment
+      );
+      const receipt = await txResponse.wait(1);
+      if (!receipt || receipt.status !== 1) {
+        throw new Error("Escrow transaction failed.");
+      }
+      const finalTxHash = receipt.hash;
+      const headers = {
+        "x-payment-tx": finalTxHash,
+        "Content-Type": "application/json"
+      };
+      const retryResponse = await fetch(`${BASE_ENDPOINT}/${gatewaySlug}`, {
+        method: "GET",
+        headers
+      });
+      if (!retryResponse.ok) {
+        const errorText = await retryResponse.text();
+        throw new Error(`Retry failed: ${retryResponse.status} - ${errorText}`);
+      }
+      return await retryResponse.json();
+    } catch (error) {
+      const errorMessage = error instanceof Error ? error.message : "Unknown error in getProxyEndpoint";
+      throw new Error(`Proxy Endpoint Failed: ${errorMessage}`);
+    }
+  }
+  /**
+   * Helper to get the current wallet address
+   */
+  getAddress() {
+    return this.wallet.address;
+  }
+};
+export {
+  PaymentService
+};

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@payroute/x402-sdk",
+  "version": "1.0.0",
+  "description": "SDK for automation payment gateway with x402",
+  "main": "./dist/index.js",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "scripts": {
+    "build": "tsup"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/payroute-protocol/payroute-x402-sdk.git"
+  },
+  "keywords": [
+    "x402",
+    "payroute",
+    "payment",
+    "gateway",
+    "sdk"
+  ],
+  "author": "",
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/payroute-protocol/payroute-x402-sdk/issues"
+  },
+  "homepage": "https://github.com/payroute-protocol/payroute-x402-sdk#readme",
+  "devDependencies": {
+    "tsup": "^8.5.1",
+    "typescript": "^5.9.3",
+    "vitest": "^4.0.16"
+  },
+  "dependencies": {
+    "ethers": "^6.16.0"
+  }
+}