Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.chipipay.com/llms.txt

Use this file to discover all available pages before exploring further.

Overview

WebAuthn passkeys replace PINs with biometric authentication (Face ID, Touch ID, Windows Hello). No PINs to remember or store.

Prerequisites

  • Next.js 13+ with App Router
  • Modern browser with WebAuthn support
  • Biometric hardware (fingerprint, face recognition)
  • Chipi Next.js SDK installed

Installation

npm install @chipi-stack/chipi-passkey

Basic Implementation

1

Create wallet with passkey

"use client";
import { useCreateWallet, Chain } from "@chipi-stack/nextjs";
import { usePasskeySetup } from "@chipi-stack/chipi-passkey/hooks";
2

Authenticate with passkey

"use client";
import { useTransfer, ChainToken } from "@chipi-stack/nextjs";
import { usePasskeyAuth } from "@chipi-stack/chipi-passkey/hooks";
3

Migrate existing wallet (optional)

If users already have a PIN-based wallet, they can migrate to passkey:
"use client";
import { useMigrateWalletToPasskey } from "@chipi-stack/nextjs";

Example

"use client";

import { useCreateWallet } from '@chipi-stack/nextjs';
import { usePasskeySetup } from '@chipi-stack/chipi-passkey/hooks';
import { useState } from 'react';

export function CreateWalletWithPasskey({ userId }: { userId: string }) {
  const { createWalletAsync, isLoading, error } = useCreateWallet();
  const { setupPasskey } = usePasskeySetup();
  const [wallet, setWallet] = useState(null);

  const handleCreate = async () => {
    try {
      // Triggers biometric prompt — requires userId and display name
      const { encryptKey, credentialId } = await setupPasskey(userId, userId);

      // Create wallet with passkey-derived key
      // Do NOT pass usePasskey: true — setupPasskey already handled it
      const result = await createWalletAsync({
        params: {
          encryptKey,
          externalUserId: userId,
          chain: Chain.STARKNET,
        },
        bearerToken: 'your-jwt-token',
      });

      // Result is flat — publicKey is at top level, not nested under .wallet
      localStorage.setItem('wallet', JSON.stringify(result));
      localStorage.setItem('credentialId', credentialId);
      setWallet(result);
    } catch (err) {
      console.error(err);
    }
  };

  return (
    <div className="p-6 bg-white rounded-lg shadow">
      <button
        onClick={handleCreate}
        disabled={isLoading}
        className="px-4 py-2 bg-green-600 text-white rounded disabled:bg-gray-400"
      >
        {isLoading ? 'Creating...' : 'Create Wallet with Passkey'}
      </button>
      {error && <p className="text-red-600 mt-2">Error: {error.message}</p>}
      {wallet && (
        <p className="text-sm mt-4 font-mono">
          Wallet created: {wallet.publicKey}
        </p>
      )}
    </div>
  );
}

Hooks Reference

HookPackagePurpose
usePasskeySetup@chipi-stack/chipi-passkey/hooksCreate new passkey
usePasskeyAuth@chipi-stack/chipi-passkey/hooksAuthenticate with existing passkey
usePasskeyStatus@chipi-stack/chipi-passkey/hooksCheck passkey support & status
useMigrateWalletToPasskey@chipi-stack/nextjsMigrate from PIN to passkey

Browser Support

  • ✅ Chrome 67+ (Desktop & Android)
  • ✅ Safari 14+ (iOS 14+, macOS)
  • ✅ Firefox 60+ (Desktop)
  • ✅ Edge 18+ (Desktop)
Passkeys are stored in the browser and synced via platform (iCloud Keychain, Google Password Manager).

Security Benefits

  • No PINs stored - Keys derived on-demand from biometric
  • Platform-level security - Hardware-backed authentication
  • Phishing resistant - Domain-bound credentials
  • User convenience - One tap authentication

Next Steps