create-x402-app 0.1.2 → 0.1.4

package/templates/fullstack-express/README.md

@@ -0,0 +1,308 @@
+# x402 Starter Template
+
+A production-ready Next.js boilerplate for building **pay-per-request APIs** using the HTTP 402 protocol on Mantle Network.
+
+## What is x402?
+
+x402 implements the [HTTP 402 Payment Required](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/402) status code to enable native payments for API access. When a client requests a paid endpoint without payment, the server returns a 402 response with payment details. After payment, the client retries with the transaction hash to access the content.
+
+## Quick Start
+
+### 1. Clone and Install
+
+```bash
+git clone https://github.com/your-repo/x402-starter.git
+cd x402-starter
+npm install
+```
+
+### 2. Get Your App ID
+
+1. Visit the [x402 Dashboard](https://mantle-x402.vercel.app) or [Documentation](https://mantle-x402.vercel.app/dashboard?tab=docs)
+2. Connect your wallet
+3. Create a new project
+4. Copy your **App ID**
+
+### 3. Configure Environment
+
+```bash
+cp .env.example .env
+```
+
+Edit `.env`:
+
+```env
+X402_APP_ID=your_app_id_here
+X402_PLATFORM_URL=https://mantle-x402.vercel.app
+```
+
+### 4. Run Development Server
+
+```bash
+npm run dev
+```
+
+Open [http://localhost:3000](http://localhost:3000)
+
+## Project Structure
+
+```
+x402-starter/
+├── src/
+│   ├── app/
+│   │   ├── api/
+│   │   │   ├── info/route.ts       # Free endpoint (no payment)
+│   │   │   ├── premium/route.ts    # Paid endpoint (0.001 MNT)
+│   │   │   └── weather/route.ts    # Paid endpoint (0.0005 MNT)
+│   │   ├── page.tsx                # Demo frontend
+│   │   └── layout.tsx              # Root layout
+│   ├── components/                 # UI components
+│   └── lib/                        # Utilities
+├── .env.example                    # Environment template
+└── package.json
+```
+
+## API Endpoints
+
+| Endpoint | Price | Description |
+|----------|-------|-------------|
+| `GET /api/info` | Free | API information |
+| `GET /api/premium` | 0.001 MNT | Premium content |
+| `GET /api/weather` | 0.0005 MNT | Weather data |
+
+## Creating Paid Endpoints
+
+### Basic Example
+
+```typescript
+// src/app/api/my-endpoint/route.ts
+import { NextRequest, NextResponse } from 'next/server'
+import { processPaymentMiddleware, initializePlatform } from 'x402-mantle-sdk/server'
+
+let initialized = false
+
+export async function GET(request: NextRequest) {
+  // Initialize once
+  if (!initialized) {
+    await initializePlatform()
+    initialized = true
+  }
+
+  // Convert headers
+  const headers: Record<string, string> = {}
+  request.headers.forEach((value, key) => {
+    headers[key] = value
+  })
+
+  // Check payment
+  const result = await processPaymentMiddleware(
+    { price: '0.01', token: 'MNT', testnet: true },
+    headers
+  )
+
+  // Return 402 if payment required
+  if (result.paymentRequired) {
+    const response = NextResponse.json(result.paymentRequired.body, { status: 402 })
+    Object.entries(result.paymentRequired.headers).forEach(([key, value]) => {
+      response.headers.set(key, value)
+    })
+    return response
+  }
+
+  // Return content if payment verified
+  if (result.allowed) {
+    return NextResponse.json({
+      success: true,
+      data: 'Your premium content here'
+    })
+  }
+
+  return NextResponse.json({ error: 'Error' }, { status: 500 })
+}
+```
+
+### Payment Options
+
+```typescript
+const options = {
+  price: '0.001',           // Amount to charge
+  token: 'MNT',             // Token (MNT, USDC, USDT)
+  testnet: true,            // Use Mantle Sepolia (false for mainnet)
+  network: 'mantle-sepolia' // Or 'mantle' for mainnet
+}
+```
+
+## Client-Side Integration
+
+### Using the PaymentModal Component
+
+```tsx
+import { PaymentModal } from 'x402-mantle-sdk/client/react'
+
+function MyComponent() {
+  const [showModal, setShowModal] = useState(false)
+  const [paymentRequest, setPaymentRequest] = useState(null)
+
+  const fetchPaidEndpoint = async () => {
+    const res = await fetch('/api/premium')
+
+    if (res.status === 402) {
+      // Extract payment details from response
+      const body = await res.json()
+      setPaymentRequest({
+        amount: body.amount,
+        token: body.token,
+        network: body.network,
+        recipient: body.recipient,
+        chainId: body.chainId,
+      })
+      setShowModal(true)
+    }
+  }
+
+  const handlePaymentComplete = async (payment) => {
+    // Retry with transaction hash
+    const res = await fetch('/api/premium', {
+      headers: {
+        'X-402-Transaction-Hash': payment.transactionHash
+      }
+    })
+    const data = await res.json()
+    console.log('Premium data:', data)
+  }
+
+  return (
+    <>
+      <button onClick={fetchPaidEndpoint}>Get Premium Data</button>
+
+      {paymentRequest && (
+        <PaymentModal
+          request={paymentRequest}
+          isOpen={showModal}
+          onComplete={handlePaymentComplete}
+          onCancel={() => setShowModal(false)}
+        />
+      )}
+    </>
+  )
+}
+```
+
+### Using x402Fetch (Auto-handles payments)
+
+```typescript
+import { x402Fetch } from 'x402-mantle-sdk/client'
+
+// Automatically shows payment modal when 402 is returned
+const response = await x402Fetch('/api/premium')
+const data = await response.json()
+```
+
+## HTTP 402 Protocol
+
+### Request Flow
+
+```
+1. Client requests paid endpoint
+   GET /api/premium
+
+2. Server returns 402 with payment details
+   HTTP/1.1 402 Payment Required
+   X-402-Amount: 0.001
+   X-402-Token: MNT
+   X-402-Network: mantle-sepolia
+   X-402-Recipient: 0x...
+
+3. Client makes payment on-chain
+
+4. Client retries with transaction hash
+   GET /api/premium
+   X-402-Transaction-Hash: 0x...
+
+5. Server verifies payment and returns content
+   HTTP/1.1 200 OK
+   { "data": "Premium content" }
+```
+
+## Supported Networks
+
+| Network | Chain ID | Environment |
+|---------|----------|-------------|
+| Mantle | 5000 | Production |
+| Mantle Sepolia | 5003 | Testnet |
+
+## Supported Tokens
+
+| Token | Mainnet | Testnet |
+|-------|---------|---------|
+| MNT | Native | Native |
+| USDC | 0x09Bc4E... | 0x09Bc4E... |
+| USDT | 0x201EBa... | - |
+
+## Testing
+
+1. Install [MetaMask](https://metamask.io/)
+2. Add Mantle Sepolia network:
+   - RPC: `https://rpc.sepolia.mantle.xyz`
+   - Chain ID: `5003`
+   - Symbol: `MNT`
+3. Get test MNT from [Mantle Faucet](https://faucet.sepolia.mantle.xyz/)
+4. Connect wallet and try paid endpoints
+
+## Deployment
+
+### Vercel (Recommended)
+
+```bash
+npm run build
+vercel deploy
+```
+
+Set environment variables in Vercel dashboard:
+- `X402_APP_ID`
+- `X402_PLATFORM_URL`
+
+### Other Platforms
+
+Works with any Node.js hosting:
+- Railway
+- Render
+- AWS Lambda
+- Google Cloud Run
+
+## Configuration
+
+### Environment Variables
+
+| Variable | Required | Description |
+|----------|----------|-------------|
+| `X402_APP_ID` | Yes | Your project App ID from the dashboard |
+| `X402_PLATFORM_URL` | Yes | Platform URL (default: https://mantle-x402.vercel.app) |
+
+## Troubleshooting
+
+### "X402_APP_ID is required"
+
+Make sure your `.env` file exists and contains a valid App ID.
+
+### Payment not verifying
+
+1. Wait for transaction confirmation (~3 seconds)
+2. Check that the transaction was successful on block explorer
+3. Ensure the amount matches exactly
+
+### Network mismatch
+
+Make sure your wallet is on the same network as configured in the endpoint (testnet vs mainnet).
+
+## Resources
+
+- [x402 Documentation](https://mantle-x402.vercel.app/dashboard?tab=docs)
+- [x402 Dashboard](https://mantle-x402.vercel.app)
+- [x402-mantle-sdk on npm](https://www.npmjs.com/package/x402-mantle-sdk)
+- [Mantle Network](https://www.mantle.xyz/)
+- [Mantle Faucet](https://faucet.sepolia.mantle.xyz/)
+
+## License
+
+MIT

package/templates/fullstack-express/_env.example

@@ -0,0 +1,11 @@
+# x402 Configuration
+# Get your App ID from: https://mantle-x402.vercel.app
+#
+# Steps:
+# 1. Visit the dashboard URL above
+# 2. Connect your wallet
+# 3. Create a new project
+# 4. Copy your App ID and paste it below
+
+X402_APP_ID=your_app_id_here
+X402_PLATFORM_URL=https://mantle-x402.vercel.app

package/templates/fullstack-express/_gitignore

@@ -0,0 +1,46 @@
+# See https://help.github.com/articles/ignoring-files/ for more about ignoring files.
+
+# dependencies
+/node_modules
+/.pnp
+.pnp.*
+.yarn/*
+!.yarn/patches
+!.yarn/plugins
+!.yarn/releases
+!.yarn/versions
+
+# testing
+/coverage
+
+# next.js
+/.next/
+/out/
+
+# production
+/build
+
+# misc
+.DS_Store
+*.pem
+
+# debug
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+.pnpm-debug.log*
+
+# env files
+.env
+.env.local
+.env.*.local
+
+# keep example
+!.env.example
+
+# vercel
+.vercel
+
+# typescript
+*.tsbuildinfo
+next-env.d.ts

package/templates/fullstack-express/eslint.config.mjs

@@ -0,0 +1,18 @@
+import { defineConfig, globalIgnores } from "eslint/config";
+import nextVitals from "eslint-config-next/core-web-vitals";
+import nextTs from "eslint-config-next/typescript";
+
+const eslintConfig = defineConfig([
+  ...nextVitals,
+  ...nextTs,
+  // Override default ignores of eslint-config-next.
+  globalIgnores([
+    // Default ignores of eslint-config-next:
+    ".next/**",
+    "out/**",
+    "build/**",
+    "next-env.d.ts",
+  ]),
+]);
+
+export default eslintConfig;

package/templates/fullstack-express/next-env.d.ts

@@ -0,0 +1,6 @@
+/// <reference types="next" />
+/// <reference types="next/image-types/global" />
+import "./.next/dev/types/routes.d.ts";
+
+// NOTE: This file should not be edited
+// see https://nextjs.org/docs/app/api-reference/config/typescript for more information.

package/templates/fullstack-express/next.config.ts

@@ -0,0 +1,7 @@
+import type { NextConfig } from "next";
+
+const nextConfig: NextConfig = {
+  /* config options here */
+};
+
+export default nextConfig;

package/templates/fullstack-express/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "x402-starter",
+  "version": "1.0.0",
+  "description": "A Next.js starter template for building pay-per-request APIs with x402 on Mantle Network",
+  "private": true,
+  "scripts": {
+    "dev": "next dev",
+    "build": "next build",
+    "start": "next start",
+    "lint": "eslint"
+  },
+  "dependencies": {
+    "clsx": "^2.1.1",
+    "ethers": "^6.16.0",
+    "motion": "^12.23.26",
+    "next": "16.1.0",
+    "react": "19.2.3",
+    "react-dom": "19.2.3",
+    "tailwind-merge": "^3.4.0",
+    "tw-animate-css": "^1.4.0",
+    "x402-mantle-sdk": "^0.2.3"
+  },
+  "devDependencies": {
+    "@tailwindcss/postcss": "^4",
+    "@types/node": "^20",
+    "@types/react": "^19",
+    "@types/react-dom": "^19",
+    "eslint": "^9",
+    "eslint-config-next": "16.1.0",
+    "tailwindcss": "^4",
+    "typescript": "^5"
+  }
+}

package/templates/fullstack-express/postcss.config.mjs

@@ -0,0 +1,7 @@
+const config = {
+  plugins: {
+    "@tailwindcss/postcss": {},
+  },
+};
+
+export default config;

package/templates/fullstack-express/src/app/api/info/route.ts

@@ -0,0 +1,14 @@
+import { NextResponse } from 'next/server'
+
+export async function GET() {
+  return NextResponse.json({
+    message: 'Welcome to x402 API',
+    endpoints: {
+      free: 'GET /api/info',
+      paid: 'GET /api/premium (0.001 MNT)',
+      paidWeather: 'GET /api/weather (0.0005 MNT)',
+    },
+    network: 'mantle-sepolia',
+    documentation: 'https://mantle-x402.vercel.app',
+  })
+}

package/templates/fullstack-express/src/app/api/premium/route.ts

@@ -0,0 +1,52 @@
+import { NextRequest, NextResponse } from 'next/server'
+import { processPaymentMiddleware, initializePlatform } from 'x402-mantle-sdk/server'
+
+let initialized = false
+
+export async function GET(request: NextRequest) {
+  // Initialize platform once
+  if (!initialized) {
+    await initializePlatform()
+    initialized = true
+  }
+
+  // Convert headers to plain object
+  const headers: Record<string, string> = {}
+  request.headers.forEach((value, key) => {
+    headers[key] = value
+  })
+
+  // Process payment - returns 402 if payment required
+  const result = await processPaymentMiddleware(
+    { price: '0.001', token: 'MNT', testnet: true },
+    headers
+  )
+
+  // Payment required - return 402 with payment details
+  if (result.paymentRequired) {
+    const response = NextResponse.json(result.paymentRequired.body, { status: 402 })
+    Object.entries(result.paymentRequired.headers).forEach(([key, value]) => {
+      response.headers.set(key, value)
+    })
+    return response
+  }
+
+  // Payment verified - return premium content
+  if (result.allowed) {
+    return NextResponse.json({
+      success: true,
+      message: 'Premium content unlocked!',
+      data: {
+        secret: 'This is premium data that required payment.',
+        timestamp: new Date().toISOString(),
+      },
+    })
+  }
+
+  // Error handling
+  if (result.error) {
+    return NextResponse.json({ error: result.error.message }, { status: result.error.status })
+  }
+
+  return NextResponse.json({ error: 'Unexpected error' }, { status: 500 })
+}

package/templates/fullstack-express/src/app/api/weather/route.ts

@@ -0,0 +1,103 @@
+import { NextRequest, NextResponse } from 'next/server'
+import { processPaymentMiddleware, initializePlatform, clearCache } from 'x402-mantle-sdk/server'
+
+// Configuration - Set these in your .env file
+const appId = process.env.X402_APP_ID || ''
+const platformUrl = process.env.X402_PLATFORM_URL || 'https://mantle-x402.vercel.app'
+
+if (!process.env.X402_APP_ID) {
+  process.env.X402_APP_ID = appId
+}
+if (!process.env.X402_PLATFORM_URL) {
+  process.env.X402_PLATFORM_URL = platformUrl
+}
+
+let initialized = false
+let initError: Error | null = null
+
+const initPlatform = async () => {
+  try {
+    await initializePlatform()
+    initialized = true
+    initError = null
+  } catch (error) {
+    initError = error as Error
+    console.error('Platform initialization failed:', error)
+  }
+}
+
+export async function GET(request: NextRequest) {
+  try {
+    // Initialize platform on first request
+    if (!initialized && !initError) {
+      await initPlatform()
+    } else if (initError) {
+      try { clearCache() } catch {}
+      initError = null
+      await initPlatform()
+    }
+
+    if (initError) {
+      return NextResponse.json(
+        { error: 'Platform initialization failed', details: (initError as Error).message },
+        { status: 500 }
+      )
+    }
+
+    // Payment options - cheaper for weather
+    const paymentOptions = {
+      price: '0.0005',
+      token: 'MNT',
+      testnet: true,
+    }
+
+    // Convert headers
+    const headers: Record<string, string> = {}
+    request.headers.forEach((value, key) => {
+      headers[key] = value
+    })
+
+    // Process payment middleware
+    const result = await processPaymentMiddleware(paymentOptions, headers)
+
+    // Payment required - return 402
+    if (result.paymentRequired) {
+      const response = NextResponse.json(result.paymentRequired.body, { status: 402 })
+      Object.entries(result.paymentRequired.headers).forEach(([key, value]) => {
+        response.headers.set(key, value)
+      })
+      return response
+    }
+
+    // Error
+    if (result.error) {
+      return NextResponse.json(
+        { error: result.error.message },
+        { status: result.error.status }
+      )
+    }
+
+    // Payment verified - return weather data
+    if (result.allowed) {
+      return NextResponse.json({
+        success: true,
+        data: {
+          location: 'New York',
+          temperature: 72,
+          unit: 'F',
+          condition: 'Sunny',
+          humidity: 45,
+          forecast: ['Sunny', 'Partly Cloudy', 'Rain'],
+        },
+      })
+    }
+
+    return NextResponse.json({ error: 'Unexpected error' }, { status: 500 })
+  } catch (error) {
+    console.error('Error in weather route:', error)
+    return NextResponse.json(
+      { error: 'Internal server error', message: error instanceof Error ? error.message : 'Unknown error' },
+      { status: 500 }
+    )
+  }
+}

package/templates/fullstack-express/src/app/globals.css

@@ -0,0 +1,82 @@
+@import "tailwindcss";
+@import "tw-animate-css";
+
+@custom-variant dark (&:is(.dark *));
+
+:root {
+  /* Light blue background with dark blue text palette */
+  --background: oklch(0.95 0.05 240); /* Light blue background */
+  --foreground: oklch(0.25 0.12 240); /* Dark blue (navy) text */
+  --card: oklch(0.92 0.04 240); /* Slightly darker light blue */
+  --card-foreground: oklch(0.25 0.12 240); /* Dark blue */
+  --popover: oklch(0.92 0.04 240);
+  --popover-foreground: oklch(0.25 0.12 240);
+  --primary: oklch(0.35 0.15 240); /* Medium dark blue */
+  --primary-foreground: oklch(0.95 0.05 240); /* Light blue */
+  --secondary: oklch(0.88 0.04 240); /* Light blue gray */
+  --secondary-foreground: oklch(0.25 0.12 240); /* Dark blue */
+  --muted: oklch(0.85 0.03 240);
+  --muted-foreground: oklch(0.4 0.1 240);
+  --accent: oklch(0.3 0.13 240); /* Dark blue accent */
+  --accent-foreground: oklch(0.95 0.05 240); /* Light blue */
+  --destructive: oklch(0.577 0.245 27.325);
+  --destructive-foreground: oklch(0.95 0.05 240);
+  --border: oklch(0.8 0.05 240); /* Light blue border */
+  --input: oklch(0.8 0.05 240);
+  --ring: oklch(0.35 0.15 240); /* Dark blue ring */
+  --radius: 0.75rem;
+}
+
+@theme inline {
+  --font-sans: "Geist", "Geist Fallback", system-ui, sans-serif;
+  --font-mono: "Geist Mono", "Geist Mono Fallback", monospace;
+  --color-background: var(--background);
+  --color-foreground: var(--foreground);
+  --color-card: var(--card);
+  --color-card-foreground: var(--card-foreground);
+  --color-popover: var(--popover);
+  --color-popover-foreground: var(--popover-foreground);
+  --color-primary: var(--primary);
+  --color-primary-foreground: var(--primary-foreground);
+  --color-secondary: var(--secondary);
+  --color-secondary-foreground: var(--secondary-foreground);
+  --color-muted: var(--muted);
+  --color-muted-foreground: var(--muted-foreground);
+  --color-accent: var(--accent);
+  --color-accent-foreground: var(--accent-foreground);
+  --color-destructive: var(--destructive);
+  --color-destructive-foreground: var(--destructive-foreground);
+  --color-border: var(--border);
+  --color-input: var(--input);
+  --color-ring: var(--ring);
+  --radius-sm: calc(var(--radius) - 4px);
+  --radius-md: calc(var(--radius) - 2px);
+  --radius-lg: var(--radius);
+  --radius-xl: calc(var(--radius) + 4px);
+}
+
+@layer base {
+  * {
+    @apply border-border outline-ring/50;
+    cursor: default;
+  }
+  body {
+    @apply bg-background text-foreground;
+  }
+
+  main {
+    /* Light blue textured background */
+    background-color: oklch(0.95 0.05 240);
+    background-image:
+      url("data:image/svg+xml,%3Csvg viewBox='0 0 400 400' xmlns='http://www.w3.org/2000/svg'%3E%3Cfilter id='noiseFilter'%3E%3CfeTurbulence type='fractalNoise' baseFrequency='0.9' numOctaves='4' stitchTiles='stitch'/%3E%3CfeColorMatrix type='saturate' values='0'/%3E%3C/filter%3E%3Crect width='100%25' height='100%25' filter='url(%23noiseFilter)' opacity='0.4' fill='%23e0f2fe'/%3E%3C/svg%3E");
+    background-size: 200px 200px;
+    background-repeat: repeat;
+  }
+
+  button,
+  a {
+    cursor: pointer;
+    transform: translateZ(0);
+    backface-visibility: hidden;
+  }
+}