x402-mantle-sdk 0.1.0 → 0.2.1

package/README.md

@@ -1,16 +1,37 @@
 # @x402-devkit/sdk
 
-Complete SDK for x402 paid APIs on Mantle Network. Monetize your APIs with HTTP 402 payments.
+> Complete SDK for monetizing APIs with HTTP 402 payments on Mantle Network
 
-## Installation
+[![npm version](https://img.shields.io/npm/v/@x402-devkit/sdk)](https://www.npmjs.com/package/@x402-devkit/sdk)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Mantle Network](https://img.shields.io/badge/Network-Mantle-blue)](https://mantle.xyz)
+
+**@x402-devkit/sdk** enables developers to monetize APIs using HTTP 402 Payment Required status code with blockchain payments on Mantle Network. Protect your API routes, handle payments automatically, and track revenue—all with a few lines of code.
+
+## ✨ Features
+
+- 🚀 **Zero-Configuration Setup** - Get started in minutes
+- 💰 **Automatic Payment Handling** - Seamless wallet integration
+- 📊 **Real-Time Analytics** - Track endpoint usage and revenue
+- 🔒 **Blockchain Verification** - On-chain payment validation
+- 🎨 **Beautiful UI Components** - Ready-to-use React payment modals
+- 🌐 **Multi-Token Support** - MNT, USDC, USDT, mETH, WMNT
+- ⚡ **Ultra-Low Fees** - Gas costs under $0.001 on Mantle
+- 🔄 **Auto Endpoint Tracking** - Endpoints appear in dashboard automatically
+
+## 📦 Installation
 
 ```bash
 npm install @x402-devkit/sdk
 ```
 
-## Quick Start
+## 🚀 Quick Start
+
+### 1. Create a Project
+
+Visit the [x402 Dashboard](https://mantle-x402.vercel.app/dashboard) to create a project and get your `X402_APP_ID`.
 
-### Server - Protect API Routes
+### 2. Protect Your API Routes
 
 ```typescript
 import { Hono } from 'hono'
@@ -18,7 +39,10 @@ import { x402 } from '@x402-devkit/sdk/server'
 
 const app = new Hono()
 
-// Protect route with payment (0.001 MNT)
+// Set your project ID
+process.env.X402_APP_ID = 'your-app-id-here'
+
+// Protect any route with payment
 app.use('/api/premium', x402({
   price: '0.001',
   token: 'MNT',
@@ -26,11 +50,11 @@ app.use('/api/premium', x402({
 }))
 
 app.get('/api/premium', (c) => {
-  return c.json({ data: 'Premium content' })
+  return c.json({ data: 'Premium content unlocked!' })
 })
 ```
 
-### Client - Handle Payments
+### 3. Handle Payments on Client
 
 ```typescript
 import { x402Fetch } from '@x402-devkit/sdk/client'
@@ -40,7 +64,76 @@ const response = await x402Fetch('https://api.example.com/api/premium')
 const data = await response.json()
 ```
 
-### React - Payment Modal Component
+**That's it!** Your API now accepts blockchain payments. 🎉
+
+## 📖 Documentation
+
+### Server Usage
+
+#### Basic Middleware
+
+```typescript
+import { x402 } from '@x402-devkit/sdk/server'
+
+app.use('/api/data', x402({
+  price: '0.001',
+  token: 'MNT',
+  network: 'mantle'  // or 'mantle-sepolia' for testnet
+}))
+```
+
+#### Advanced Options
+
+```typescript
+app.use('/api/premium', x402({
+  price: '0.001',
+  token: 'USDC',
+  network: 'mantle',
+  endpoint: '/api/premium',  // For dashboard tracking
+  method: 'GET',              // For dashboard tracking
+  enableAnalytics: true       // Auto-track payments (default: true)
+}))
+```
+
+#### Environment Variables
+
+```env
+# Required
+X402_APP_ID=your-project-app-id
+
+# Optional
+X402_PLATFORM_URL=https://mantle-x402.vercel.app
+```
+
+### Client Usage
+
+#### Automatic Payment Handling
+
+```typescript
+import { x402Fetch } from '@x402-devkit/sdk/client'
+
+// Automatically intercepts 402 responses and shows payment modal
+const response = await x402Fetch('https://api.example.com/api/premium')
+const data = await response.json()
+```
+
+#### Custom Client Configuration
+
+```typescript
+import { x402Client } from '@x402-devkit/sdk/client'
+
+const client = x402Client({
+  autoRetry: true,
+  autoSwitchNetwork: true,
+  testnet: false
+})
+
+const response = await client.fetch('https://api.example.com/api/premium')
+```
+
+### React Components
+
+#### Basic Payment Modal
 
 ```tsx
 import { PaymentModal } from '@x402-devkit/sdk/client/react'
@@ -54,7 +147,7 @@ function App() {
       request={request}
       isOpen={isOpen}
       onComplete={(payment) => {
-        console.log('Paid:', payment.transactionHash)
+        console.log('Payment successful:', payment.transactionHash)
         setIsOpen(false)
       }}
       onCancel={() => setIsOpen(false)}
@@ -63,41 +156,89 @@ function App() {
 }
 ```
 
-## Features
+#### Enhanced Payment Modal
 
-- **Server Middleware**: Hono middleware for payment-gated routes
-- **Client SDK**: Automatic 402 handling with wallet integration
-- **React Components**: Ready-to-use payment modal
-- **Mantle Network**: Native support for Mantle mainnet and testnet
-- **Multiple Tokens**: Support for MNT, USDC, USDT, mETH, WMNT
-- **Custom Networks**: Register custom networks and tokens
-- **0.5% Platform Fee**: Automatic fee splitting to Treasury
+```tsx
+import { EnhancedPaymentModal } from '@x402-devkit/sdk/client/react'
 
-## Environment Variables
+function App() {
+  const [isOpen, setIsOpen] = useState(false)
+  const [request, setRequest] = useState({
+    amount: '0.001',
+    token: 'MNT',
+    network: 'mantle',
+    recipient: '0x...',
+    description: 'Premium API access',
+    endpoint: '/api/premium-data'
+  })
 
-### Server
-```env
-X402_APP_ID=your-app-id
-X402_PLATFORM_URL=https://api.x402.dev  # Optional
+  return (
+    <EnhancedPaymentModal
+      request={request}
+      isOpen={isOpen}
+      onComplete={(payment) => {
+        console.log('Paid:', payment.transactionHash)
+        setIsOpen(false)
+      }}
+      onCancel={() => setIsOpen(false)}
+      description="Premium API access"
+      endpoint="/api/premium-data"
+      simulation={false}  // Set to true for testing
+    />
+  )
+}
 ```
 
-## Networks
+## 🌐 Supported Networks
+
+| Network | Chain ID | Status | Tokens |
+|---------|----------|--------|--------|
+| Mantle Mainnet | 5000 | ✅ Production | MNT, USDC, USDT, mETH, WMNT |
+| Mantle Sepolia | 5003 | ✅ Testnet | MNT, USDC, mETH, WMNT |
+
+## 💡 Use Cases
 
-| Network | Chain ID | Token |
-|---------|----------|-------|
-| Mantle Mainnet | 5000 | MNT |
-| Mantle Sepolia | 5003 | MNT |
+- **AI & LLM APIs** - Charge per token, per request, or per compute second
+- **Data APIs** - Monetize datasets, market data, or proprietary information
+- **Compute APIs** - Image processing, video transcoding, ML inference
+- **Premium Content** - Articles, research, analysis with micropayments
+- **IoT & Sensors** - Sell real-time sensor data with pay-per-read
 
-## API Reference
+## 📊 Dashboard & Analytics
+
+All endpoints are automatically tracked in the [x402 Dashboard](https://mantle-x402.vercel.app/dashboard):
+
+- **Automatic Endpoint Discovery** - Endpoints appear when first accessed
+- **Real-Time Payment Tracking** - See payments as they happen
+- **Revenue Analytics** - Track earnings per endpoint
+- **Usage Statistics** - Monitor API usage patterns
+
+## 🔧 API Reference
 
 ### Server Exports
 
 ```typescript
 import {
-  x402,                    // Main middleware
-  verifyPayment,           // Manual payment verification
-  getNetworkConfig,        // Get network configuration
-  registerCustomNetwork,   // Register custom network
+  // Main middleware
+  x402,
+  
+  // Payment verification
+  verifyPayment,
+  verifyPaymentOnChain,
+  
+  // Network utilities
+  getNetworkConfig,
+  getTokenConfig,
+  registerCustomNetwork,
+  registerCustomTokens,
+  
+  // Analytics
+  logPayment,
+  registerEndpoint,
+  
+  // Platform
+  initializePlatform,
+  getProjectConfig,
 } from '@x402-devkit/sdk/server'
 ```
 
@@ -105,26 +246,80 @@ import {
 
 ```typescript
 import {
-  x402Fetch,               // Enhanced fetch with 402 handling
-  x402Client,              // Client factory
-  connectWallet,           // Connect wallet
-  processPayment,          // Process payment manually
-  TREASURY_ADDRESS,        // Treasury contract address
+  // Fetch with 402 handling
+  x402Fetch,
+  x402Client,
+  
+  // Wallet utilities
+  connectWallet,
+  detectWalletProvider,
+  ensureNetwork,
+  
+  // Payment processing
+  processPayment,
+  
+  // Constants
+  TREASURY_ADDRESS,
+  PLATFORM_FEE_BPS,
 } from '@x402-devkit/sdk/client'
 ```
 
 ### React Exports
 
 ```typescript
-import { PaymentModal } from '@x402-devkit/sdk/client/react'
+import {
+  PaymentModal,          // Basic payment modal
+  EnhancedPaymentModal,  // Enhanced modal with success states
+} from '@x402-devkit/sdk/client/react'
 ```
 
-## Treasury
+## 🏗️ Architecture
+
+```
+@x402-devkit/sdk
+├── /server          # Server middleware (Hono, Express-compatible)
+├── /client          # Client SDK (fetch, wallet integration)
+└── /client/react    # React components (payment modals)
+```
+
+## 🔐 Security
+
+- **On-Chain Verification** - All payments verified on blockchain
+- **No Private Keys** - Wallet-based payments only
+- **Idempotent Payments** - Duplicate transaction protection
+- **Amount Tolerance** - Handles minor blockchain rounding
+
+## 💰 Pricing & Fees
+
+- **Platform Fee**: 0.5% (automatically split to Treasury)
+- **Gas Costs**: < $0.001 per transaction on Mantle
+- **No Hidden Fees**: Transparent fee structure
+
+## 🤝 Contributing
+
+Contributions are welcome! Please read our contributing guidelines first.
+
+## 📄 License
+
+MIT License - see [LICENSE](LICENSE) file for details.
+
+## 🔗 Links
+
+- **Dashboard**: [https://mantle-x402.vercel.app](https://mantle-x402.vercel.app)
+- **Documentation**: [https://mantle-x402.vercel.app/dashboard?tab=docs](https://mantle-x402.vercel.app/dashboard?tab=docs)
+- **GitHub**: [https://github.com/x402-devkit/x402](https://github.com/x402-devkit/x402)
+- **Mantle Network**: [https://mantle.xyz](https://mantle.xyz)
+
+## 🆘 Support
+
+- **Issues**: [GitHub Issues](https://github.com/x402-devkit/x402/issues)
+- **Discord**: [Join our community](https://discord.gg/x402)
+- **Email**: support@x402.dev
+
+## 🙏 Acknowledgments
 
-Platform fee (0.5%) is automatically sent to the Treasury contract:
-- **Address**: `0xB27705342ACE73736AE490540Ea031cc06C3eF49`
-- **Network**: Mantle Sepolia
+Built for [Mantle Network](https://mantle.xyz) - the fastest and cheapest Layer 2 for Ethereum.
 
-## License
+---
 
-MIT
+**Made with ❤️ for the Mantle ecosystem**

package/dist/client/index.cjs

@@ -293,11 +293,33 @@ var MetaMaskProvider = class {
     if (!this.ethereum) {
       throw new Error("MetaMask is not available");
     }
-    const txHash = await this.ethereum.request({
-      method: "eth_sendTransaction",
-      params: [tx]
-    });
-    return txHash;
+    const account = await this.getAccount();
+    if (!account) {
+      throw new Error("No account connected. Please connect your wallet first.");
+    }
+    const txWithFrom = {
+      ...tx,
+      from: account
+    };
+    try {
+      const txHash = await this.ethereum.request({
+        method: "eth_sendTransaction",
+        params: [txWithFrom]
+      });
+      return txHash;
+    } catch (error) {
+      if (error.code === 4001) {
+        throw new Error("Transaction rejected by user");
+      } else if (error.code === -32602) {
+        throw new Error("Invalid transaction parameters");
+      } else if (error.message?.includes("insufficient funds") || error.message?.includes("insufficient balance")) {
+        throw new Error("Insufficient funds for this transaction");
+      } else if (error.message) {
+        throw new Error(error.message);
+      } else {
+        throw new Error(`Transaction failed: ${error.code || "Unknown error"}`);
+      }
+    }
   }
   async signMessage(message) {
     if (!this.ethereum) {
@@ -384,9 +406,15 @@ function encodeERC20Transfer(to, amount) {
   return ERC20_TRANSFER_SIG + toHex + amountHex;
 }
 async function processPayment(request, wallet) {
+  if (!request.amount || !request.recipient || !request.network) {
+    throw new Error("Invalid payment request: missing required fields");
+  }
   const tokenConfig = getTokenConfig(request.token, request.network);
   const decimals = tokenConfig?.decimals ?? 18;
   const totalAmount = amountToWei(request.amount, decimals);
+  if (totalAmount === 0n) {
+    throw new Error("Invalid payment amount: amount must be greater than 0");
+  }
   const { merchantAmount, feeAmount } = calculateSplit(totalAmount);
   let txHash;
   if (tokenConfig) {
@@ -397,17 +425,21 @@ async function processPayment(request, wallet) {
     };
     txHash = await wallet.sendTransaction(tx);
   } else {
+    const merchantValue = merchantAmount.toString(16);
     const merchantTx = {
       to: request.recipient,
-      value: `0x${merchantAmount.toString(16)}`
+      value: `0x${merchantValue}`
     };
     txHash = await wallet.sendTransaction(merchantTx);
     if (feeAmount > 0n) {
+      const feeValue = feeAmount.toString(16);
       const feeTx = {
         to: TREASURY_ADDRESS,
-        value: `0x${feeAmount.toString(16)}`
+        value: `0x${feeValue}`
       };
-      await wallet.sendTransaction(feeTx);
+      wallet.sendTransaction(feeTx).catch((err) => {
+        console.warn("Fee transaction failed (non-critical):", err);
+      });
     }
   }
   return {