@payai/x402-next-starter 0.1.5 → 1.0.0

package/NOTICE

@@ -1,2 +1,2 @@
 This package includes portions derived from coinbase/x402 (examples/typescript/fullstack/next), Apache-2.0,
-commit 8d27e85f571bb9de62064a00f2f7abc0a63f6dd0. See LICENSE and upstream LICENSE notices.
+commit 6a99ba028b0d657122db8a06328cd432bdd8c7c0. See LICENSE and upstream LICENSE notices.

package/package.json

@@ -1,7 +1,11 @@
 {
   "name": "@payai/x402-next-starter",
-  "version": "0.1.5",
+  "version": "1.0.0",
   "private": false,
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org"
+  },
   "description": "Create an x402 Next.js app in less than 2 minutes!",
   "type": "module",
   "bin": {
@@ -34,6 +38,6 @@
     "url": "https://github.com/PayAINetwork/x402-next-starter"
   },
   "config": {
-    "x402NextVersion": "0.6.5"
+    "x402NextVersion": "2.3.0"
   }
 }

package/template/.env-local

@@ -1,3 +1,12 @@
+EVM_ADDRESS=
+SVM_ADDRESS=
+FACILITATOR_URL=
+
+CDP_CLIENT_KEY=
+APP_NAME=Next x402 Demo
+APP_LOGO=/x402-icon-blue.png
+
+
 NEXT_PUBLIC_FACILITATOR_URL=https://facilitator.payai.network
+
 NETWORK=solana-devnet
-RESOURCE_WALLET_ADDRESS=

package/template/.env.example

@@ -0,0 +1,4 @@
+
+NEXT_PUBLIC_FACILITATOR_URL=https://facilitator.payai.network
+
+NETWORK=solana-devnet

package/template/.prettierignore

@@ -3,6 +3,7 @@ dist/
 node_modules/
 coverage/
 .github/
+.next/
 src/client
 **/**/*.json
 *.md

package/template/README.md

@@ -1,30 +1,36 @@
 # x402-next Example App
 
-This is a Next.js application that demonstrates how to use the `x402-next` middleware to implement paywall functionality in your Next.js routes.
+Next.js application demonstrating how to protect routes with a paywall using the `@x402/next` middleware.
 
 ## Prerequisites
 
 - Node.js v20+ (install via [nvm](https://github.com/nvm-sh/nvm))
 - pnpm v10 (install via [pnpm.io/installation](https://pnpm.io/installation))
-- A valid Ethereum address for receiving payments
+- Valid EVM and SVM addresses for receiving payments
+- URL of a facilitator supporting the desired payment network, see [facilitator list](https://www.x402.org/ecosystem?category=facilitators)
 
 ## Setup
 
-1. Copy `.env-local` to `.env` and add your Ethereum address to receive payments:
+1. Copy `.env-local` to `.env`:
 
 ```bash
 cp .env-local .env
 ```
 
+and fill required environment variables:
+
+- `FACILITATOR_URL` - Facilitator endpoint URL
+- `EVM_ADDRESS` - Ethereum address to receive payments
+- `SVM_ADDRESS` - Solana address to receive payments
+
 2. Install and build all packages from the typescript examples root:
 ```bash
 cd ../../
-pnpm install
-pnpm build
+pnpm install && pnpm build
 cd fullstack/next
 ```
 
-2. Install and start the Next.js example:
+3. Run the server:
 ```bash
 pnpm dev
 ```
@@ -34,94 +40,238 @@ pnpm dev
 The app includes protected routes that require payment to access:
 
 ### Protected Page Route
-The `/protected` route requires a payment of $0.01 to access. The route is protected using the x402-next middleware:
+
+The `/protected` route is protected using `paymentProxy`. Page routes are protected using this approach:
 
 ```typescript
-// middleware.ts
-import { paymentMiddleware, Network, Resource } from "x402-next";
+// proxy.ts
+import { paymentProxy } from "@x402/next";
+import { x402ResourceServer, HTTPFacilitatorClient } from "@x402/core/server";
+import { registerExactEvmScheme } from "@x402/evm/exact/server";
+import { registerExactSvmScheme } from "@x402/svm/exact/server";
+import { createPaywall } from "@x402/paywall";
+import { evmPaywall } from "@x402/paywall/evm";
+import { svmPaywall } from "@x402/paywall/svm";
 
-const facilitatorUrl = process.env.NEXT_PUBLIC_FACILITATOR_URL as Resource;
-const payTo = process.env.RESOURCE_WALLET_ADDRESS as Address;
-const network = process.env.NETWORK as Network;
+const facilitatorClient = new HTTPFacilitatorClient({ url: facilitatorUrl });
+const server = new x402ResourceServer(facilitatorClient);
 
-export const middleware = paymentMiddleware(
-  payTo,
+// Register schemes
+registerExactEvmScheme(server);
+registerExactSvmScheme(server);
+
+// Build paywall using builder pattern
+const paywall = createPaywall()
+  .withNetwork(evmPaywall)
+  .withNetwork(svmPaywall)
+  .withConfig({
+    appName: "Next x402 Demo",
+    appLogo: "/x402-icon-blue.png",
+    testnet: true,
+  })
+  .build();
+
+export const proxy = paymentProxy(
   {
     "/protected": {
-      price: "$0.01",
-      network,
-      config: {
-        description: "Access to protected content",
-      },
+      accepts: [
+        {
+          scheme: "exact",
+          price: "$0.001",
+          network: "eip155:84532",
+          payTo: evmAddress,
+        },
+        {
+          scheme: "exact",
+          price: "$0.001",
+          network: "solana:EtWTRABZaYq6iMfeYKouRu166VU2xqa1",
+          payTo: svmAddress,
+        },
+      ],
+      description: "Premium music: x402 Remix",
+      mimeType: "text/html",
     },
   },
-  {
-    url: facilitatorUrl,
-  },
+  server,
+  undefined, // paywallConfig (using custom paywall instead)
+  paywall,   // custom paywall provider
 );
 
-// Configure which paths the middleware should run on
 export const config = {
   matcher: ["/protected/:path*"],
 };
 ```
 
+### Weather API Route (using withX402)
+
+The `/api/weather` route demonstrates the `withX402` wrapper for individual API routes:
+
+```typescript
+// app/api/weather/route.ts
+import { NextRequest, NextResponse } from "next/server";
+import { withX402 } from "@x402/next";
+import { server, paywall, evmAddress, svmAddress } from "../../../proxy";
+
+const handler = async (_: NextRequest) => {
+  return NextResponse.json({
+    report: {
+      weather: "sunny",
+      temperature: 72,
+    },
+  });
+};
+
+export const GET = withX402(
+  handler,
+  {
+    accepts: [
+      {
+        scheme: "exact",
+        price: "$0.001",
+        network: "eip155:84532",
+        payTo: evmAddress,
+      },
+      {
+        scheme: "exact",
+        price: "$0.001",
+        network: "solana:EtWTRABZaYq6iMfeYKouRu166VU2xqa1",
+        payTo: svmAddress,
+      },
+    ],
+    description: "Access to weather API",
+    mimeType: "application/json",
+  },
+  server,
+  undefined, // paywallConfig (using custom paywall from proxy.ts)
+  paywall,
+);
+```
+
 ## Response Format
 
 ### Payment Required (402)
+
+```
+HTTP/1.1 402 Payment Required
+Content-Type: application/json; charset=utf-8
+PAYMENT-REQUIRED: <base64-encoded JSON>
+
+{}
+```
+
+The `PAYMENT-REQUIRED` header contains base64-encoded JSON with the payment requirements.
+Note: `amount` is in atomic units (e.g., 1000 = 0.001 USDC, since USDC has 6 decimals):
+
 ```json
 {
-  "error": "X-PAYMENT header is required",
-  "paymentRequirements": {
-    "scheme": "exact",
-    "network": "base",
-    "maxAmountRequired": "1000",
-    "resource": "http://localhost:3000/protected",
-    "description": "Access to protected content",
-    "mimeType": "",
-    "payTo": "0xYourAddress",
-    "maxTimeoutSeconds": 60,
-    "asset": "0x...",
-    "outputSchema": null,
-    "extra": null
-  }
+  "x402Version": 2,
+  "error": "Payment required",
+  "resource": {
+    "url": "http://localhost:3000/api/weather",
+    "description": "Access to weather API",
+    "mimeType": "application/json"
+  },
+  "accepts": [
+    {
+      "scheme": "exact",
+      "network": "eip155:84532",
+      "amount": "1000",
+      "asset": "0x036CbD53842c5426634e7929541eC2318f3dCF7e",
+      "payTo": "0x...",
+      "maxTimeoutSeconds": 300,
+      "extra": {
+        "name": "USDC",
+        "version": "2",
+        "resourceUrl": "http://localhost:4021/weather"
+      }   
+    }
+  ]
 }
 ```
 
 ### Successful Response
-```ts
-// Headers
+
+```
+HTTP/1.1 200 OK
+Content-Type: application/json; charset=utf-8
+PAYMENT-RESPONSE: <base64-encoded JSON>
+
+{"report":{"weather":"sunny","temperature":72}}
+```
+
+The `PAYMENT-RESPONSE` header contains base64-encoded JSON with the settlement details:
+
+```json
 {
-  "X-PAYMENT-RESPONSE": "..." // Encoded response object
+  "success": true,
+  "transaction": "0x...",
+  "network": "eip155:84532",
+  "payer": "0x...",
+  "requirements": {
+    "scheme": "exact",
+    "network": "eip155:84532",
+    "amount": "1000",
+    "asset": "0x036CbD53842c5426634e7929541eC2318f3dCF7e",
+    "payTo": "0x...",
+    "maxTimeoutSeconds": 300,
+    "extra": {
+      "name": "USDC",
+      "version": "2",
+      "resourceUrl": "http://localhost:4021/weather"
+    }
+  }
 }
 ```
 
+## paymentProxy vs withX402
+
+The `paymentProxy` function is used to protect page routes. It can also protect API routes, however this will charge clients for failed API responses.
+
+The `withX402` function wraps API route handlers. This is the recommended approach to protect API routes as it guarantees payment settlement only AFTER successful API responses (status < 400).
+
+| Approach | Use Case |
+|----------|----------|
+| `paymentProxy` | Protecting page routes or multiple routes with a single configuration |
+| `withX402` | Protecting individual API routes where you need precise control over settlement timing |
+
 ## Extending the Example
 
-To add more protected routes, update the middleware configuration:
+To add more protected routes, update the proxy configuration:
 
 ```typescript
-export const middleware = paymentMiddleware(
-  payTo,
+export const proxy = paymentProxy(
   {
     "/protected": {
-      price: "$0.01",
-      network,
-      config: {
-        description: "Access to protected content",
+      accepts: {
+        scheme: "exact",
+        price: "$0.001",
+        network: "eip155:84532",
+        payTo: evmAddress,
       },
+      description: "Access to protected content",
     },
-    "/api/premium": {
-      price: "$0.10",
-      network,
-      config: {
-        description: "Premium API access",
+    "/premium": {
+      accepts: {
+        scheme: "exact",
+        price: "$0.10",
+        network: "eip155:84532",
+        payTo: evmAddress,
       },
+      description: "Premium content access",
     },
-  }
+  },
+  server,
+  undefined,
+  paywall,
 );
 
 export const config = {
-  matcher: ["/protected/:path*", "/api/premium/:path*"],
+  matcher: ["/protected/:path*", "/premium/:path*"],
 };
 ```
+
+**Network identifiers** use [CAIP-2](https://github.com/ChainAgnostic/CAIPs/blob/main/CAIPs/caip-2.md) format, for example:
+- `eip155:84532` — Base Sepolia
+- `eip155:8453` — Base Mainnet
+- `solana:EtWTRABZaYq6iMfeYKouRu166VU2xqa1` — Solana Devnet
+- `solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp` — Solana Mainnet

package/template/app/api/weather/route.ts

@@ -0,0 +1,69 @@
+import { NextRequest, NextResponse } from "next/server";
+import { withX402 } from "@x402/next";
+import { declareDiscoveryExtension } from "@x402/extensions/bazaar";
+import { server, paywall, evmAddress, svmAddress } from "../../../proxy";
+
+/**
+ * Weather API endpoint handler
+ *
+ * This handler returns weather data after payment verification.
+ * Payment is only settled after a successful response (status < 400).
+ *
+ * @param _ - Incoming Next.js request
+ * @returns JSON response with weather data
+ */
+const handler = async (_: NextRequest) => {
+  return NextResponse.json(
+    {
+      report: {
+        weather: "sunny",
+        temperature: 72,
+      },
+    },
+    { status: 200 },
+  );
+};
+
+/**
+ * Protected weather API endpoint using withX402 wrapper
+ *
+ * This demonstrates the v2 withX402 wrapper for individual API routes.
+ * Unlike middleware, withX402 guarantees payment settlement only after
+ * the handler returns a successful response (status < 400).
+ */
+export const GET = withX402(
+  handler,
+  {
+    accepts: [
+      {
+        scheme: "exact",
+        price: "$0.001",
+        network: "eip155:84532", // base-sepolia
+        payTo: evmAddress,
+      },
+      {
+        scheme: "exact",
+        price: "$0.001",
+        network: "solana:EtWTRABZaYq6iMfeYKouRu166VU2xqa1", // solana devnet
+        payTo: svmAddress,
+      },
+    ],
+    description: "Access to weather API",
+    mimeType: "application/json",
+    extensions: {
+      ...declareDiscoveryExtension({
+        output: {
+          example: {
+            report: {
+              weather: "sunny",
+              temperature: 72,
+            },
+          },
+        },
+      }),
+    },
+  },
+  server,
+  undefined, // paywallConfig (using custom paywall from proxy.ts)
+  paywall,
+);

package/template/app/globals.css

@@ -1,33 +1,29 @@
-@tailwind base;
-@tailwind components;
-@tailwind utilities;
+@import "tailwindcss";
 
-:root {
-  --background: #ffffff;
-  --foreground: #171717;
+@theme {
+  --color-background: #ffffff;
+  --color-foreground: #171717;
 }
 
 @media (prefers-color-scheme: dark) {
-  :root {
-    --background: #1a1a2e;
-    --foreground: #ededed;
+  @theme {
+    --color-background: #1a1a2e;
+    --color-foreground: #ededed;
   }
 }
 
 body {
-  color: var(--foreground);
-  background: var(--background);
+  color: var(--color-foreground);
+  background: var(--color-background);
   font-family: Arial, Helvetica, sans-serif;
 }
 
-@layer utilities {
-  .full-bleed {
-    width: 100vw;
-    margin-left: calc(50% - 50vw);
-  }
+@utility full-bleed {
+  width: 100vw;
+  margin-left: calc(50% - 50vw);
+}
 
-  .unset-full-bleed {
-    width: unset;
-    margin-left: unset;
-  }
+@utility unset-full-bleed {
+  width: unset;
+  margin-left: unset;
 }

package/template/app/layout.tsx

@@ -13,8 +13,8 @@ const geistMono = Geist_Mono({
 });
 
 export const metadata: Metadata = {
-  title: 'x402.org',
-  description: 'A chain-agnostic protocol for web payments',
+  title: "x402 Next.js Demo",
+  description: "A chain-agnostic protocol for web payments",
 };
 
 export default function RootLayout({
@@ -25,19 +25,8 @@ export default function RootLayout({
   return (
     <html lang="en">
       <head>
-        <link rel="icon" href="/favicon.ico" sizes="any" />
-        <link
-          rel="icon"
-          type="image/png"
-          href="/favicon-96x96.png"
-          sizes="96x96"
-        />
-        <link rel="icon" type="image/svg+xml" href="/favicon.svg" />
-        <link
-          rel="apple-touch-icon"
-          sizes="180x180"
-          href="/apple-touch-icon.png"
-        />
+        <link rel="icon" type="image/png" href="/x402-icon-black.png" />
+        <link rel="apple-touch-icon" href="/x402-icon-black.png" />
         <meta name="apple-mobile-web-app-title" content="x402" />
         <link rel="manifest" href="/site.webmanifest" />
       </head>
@@ -49,3 +38,4 @@ export default function RootLayout({
     </html>
   );
 }
+

package/template/app/page.tsx

@@ -1,5 +1,5 @@
-import Link from 'next/link';
-import WordmarkCondensed from './assets/x402_wordmark_light.svg';
+import Link from "next/link";
+import Image from "next/image";
 
 export default function Home() {
   return (
@@ -8,8 +8,14 @@ export default function Home() {
         {/* Hero Section */}
         <section className="max-w-6xl mx-auto px-4 py-20 lg:py-28">
           <div className="text-center">
-            <div className="w-64 mb-6 mx-auto">
-              <WordmarkCondensed className="mx-auto" />
+            <div className="mb-6">
+              <Image
+                src="/x402-logo-dark.png"
+                alt="x402 logo"
+                width={320}
+                height={160}
+                className="mx-auto"
+              />
             </div>
             <p className="text-xl text-gray-600 mb-8 font-mono">
               Fullstack demo powered by Next.js
@@ -19,14 +25,20 @@ export default function Home() {
                 href="/protected"
                 className="px-6 py-3 bg-blue-600 hover:bg-blue-700 rounded-lg font-mono transition-colors text-white"
               >
-                Live demo
+                Protected page
+              </Link>
+              <Link
+                href="/api/weather"
+                className="px-6 py-3 bg-blue-600 hover:bg-blue-700 rounded-lg font-mono transition-colors text-white"
+              >
+                Protected API
               </Link>
             </div>
           </div>
         </section>
       </div>
       <footer className="py-8 text-center text-sm text-gray-500">
-        By using this site, you agree to be bound by the{' '}
+        By using this site, you agree to be bound by the{" "}
         <a
           href="https://www.coinbase.com/legal/developer-platform/terms-of-service"
           target="_blank"
@@ -34,8 +46,8 @@ export default function Home() {
           className="text-blue-500"
         >
           CDP Terms of Service
-        </a>{' '}
-        and{' '}
+        </a>{" "}
+        and{" "}
         <a
           href="https://www.coinbase.com/legal/privacy"
           target="_blank"
@@ -49,3 +61,4 @@ export default function Home() {
     </div>
   );
 }
+

package/template/app/protected/page.tsx

@@ -6,11 +6,48 @@ export default function ProtectedPage() {
         <p className="text-lg">
           Your payment was successful! Enjoy this banger song.
         </p>
-        <iframe width="100%" height="300" scrolling="no" frameBorder="no" allow="autoplay" src="https://w.soundcloud.com/player/?url=https%3A//api.soundcloud.com/tracks/2044190296&color=%23ff5500&auto_play=true&hide_related=false&show_comments=true&show_user=true&show_reposts=false&show_teaser=true&visual=true"></iframe>
-        <div style={{ fontSize: '10px', color: '#cccccc', lineBreak: 'anywhere', wordBreak: 'normal', overflow: 'hidden', whiteSpace: 'nowrap', textOverflow: 'ellipsis', fontFamily: 'Interstate,Lucida Grande,Lucida Sans Unicode,Lucida Sans,Garuda,Verdana,Tahoma,sans-serif', fontWeight: '100' }}>
-          <a href="https://soundcloud.com/dan-kim-675678711" title="danXkim" target="_blank" style={{ color: '#cccccc', textDecoration: 'none' }}>danXkim</a> · <a href="https://soundcloud.com/dan-kim-675678711/x402" title="x402 (DJ Reppel Remix)" target="_blank" style={{ color: '#cccccc', textDecoration: 'none' }}>x402 (DJ Reppel Remix)</a>
+        <iframe
+          width="100%"
+          height="300"
+          scrolling="no"
+          frameBorder="no"
+          allow="autoplay"
+          src="https://w.soundcloud.com/player/?url=https%3A//api.soundcloud.com/tracks/2044190296&color=%23ff5500&auto_play=true&hide_related=false&show_comments=true&show_user=true&show_reposts=false&show_teaser=true&visual=true"
+        ></iframe>
+        <div
+          style={{
+            fontSize: "10px",
+            color: "#cccccc",
+            lineBreak: "anywhere",
+            wordBreak: "normal",
+            overflow: "hidden",
+            whiteSpace: "nowrap",
+            textOverflow: "ellipsis",
+            fontFamily:
+              "Interstate,Lucida Grande,Lucida Sans Unicode,Lucida Sans,Garuda,Verdana,Tahoma,sans-serif",
+            fontWeight: "100",
+          }}
+        >
+          <a
+            href="https://soundcloud.com/dan-kim-675678711"
+            title="danXkim"
+            target="_blank"
+            style={{ color: "#cccccc", textDecoration: "none" }}
+          >
+            danXkim
+          </a>{" "}
+          ·{" "}
+          <a
+            href="https://soundcloud.com/dan-kim-675678711/x402"
+            title="x402 (DJ Reppel Remix)"
+            target="_blank"
+            style={{ color: "#cccccc", textDecoration: "none" }}
+          >
+            x402 (DJ Reppel Remix)
+          </a>
         </div>
       </div>
     </div>
   );
 }
+

package/template/eslint.config.js

@@ -7,7 +7,7 @@ import importPlugin from "eslint-plugin-import";
 
 export default [
   {
-    ignores: ["dist/**", "node_modules/**", ".next/**"],
+    ignores: ["dist/**", "node_modules/**", ".next/**", "next-env.d.ts"],
   },
   {
     files: ["**/*.ts"],

package/template/next-env.d.ts

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