Pearfect-Project

Pearfect — Demo Trading App for Pear Protocol

A guided, gamified demo trading experience that converts curious users into Pear Protocol traders.

---

What is Pearfect?

Pearfect is a zero-friction demo trading app built on top of Pear Protocol. Users arrive, get a burner wallet instantly, type a trade thesis in plain English, and receive an AI-generated LONG/SHORT basket — all without connecting a real wallet or touching real funds.

The goal: show users the Pear experience end-to-end, then convert them to live trading via a tracked "Go to Pear" CTA.

---

Live Demo

🔗 pearfect.vercel.app (Milestone 1 in active development)

---

Feature Milestones

✅ Milestone 1 — Functional Demo App ($500 on delivery)

End-to-end demo flow: wallet generation → guided trade builder → simulated execution → credit system → conversion modal.

🔄 Milestone 2 — Demo Sign-Up Tracking (revenue share baseline)

Analytics layer: log every wallet creation with timestamp + unique ID, expose daily/weekly dashboard.

🔄 Milestone 3 — Conversion Rate Tracking (75% revenue share trigger)

Log "Go to Pear" clicks with UTM attribution so Pear can tie trading volume back to demo-converted users.

---

Frontend — What's Built

Page / Component	Status
Landing page — branding, CTA, "Start Demo" button	✅ Live
Nav — wallet address display, XP level UI	✅ Live (mock wallet → real wallet in M1)
Agent page — AI pair analysis, bullish/bearish/risk prompts, confidence %	✅ Live
Learn page + Discord link	✅ Live
Burner wallet generation UI — auto-trigger on "Start Demo"	🔄 In progress
Guided Trade Builder UI — thesis input, LONG/SHORT basket, weight sliders	🔄 In progress
Simulated wallet signing modal — fake "Confirm Transaction" popup	🔄 In progress
Trade execution result screen — fill price, P&L, basket summary	🔄 In progress
Trade history panel — past trades with pair, direction, simulated P&L	🔄 In progress
Credit tracker — persistent display, deducts per trade	🔄 In progress
"Upgrade to Pear" modal — fires at 0 credits with UTM-tagged CTA	🔄 In progress
Analytics dashboard — sign-up totals, daily/weekly chart	🔄 M2

---

Tech Stack

Layer	Technology
Framework	Next.js 14 (App Router)
Language	TypeScript
Styling	Tailwind CSS — matched to Pear Protocol design kit
Deployment	Vercel
Market Data	CoinGecko API / Binance WebSocket (via backend)
State	React Context + hooks
Auth	Sessionless — burner wallet tied to device fingerprint (backend)

---

Project Structure

pearfect/
├── app/
│   ├── page.tsx                  # Landing page
│   ├── demo/
│   │   └── trade/
│   │       └── page.tsx          # Main demo trade page
│   ├── agent/
│   │   └── page.tsx              # Guided Trade Builder (AI agent UI)
│   ├── learn/
│   │   └── page.tsx              # Learn page
│   └── analytics/
│       └── page.tsx              # M2 — sign-up + conversion dashboard
├── components/
│   ├── WalletBadge.tsx           # Wallet address + credit display in nav
│   ├── TradeBuilder/
│   │   ├── ThesisInput.tsx       # Free-text thesis entry
│   │   ├── BasketDisplay.tsx     # LONG/SHORT basket with weight sliders
│   │   └── SigningModal.tsx      # Simulated wallet confirm popup
│   ├── TradeResult.tsx           # Fill price, P&L, basket summary
│   ├── TradeHistory.tsx          # Past trades panel
│   ├── CreditTracker.tsx         # Persistent credit counter
│   └── UpgradeModal.tsx          # "Go to Pear" CTA modal at 0 credits
├── hooks/
│   ├── useWallet.ts              # Wallet state + generation trigger
│   ├── useCredits.ts             # Credit balance management
│   └── useTrade.ts               # Trade submission + result handling
├── lib/
│   ├── api.ts                    # Typed API client (see API_CONTRACT.md)
│   └── utm.ts                    # UTM param builder for "Go to Pear" link
└── types/
    └── index.ts                  # Shared TypeScript interfaces

---

Getting Started

git clone https://github.com/[your-handle]/pearfect
cd pearfect
npm install
cp .env.example .env.local
npm run dev

Environment Variables

NEXT_PUBLIC_API_BASE_URL=https://your-backend.railway.app
NEXT_PUBLIC_PEAR_URL=https://pear.garden

---

Frontend–Backend Coordination

Frontend is built against a typed API contract — see API_CONTRACT.md for full request/response shapes.

During parallel development, the frontend mocks all backend responses using the fixtures in /lib/mocks/. Switch to live endpoints by updating NEXT_PUBLIC_API_BASE_URL.

---

Demo Flow (M1 End-to-End)

Landing page
    ↓  "Start Demo" click
Burner wallet generated (auto, no user action needed)
    ↓
Agent page — type trade thesis
    ↓  POST /api/trade-builder
LONG/SHORT basket returned → weight sliders displayed
    ↓  "Execute Trade" click
Simulated signing modal
    ↓  "Confirm"
Trade result screen — fill price, P&L delta shown
Credits decremented → trade saved to history
    ↓  credits hit 0
"Upgrade to Pear" modal → UTM-tagged "Go to Pear" CTA

---