Payroute Web Monitoring

_{Payroute — x402-native marketplace, dashboard, and demo toolkit for Mantle builders.}

Table of Contents

• Overview
• Key Frontend Features
• Tech Stack
• Architecture Snapshot
• Routes
• Local Development
• Environment Variables
• Build & Production
• Demo Flow
• Known Limitations
• Security & Privacy Notes
• Further Documentation

Overview

Payroute Web Monitoring is a Next.js 16 frontend that showcases how API and AI creators can monetize access through the x402 payment protocol. It brings the Payroute marketplace, creator dashboard, and marketing landing page into one cohesive interface backed by Privy-authenticated wallets. Creators can register on Mantle Sepolia, wrap their APIs, publish AI agents, and push offerings straight to the marketplace without shipping extra UI. Buyers can browse paid endpoints, run pay-per-call demos (direct or escrow), and interact with AI agents through the bundled @payroute/x402-sdk flows. The faucet utility helps judges mint test mUSD balances so they can try the experience end-to-end. The entire experience is tuned for hackathon judging: deterministic instructions, mock fallbacks when backend routes are missing, and a clear separation between landing and app surfaces.

Key Frontend Features

• Wallet-gated creator onboarding and login powered by Privy, Wagmi, and Mantle Sepolia testnet wallets (src/hooks/auth/useAuthLogin.ts).
• Creator dashboard with tabs to create gateways, manage wrapped APIs, configure AI agents, and attach resources using Zustand stores (src/components/pages/(main)/dashboard/creator).
• Marketplace views for both URL-wrapped APIs and AI agents, including filters, search, and rich detail pages with live testing widgets.
• Client-side testers that call /api/payment/proxy and /api/payment/ai-agent to execute pay-per-call or escrow flows via the @payroute/x402-sdk server actions.
• Embedded SDK education section on the landing page plus faucet utility so judges can fund wallets without leaving the app.
• Toast-driven feedback (sonner) and optimistic caches to make demos predictable even when upstream services respond slowly.

Tech Stack

• Framework: Next.js 16 App Router with React 19 and Server Actions disabled for client-heavy pages.
• Styling: Tailwind CSS v4, custom OKLCH tokens, clsx, tailwind-merge, framer-motion, and gsap for motion + grid overlays.
• Wallet & Auth: Privy (@privy-io/react-auth), Wagmi 3 configured for Mantle Sepolia (src/lib/wagmi.ts), @privy-io/wagmi, and Viem helpers.
• Payments: @payroute/x402-sdk instantiated inside Zustand stores (src/stores/payment*.ts) and inside Next.js API routes for server-safe private key usage.
• State & Data: Zustand stores per domain (src/stores), TanStack Query client for future hooks, and @tanstack/react-query provider in PrivyWagmiProvider.
• UI primitives: lucide-react, react-icons, sonner toasts, custom Button/Input/Modal components in src/components/ui.

Architecture Snapshot

• Route groups split surfaces: (landing) renders marketing pages, (main) holds the authenticated app, and /api/payment/* exposes server-side SDK helpers.
• src/components/pages mirrors route segments to keep UI logic presentational and easy to swap during demos.
• Domain stores under src/stores encapsulate all network calls, caching, error toasts, and SDK interactions (creator, marketplace, payment, upload, etc.).
• src/lib centralizes integrations: privy-provider.tsx wires Privy + Wagmi + Query, api/client.ts wraps fetch with base URL + headers, and wagmi.ts pins Mantle Sepolia RPCs.
• Shared data contracts live in src/types, while mock listings in src/data guarantee marketplace cards render before the backend is wired in fully.

Routes

Route	Description
/	Landing experience composed of Hero, Services, Portal, SDK, FAQ, and Footer sections with CTA to the app (src/components/pages/(landing)).
/marketplace	Lists URL-wrapped APIs with filters, search, and table layout fed by useMarketplaceStore.fetchUrlWrappedEndpoints.
/marketplace/[id]	Detailed API view with endpoint metadata, stats, and the TestApiSection paywall tester.
/marketplace/ai-agent	AI Agent marketplace grid backed by useMarketplaceStore.fetchAIAgentEndpoints.
/marketplace/ai-agent/[slug]	AI agent detail and TestAIAgentSection for per-message payments.
/marketplace/faucet	Mantle Sepolia faucet UI that writes to faucet(address, amount) via Wagmi hooks.
/dashboard	Entry page that routes users to login/register flows.
/register	Creator registration form storing wallet + ID via useCreatorStore.registerCreator.
/login	Wallet nonce-signing login handled by useAuthLogin and Privy session state.
/dashboard/creator	Main creator dashboard with analytics placeholders (DashboardContent).
/dashboard/creator/create-gateway	Gateway builder form that uploads icons and posts to /creator/wrapped/:id.
/dashboard/creator/my-wrapped-api	Table of wrapped APIs fetched from the Creator store cache.
/dashboard/creator/ai-agent	AI agent creation + management UI (creator/AIAgent).
/dashboard/creator/resources	Resource management UI for attaching knowledge to agents.
/dashboard/creator/profile	Profile panel that mirrors stored wallet metadata.

Local Development

1. Ensure you are on Node 20+ with pnpm installed (corepack enable).
2. Copy .env.local.example (create one if needed) and provide the variables listed below.
3. Install dependencies: pnpm install.
4. Start the dev server: pnpm dev (runs on http://localhost:3000).
5. Connect a Mantle Sepolia wallet via Privy, then exercise marketplace and dashboard flows.

Environment Variables

Name	Required	Description	Example	Referenced In
NEXT_PUBLIC_PRIVY_APP_ID	Yes	Privy application identifier for wallet auth and embedded wallets.	app_abcdefghijklmnop	src/lib/privy-provider.tsx
NEXT_PUBLIC_X402_SERVICES_API	Yes	Base HTTPS URL for the Payroute/x402 service the stores call (creator register, marketplace listings, uploads).	https://services.payroute.dev	src/lib/api/client.ts, src/stores/*, src/stores/upload.ts
WALLET_PRIVATE_KEY	Yes (server)	Server-only wallet used by Next API routes to instantiate PaymentService for proxy + AI calls. Keep it out of NEXT_PUBLIC_*.	0xabc123...	src/app/api/payment/*/route.ts
AGENT_PRIVATE_KEY	Optional	Only referenced inside code snippets rendered on the landing page for documentation purposes. Use if you want live examples compiled with a specific key.	0xfeedface...	src/components/pages/(landing)/SDK.tsx

See docs/ENVIRONMENT.md for setup tips and validation steps.

Build & Production

• Build for production: pnpm build (runs next build).
• Start the production server locally: pnpm start (serves the .next output on port 3000 by default).
• Ensure WALLET_PRIVATE_KEY is injected as a server secret in your hosting provider and that NEXT_PUBLIC_* values are safe to expose.
• When deploying to Vercel or similar, add Mantle Sepolia RPC domains to the allowlist if your platform enforces outbound firewalling.

Demo Flow

1. Landing overview – start at /, trigger the floating Navigation, and scroll through Services → Portal → SDK to explain the story.
2. Creator onboarding – click "Launch App" → /register, connect a test wallet via Privy, and submit the form (toast confirms + redirect to /login).
3. Login + dashboard – on /login, use the same wallet to request a nonce, sign it, and land on /dashboard/creator where stats + tabs render instantly.
4. Create a gateway – navigate to "Create Gateway", upload an icon, enter values like https://example.com/weather, slug weather-oracle, price 0.05, submit and show success toasts.
5. Marketplace test – visit /marketplace, filter, and open any row. Use Test API → choose Direct vs Escrow and trigger /api/payment/proxy; if backend 404s you still get the mock payload so judges can see results.
6. AI Agent test – open /marketplace/ai-agent, pick an agent, and run the tester with a prompt such as "Summarize the Mantle roadmap". Mock responses appear if the upstream slug is missing.
7. Faucet + security – finally open /marketplace/faucet, autofill the connected address, and submit so the Mantle explorer link appears in the toast + UI.

Known Limitations

• Dashboard analytics currently show placeholder earnings and counts because the backend endpoints are not yet wired; highlight this during demos.
• Marketplace listings depend on the NEXT_PUBLIC_X402_SERVICES_API responses. Without it, useMarketplaceStore falls back to empty arrays and the UI will say "No APIs found".
• Payment testers call server routes that require WALLET_PRIVATE_KEY. If it is missing or the slug is invalid, the handlers return mock data after logging the issue.
• Creator session state is stored in sessionStorage. Clearing site data or opening a new tab resets the guard and forces a new login.

Security & Privacy Notes

• Never expose WALLET_PRIVATE_KEY or other secrets in NEXT_PUBLIC_* variables or client bundles. Keep them in server envs or platform secrets.
• Privy + Wagmi expect HTTPS origins in production; ensure callback URLs are whitelisted inside the Privy dashboard.
• Uploaded assets are proxied through NEXT_PUBLIC_X402_SERVICES_API. Validate that service before trusting user-generated content.
• When sharing demo environments, rotate faucet contract addresses and private keys between hackathons.

Further Documentation

• docs/FRONTEND.md – deep dive into app structure, route responsibilities, and data flow.
• docs/ARCHITECTURE.md – expanded file + module architecture reference.
• docs/ENVIRONMENT.md – environment setup matrix and diagnostics.
• docs/DEMO_GUIDE.md – click-by-click script for judges.
• docs/TROUBLESHOOTING.md – known issues and quick fixes.
• docs/CONTRIBUTING_FRONTEND.md – coding conventions, linting, and pull request tips.