Cardano x402 Protocol Demo (Next.js)

A Next.js 16 application demonstrating payment-based access control using the x402 protocol on the Cardano blockchain. This demo shows how to implement a paywall system where users must connect their Cardano wallet and make a small payment to access protected resources using the X-PAYMENT header.

Overview

This project implements the x402 protocol, which extends HTTP with payment-based authentication. Users are required to:

1. Connect their Cardano wallet (supports Yoroi, Lace, Eternl).
2. Pay 0.01 USDM (Policy: c48cbb3d5e57ed56e276bc45f99ab39abe94e6cd7ac39fb402da47ad) to access protected resources.
3. The backend verifies the transaction on-chain via Blockfrost before serving the content.

Features

• Frontend: Next.js 16 (App Router), Tailwind CSS, Radix UI.
• Wallet Integration: @cardano-foundation/cardano-connect-with-wallet for multi-wallet support.
• Transaction Building: Client-side transaction construction using lucid-cardano.
• Backend: Next.js API Routes acting as both Resource Server and Facilitator.
• Verification: Server-side on-chain verification using @blockfrost/blockfrost-js.
• Deployment: Vercel-ready with WASM support configured.

Tech Stack

• Framework: Next.js 16
• Styling: Tailwind CSS
• State Management: Jotai
• Cardano Libs: lucid-cardano, @blockfrost/blockfrost-js
• Animations: Motion

Getting Started

Prerequisites

• Node.js 18+
• pnpm (recommended) or npm/yarn
• A Cardano wallet (Yoroi, Lace, or Eternl)
• A Blockfrost Project ID (Mainnet for this demo as per config)

Installation

1. Clone the repository:

   git clone <repository-url>
   cd x402-example-cardano

2. Install dependencies:

   pnpm install
   # or npm install

3. Set up environment variables:

   Create a .env.local file in the root directory:

   # Required for backend verification
   BLOCKFROST_PROJECT_ID=your_mainnet_project_id
   
   # Required for client-side transaction building (demo only)
   NEXT_PUBLIC_BLOCKFROST_PROJECT_ID=your_mainnet_project_id
   
   # URL for the facilitator (same as app URL for local)
   FACILITATOR_URL=http://localhost:3000/api/facilitator
   
   NETWORK=cardano-mainnet

4. Run the development server:

   pnpm run dev

   Open http://localhost:3000 with your browser.

Deployment on Vercel

This project requires specific configuration for WASM support (used by Cardano crypto libraries).

1. Build Command: The package.json is configured to force Webpack: next build --webpack
2. Config: next.config.ts enables asyncWebAssembly.

Deploy normally via Vercel CLI or Git integration. Ensure you add the Environment Variables in the Vercel dashboard.

x402 Flow

1. Resource Request: Client requests protected resource.
2. Payment Required (402): Server responds with 402 and PaymentRequirements (address, amount, asset).
3. Payment Submission: Client signs transaction, encodes it in X-PAYMENT header, and retries request.
4. Verification: Server verifies X-PAYMENT header, submits transaction to network (if needed), and monitors confirmation.
5. Access Granted: Once confirmed, Server responds with 200 OK and the resource.

Local Development Notes

• WASM Issues: If you see errors related to @peculiar/webcrypto or lucid-cardano, ensure you are running pnpm run dev which uses the updated webpack config flags.
• Wallet Connection: Ensure your wallet is set to the correct network (Mainnet) to match the demo config.