Chipi Wallet Starter Template

A hackathon-ready starter to build crypto and wallet experiences on. Everything you need to go from zero to a working app is already wired up—auth, wallet creation, USDC balance, and payments—so you can focus on your idea instead of plumbing.

---

What’s in the box

• Authentication (Clerk) — Sign in, sign up, and user session out of the box.
• Chipi Wallet (Starknet + USDC) — Create a wallet with a 4-digit PIN, view balance, and send USDC.
• Pre-built UI components — Dialogs, forms, cards, and buttons so you can ship fast.
• Payments — “Pay with Chipi” and “Pay with external wallet” flows for checkout-style flows.

Use this as a base and extend it: add your own pages, flows, and product logic.

---

Quick start

1. Clone and install

cd starter-repo
npm install

2. Environment variables

You only need 5 env vars. Copy env.example to .env or .env.local and paste your values:

NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY=pk_test_...
CLERK_SECRET_KEY=sk_test_...

NEXT_PUBLIC_CHIPI_API_KEY=pk_prod_...
CHIPI_SECRET_KEY=sk_prod_...

• Clerk keys: dashboard.clerk.com → your application → API Keys.
• Chipi keys: dashboard.chipipay.com → get your publishable and secret keys.

Chipi dashboard — JWKS (required for gasless transactions)
Add the JWKS Endpoint from your auth provider so Chipi can authenticate gasless transactions. In dashboard.chipipay.com go to Configure → JWKS Endpoint and paste your provider’s JWKS URL (e.g. Clerk’s JWKS URL from your Clerk app settings).

Optional: add NEXT_PUBLIC_MERCHANT_WALLET=0x... if you use the “Pay with crypto” merchant flow.

3. Run the app

npm run dev

Open http://localhost:3000. Sign up, create a wallet, and try the built-in flows.

---

What’s already built

Feature	Where it lives	What it does
Sign in / Sign up	app/page.tsx + Clerk	Header and landing auth; user session
Create wallet	components/create-wallet.dialog.tsx	4-digit PIN, confirm PIN, create Starknet wallet
Wallet summary	components/wallet-summary.tsx	Short address, copy, USDC balance
Send USDC	components/send-usdc-dialog.tsx	Recipient + amount + PIN, then send
Pay with crypto	components/pay-with-crypto-card.tsx	Subtotal/total, Chipi wallet or external wallet
PIN entry	components/wallet-pin-dialog.tsx	Reusable 4-digit PIN for sensitive actions
UI primitives	components/ui/	Buttons, dialogs, forms, cards, inputs, etc.

Layout and providers (Clerk, Chipi, toasts) are set up in app/layout.tsx. The main dashboard logic is in app/page.tsx—good first place to tweak for your hack.

---

Project structure (where to look)

starter-repo/
├── app/
│   ├── layout.tsx          # Providers (Clerk, Chipi, Toaster)
│   ├── page.tsx            # Main dashboard: auth + wallet + demo pay
│   └── globals.css         # Theme and shadcn-style variables
├── components/
│   ├── create-wallet.dialog.tsx
│   ├── wallet-summary.tsx
│   ├── send-usdc-dialog.tsx
│   ├── wallet-pin-dialog.tsx
│   ├── pay-with-crypto-card.tsx
│   ├── pay-with-chipi.button.tsx
│   ├── pay-with-external-wallet-button.tsx
│   ├── usdc-balance.tsx
│   └── ui/                 # Reusable UI (button, dialog, form, card, …)
├── lib/
│   └── utils.ts            # cn() for classnames
├── middleware.ts           # Clerk auth middleware
└── next.config.ts

• New pages: add app/your-route/page.tsx and link from the dashboard or nav.
• New flows: reuse WalletPinDialog, SendUsdcDialog, or payment components and pass the right props.
• Styling: app/globals.css and Tailwind; UI components use CSS variables for theming.

---

Hackathon tips

• First run: Get env vars from Chipi and Clerk (both have free tiers), then run npm run dev and click through sign up → create wallet → send USDC so you see the full loop.
• Customize the dashboard: Edit app/page.tsx to add your product copy, extra actions, or navigation.
• Add new screens: Use the same layout and providers; add routes under app/ and reuse the existing components.
• Deploy: Push to GitHub and deploy to Vercel; add the same env vars in the project settings. Use Vercel’s preview URLs for demos and judging.

---

Tech stack

• Framework: Next.js 16 (App Router), TypeScript
• Auth: Clerk
• Wallet & USDC: Chipi (Starknet) via @chipi-stack/nextjs
• UI: Tailwind CSS, shadcn-style components (Radix, CVA)
• Forms: React Hook Form, Zod
• Toasts: Sonner

---

Need help?

• Chipi: Chipi Pay / Chipi Stack docs (or your hack’s Chipi handout).
• Clerk: Clerk Docs.
• Next.js: Next.js Docs.

---

Chipi Next.js SDK docs

See the full SDK documentation at:
👉 Chipi Next.js SDK Guide

Find code samples, usage patterns, advanced configuration, and troubleshooting.

---

Use this starter as the foundation—then build the experience that wins the room.