create-x402-app 0.1.2 → 0.1.3

package/templates/fullstack-express/src/components/ui/blur-fade.tsx

@@ -0,0 +1,81 @@
+"use client"
+
+import { useRef } from "react"
+import {
+  AnimatePresence,
+  motion,
+  MotionProps,
+  useInView,
+  UseInViewOptions,
+  Variants,
+} from "motion/react"
+
+type MarginType = UseInViewOptions["margin"]
+
+interface BlurFadeProps extends MotionProps {
+  children: React.ReactNode
+  className?: string
+  variant?: {
+    hidden: { y: number }
+    visible: { y: number }
+  }
+  duration?: number
+  delay?: number
+  offset?: number
+  direction?: "up" | "down" | "left" | "right"
+  inView?: boolean
+  inViewMargin?: MarginType
+  blur?: string
+}
+
+export function BlurFade({
+  children,
+  className,
+  variant,
+  duration = 0.4,
+  delay = 0,
+  offset = 6,
+  direction = "down",
+  inView = false,
+  inViewMargin = "-50px",
+  blur = "6px",
+  ...props
+}: BlurFadeProps) {
+  const ref = useRef(null)
+  const inViewResult = useInView(ref, { once: true, margin: inViewMargin })
+  const isInView = !inView || inViewResult
+  const defaultVariants: Variants = {
+    hidden: {
+      [direction === "left" || direction === "right" ? "x" : "y"]:
+        direction === "right" || direction === "down" ? -offset : offset,
+      opacity: 0,
+      filter: `blur(${blur})`,
+    },
+    visible: {
+      [direction === "left" || direction === "right" ? "x" : "y"]: 0,
+      opacity: 1,
+      filter: `blur(0px)`,
+    },
+  }
+  const combinedVariants = variant || defaultVariants
+  return (
+    <AnimatePresence>
+      <motion.div
+        ref={ref}
+        initial="hidden"
+        animate={isInView ? "visible" : "hidden"}
+        exit="hidden"
+        variants={combinedVariants}
+        transition={{
+          delay: 0.04 + delay,
+          duration,
+          ease: "easeOut",
+        }}
+        className={className}
+        {...props}
+      >
+        {children}
+      </motion.div>
+    </AnimatePresence>
+  )
+}

package/templates/fullstack-express/src/components/ui/magic-card.tsx

@@ -0,0 +1,103 @@
+"use client"
+
+import React, { useCallback, useEffect } from "react"
+import { motion, useMotionTemplate, useMotionValue } from "motion/react"
+
+import { cn } from "@/lib/utils"
+
+interface MagicCardProps {
+  children?: React.ReactNode
+  className?: string
+  gradientSize?: number
+  gradientColor?: string
+  gradientOpacity?: number
+  gradientFrom?: string
+  gradientTo?: string
+}
+
+export function MagicCard({
+  children,
+  className,
+  gradientSize = 200,
+  gradientColor = "#262626",
+  gradientOpacity = 0.8,
+  gradientFrom = "#9E7AFF",
+  gradientTo = "#FE8BBB",
+}: MagicCardProps) {
+  const mouseX = useMotionValue(-gradientSize)
+  const mouseY = useMotionValue(-gradientSize)
+  const reset = useCallback(() => {
+    mouseX.set(-gradientSize)
+    mouseY.set(-gradientSize)
+  }, [gradientSize, mouseX, mouseY])
+
+  const handlePointerMove = useCallback(
+    (e: React.PointerEvent<HTMLDivElement>) => {
+      const rect = e.currentTarget.getBoundingClientRect()
+      mouseX.set(e.clientX - rect.left)
+      mouseY.set(e.clientY - rect.top)
+    },
+    [mouseX, mouseY]
+  )
+
+  useEffect(() => {
+    reset()
+  }, [reset])
+
+  useEffect(() => {
+    const handleGlobalPointerOut = (e: PointerEvent) => {
+      if (!e.relatedTarget) {
+        reset()
+      }
+    }
+
+    const handleVisibility = () => {
+      if (document.visibilityState !== "visible") {
+        reset()
+      }
+    }
+
+    window.addEventListener("pointerout", handleGlobalPointerOut)
+    window.addEventListener("blur", reset)
+    document.addEventListener("visibilitychange", handleVisibility)
+
+    return () => {
+      window.removeEventListener("pointerout", handleGlobalPointerOut)
+      window.removeEventListener("blur", reset)
+      document.removeEventListener("visibilitychange", handleVisibility)
+    }
+  }, [reset])
+
+  return (
+    <div
+      className={cn("group relative rounded-[inherit]", className)}
+      onPointerMove={handlePointerMove}
+      onPointerLeave={reset}
+      onPointerEnter={reset}
+    >
+      <motion.div
+        className="bg-border pointer-events-none absolute inset-0 rounded-[inherit] duration-300 group-hover:opacity-100"
+        style={{
+          background: useMotionTemplate`
+          radial-gradient(${gradientSize}px circle at ${mouseX}px ${mouseY}px,
+          ${gradientFrom},
+          ${gradientTo},
+          var(--border) 100%
+          )
+          `,
+        }}
+      />
+      <div className="bg-background absolute inset-px rounded-[inherit]" />
+      <motion.div
+        className="pointer-events-none absolute inset-px rounded-[inherit] opacity-0 transition-opacity duration-300 group-hover:opacity-100"
+        style={{
+          background: useMotionTemplate`
+            radial-gradient(${gradientSize}px circle at ${mouseX}px ${mouseY}px, ${gradientColor}, transparent 100%)
+          `,
+          opacity: gradientOpacity,
+        }}
+      />
+      <div className="relative">{children}</div>
+    </div>
+  )
+}

package/templates/fullstack-express/src/lib/utils.ts

@@ -0,0 +1,6 @@
+import { clsx, type ClassValue } from "clsx"
+import { twMerge } from "tailwind-merge"
+
+export function cn(...inputs: ClassValue[]) {
+  return twMerge(clsx(inputs))
+}

package/templates/fullstack-express/src/types/ethereum.d.ts

@@ -0,0 +1,11 @@
+interface EthereumProvider {
+  request(args: { method: string; params?: unknown[] }): Promise<unknown>
+  isMetaMask?: boolean
+  on(event: string, handler: (...args: unknown[]) => void): void
+  removeListener(event: string, handler: (...args: unknown[]) => void): void
+}
+
+interface Window {
+  ethereum?: EthereumProvider
+}
+

package/templates/fullstack-express/tsconfig.json

@@ -0,0 +1,34 @@
+{
+  "compilerOptions": {
+    "target": "ES2017",
+    "lib": ["dom", "dom.iterable", "esnext"],
+    "allowJs": true,
+    "skipLibCheck": true,
+    "strict": true,
+    "noEmit": true,
+    "esModuleInterop": true,
+    "module": "esnext",
+    "moduleResolution": "bundler",
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "jsx": "react-jsx",
+    "incremental": true,
+    "plugins": [
+      {
+        "name": "next"
+      }
+    ],
+    "paths": {
+      "@/*": ["./src/*"]
+    }
+  },
+  "include": [
+    "next-env.d.ts",
+    "**/*.ts",
+    "**/*.tsx",
+    ".next/types/**/*.ts",
+    ".next/dev/types/**/*.ts",
+    "**/*.mts"
+  ],
+  "exclude": ["node_modules", "server.ts"]
+}

package/templates/fullstack-hono/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-hono/_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-hono/_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-hono/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-hono/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-hono/next.config.ts

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

package/templates/fullstack-hono/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-hono/postcss.config.mjs

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

package/templates/fullstack-hono/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',
+  })
+}