Wallet Dashboard

This is a Next.js project bootstrapped with create-next-app, focused on Web3 frontend development. It integrates MetaMask wallet, Wagmi, and other tools to implement core features such as wallet dashboards and Web3 payments. It is for Web3 beginners as it can easily connect MetaMask, view on-chain assets, and complete simple payments without technical expertise. Web3 frontend developers are also be suitable as reusable architecture and core modules can be directly uesd to quickly build wallet interfaces. Small Web3 projects can also use for the fast integration with the X402 payment protocol to unlock paid on-chain resources.

---

Features

·One-click wallet connection via MetaMask ·Real-time ETH balance display ·Automatic current network detection ·Send test ETH transactions and track transaction hashes ·Local storage for the latest 5 transaction records ·X402 payment challenge generation ·Backend on-chain transaction verification ·Unlock premium API data after successful payment ·Complete payment request logs ·Payment modals, status badges, and transaction links to block explorers

---

Installation

Prerequisites

Ensure the following tools are installed in your local environment:

• Node.js 18.17+ (LTS version recommended)
• MetaMask wallet extension
• WalletConnect Project ID
• Testnet ETH on Base Sepolia or Sepolia

Installation Steps

1. Clone the projectgit clone <your-project-repository-url> cd <your-project-directory-name>

2. Install dependencies` npm install

or

yarn install

or

pnpm install

or

bun install`

3. Configure environment variablesCreate a .env.local file in the project root and fill in the required environment variables: NEXT_PUBLIC_APP_URL=http://localhost:3000 NEXT_PUBLIC_WALLET_CONNECT_PROJECT_ID=your-walletconnect-id PAYWALL_ADDRESS=your-receiving-wallet-address REQUIRED_PRICE=100000000000000 RPC_URL=https://sepolia.base.org

4. Run the development server`npm run dev

or

yarn dev

or

pnpm dev

or

bun dev`

5. Access the applicationOpen your browser and visit http://localhost:3000 to see the result. You can start editing the page by modifying app/page.tsx, and the page will auto-update as you edit the file.

---

Tech Stack & Versions

Technology/Tool	Version	Purpose
Next.js	15.x	Full-stack React framework for server-side rendering, routing, etc.
React	18.x	Frontend UI building library
TypeScript	5.x	Typed superset of JavaScript for type safety
Wagmi	2.x	Web3 interaction library for wallet connection, contract calls, etc.
Viem	2.x	High-performance Ethereum interaction library (alternative to Ethers.js)
RainbowKit	2.x	Beautiful wallet connection UI component for Web3 DApps
X402 Protocol	Latest	Decentralized payment protocol for on-chain API access control
MetaMask Browser Extension	Latest	Wallet connection and interaction
Tailwind CSS	3.x	Utility-first CSS framework for responsive UI styling
ESLint	8.x	Code linting and style checking

---

Environment Variables Documentation

Variable Name	Required	Function & Description	Security Considerations
NEXT_PUBLIC_APP_URL	✅ Required	Base URL of the deployed application. Set to http://localhost:3000 for local development; replace with your production domain after deployment. Used for frontend routing and API request base address.	No sensitive data, safe to expose to the browser.
NEXT_PUBLIC_WALLET_CONNECT_PROJECT_ID	✅ Required	WalletConnect Project ID, mandatory for RainbowKit wallet connection (supports MetaMask, WalletConnect, etc.). Obtain from WalletConnect Cloud.	Do not leak this ID to avoid unauthorized usage of your WalletConnect project quota.
PAYWALL_ADDRESS	✅ Required	The wallet address that receives on-chain payments for X402 protocol. All user payments for premium data will be sent to this address.	Never expose this variable to the frontend (only used in backend API routes, no NEXT_PUBLIC_ prefix).
REQUIRED_PRICE	✅ Required	The minimum payment amount (in wei) required to unlock premium API data. 1 ETH = 10^18 wei, default value is 100000000000000 (0.0001 ETH).	Only used in backend verification logic, no NEXT_PUBLIC_ prefix, safe from frontend tampering.
RPC_URL	✅ Required	RPC node URL for Base Sepolia testnet, used by the backend to query on-chain transactions and verify payment validity. Default value is https://sepolia.base.org.	Only used in backend, no NEXT_PUBLIC_ prefix, avoid exposing to public to prevent RPC quota abuse.

---

Usage Examples

Complete X402 Payment Flow

1. Connect your wallet

2. Click Fetch Premium Data

3. The backend returns a 402 response, and a payment modal pops up

4. Click Approve & Pay and confirm the transaction in your wallet

5. The backend automatically verifies that the transaction meets the following criteria:

• Correct recipient address

• Minimum required amount

• Successful on-chain transaction

6. Verification passed → Unlock premium data and display a success prompt

Success Indicators

• A green success prompt appears

• Encrypted returned content is displayed

• A successful payment record is added to the log table

• The transaction is saved to the transaction history

---

Project Architecture

Overall Architecture

This project adopts the Next.js App Router architecture for integrated front-end and back-end development, with the following core layers:

Project Root
├── app/                # Next.js App Router pages and routes
│   ├── page.tsx        # Homepage & main wallet dashboard UI
│   └── api/
│       └── premium-data/
│           └── route.ts # Backend API endpoint for X402 payment verification
├── components/         # Reusable UI components (if extended)
│   ├── wallet/         # Wallet-related components (connect button, balance display, etc.)
│   └── layout/         # Layout components
├── hooks/              # Custom React Hooks
│   ├── useWallet.ts    # Wallet connection and state management Hook
│   └── useX402.ts      # X402 payment Hook (payment flow, proof handling)
├── lib/                # Utility functions and configurations
│   ├── wagmi.ts        # Wagmi client configuration (wallet connection, chain setup)
│   └── constants.ts    # Project constants (chain info, payment address, etc.)
├── public/             # Static assets (logos, icons, etc.)
└── .env.local          # Environment variables (local, never commit to Git)

Core Workflows

1. Wallet Connection Flow User clicks "Connect Wallet" → Calls Wagmi's useConnect Hook via RainbowKit → Triggers MetaMask wallet → Confirms connection, Wagmi manages wallet state → Page displays wallet address, balance, and network information
2. X402 Payment Flow (Premium Data Access) User accesses /api/premium-data without payment proof → Backend returns 402 Payment Required with X402 challenge → Frontend parses challenge, displays payment modal → User confirms payment in MetaMask, sends on-chain transaction → Frontend resubmits request with transaction proof → Backend verifies transaction (recipient address + amount) via Viem → If valid, unlocks and returns premium data; if invalid, re-prompts for payment
3. Test ETH Transaction Flow User clicks "Send Test ETH" → Frontend calls Wagmi's useSendTransaction Hook → Triggers MetaMask to confirm transaction → Transaction is broadcast to Base Sepolia/Sepolia testnet → Frontend tracks transaction status via useWaitForTransactionReceipt → After on-chain confirmation, saves transaction to local history and logs the operation

---

Known Issues & Limitations

• Only supports the Base Sepolia network

• Only supports native ETH payments

• Transaction history is stored in localStorage and will be lost if the browser cache is cleared

• Occasional wallet state delay when switching networks

• Automatically falls back to local verification if third-party facilitator verification is unavailable

Future Optimization Directions

• Add multi-chain support

• Pull real on-chain transaction history from RPC

---

Learn More

To learn more about Next.js, take a look at the following resources:

• Next.js Documentation - learn about Next.js features and API.
• Learn Next.js - an interactive Next.js tutorial.
• Wagmi Documentation - learn Web3 wallet interaction and contract calls.
• Viem Documentation - master low-level Ethereum interaction capabilities.
• X402 Protocol Documentation - understand the implementation of Web3 payment protocols.

You can check out the Next.js GitHub repository - your feedback and contributions are welcome!

---

Contribute

Issues and Pull Requests to improve this project are welcome!

---

License

This project is open-source under the MIT License (modify according to your project's actual license).