Getting Started with Next.js

Build a StarkNet-powered app with Next.js and Chipi. Full App Router setup with gasless wallets, USDC transfers, and passkey authentication.

Overview

Next.js with App Router is the recommended stack for building with Chipi. The @chipi-stack/nextjs package provides React hooks for wallets, transfers, staking, session keys, and more. All gasless. Server components handle metadata and layout, while client components handle wallet interactions.

Create Your Project

Create a new Next.js project and install the Chipi SDK:

bashnpx create-next-app@latest my-app --typescript --tailwind --app --src-dir
cd my-app
npm install @chipi-stack/nextjs@latest

The SDK requires React 18+ and the App Router (app/ directory).

Install an Auth Provider

Chipi ties each wallet to an authenticated user. Install your auth provider:

  • - Clerk (recommended): npm install @clerk/nextjs. Drop-in auth with email, Google, and passkeys
  • - Firebase: npm install firebase. Google's auth platform with phone, email, and social sign-in
  • - Supabase: npm install @supabase/supabase-js @supabase/auth-helpers-nextjs. Open-source auth with PostgreSQL
  • - Better Auth: npm install better-auth. Lightweight, framework-agnostic auth

No auth = no wallet. Each authenticated user gets their own self-custody wallet.

Configure Providers

Wrap your app with ChipiProvider in app/layout.tsx. This initializes the SDK context so all child components can use wallet hooks.

tsx// app/layout.tsx
import { ChipiProvider } from "@chipi-stack/nextjs";
import { ClerkProvider } from "@clerk/nextjs";

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en">
      <body>
        <ClerkProvider>
          <ChipiProvider>
            {children}
          </ChipiProvider>
        </ClerkProvider>
      </body>
    </html>
  );
}

Use the MCP tool get_component_code("chipi-providers") for the exact wrapper matching your auth setup.

Set Environment Variables

Create a .env.local file with your API keys:

bash# Chipi API keys. From dashboard.chipipay.com
NEXT_PUBLIC_CHIPI_API_KEY=pk_prod_YOUR_KEY
CHIPI_SECRET_KEY=sk_prod_YOUR_KEY

# Clerk auth (or your provider)
NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY=pk_YOUR_CLERK_KEY
CLERK_SECRET_KEY=sk_YOUR_CLERK_KEY

Keys starting with pk_prod_ are public (safe for frontend). Keys starting with sk_prod_ are secret (backend/webhooks only. Never expose to client code).

Add Wallet Creation

Use the CreateWalletDialog component for the wallet creation flow. Get the full component code via the MCP:

get_component_code("create-wallet-dialog")

Defaults:

  • - walletType: "CHIPI". Chipi's own account contract with session key support
  • - usePasskey: true. Hardware-backed security using the device's fingerprint or face sensor

The component auto-detects WebAuthn PRF support. If supported, the user chooses between passkey (recommended) and PIN. If not, it falls back to PIN-only.

Add Wallet Summary and Transfers

Wire the wallet page together with useChipiWallet:

tsx"use client";
import { useChipiWallet } from "@chipi-stack/nextjs";

export default function WalletPage() {
  const { wallet, hasWallet, formattedBalance } = useChipiWallet({
    externalUserId: user.id,
    getBearerToken: async () => process.env.NEXT_PUBLIC_CHIPI_API_KEY!,
  });

  if (!hasWallet) return <CreateWalletDialog />;
  return (
    <>
      <WalletSummary wallet={wallet} />
      <SendUsdcDialog wallet={wallet} />
    </>
  );
}

Get the full component code for WalletSummary and SendUsdcDialog via the MCP tools get_component_code("wallet-summary") and get_component_code("send-usdc-dialog").

Test and Next Steps

Start the dev server and test the wallet flow:

bashnpm run dev
  1. Sign in with your auth provider
  2. Create a wallet with passkey
  3. View the wallet address and balance
  4. Try a USDC transfer

Once the basics work, add more features: USDC payments, DeFi staking via VESU, session keys for frictionless UX, custom contract calls, or a digital services marketplace.

Ready to build?

Connect the Chipi MCP server and start building in minutes.

Get Started