> ## 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.

# useChipiWallet

> All-in-one hook for wallet management - combines wallet fetching, creation, and balance checking into a single unified API.

## Overview

`useChipiWallet` is a convenience hook that simplifies wallet management by combining multiple operations into one:

* **Wallet fetching** (replaces `useGetWallet`)
* **Wallet creation** (replaces `useCreateWallet`)
* **Balance checking** (replaces `useGetTokenBalance`)

Use this hook when you want a streamlined API. Use the individual hooks (`useGetWallet`, `useCreateWallet`, `useGetTokenBalance`) when you need more granular control.

## Quick Start

```typescript theme={null}
import { useAuth } from "@clerk/nextjs";
import { useChipiWallet } from "@chipi-stack/nextjs";

function WalletComponent() {
  const { userId, getToken } = useAuth();
  
  const {
    wallet,
    hasWallet,
    balance,
    formattedBalance,
    createWallet,
    isCreating,
    isLoadingWallet,
  } = useChipiWallet({
    externalUserId: userId,
    getBearerToken: getToken,
  });

  if (isLoadingWallet) return <div>Loading...</div>;

  if (!hasWallet) {
    return (
      <button 
        onClick={() => createWallet({ encryptKey: "1234" })}
        disabled={isCreating}
      >
        {isCreating ? "Creating..." : "Create Wallet"}
      </button>
    );
  }

  return (
    <div>
      <p>Address: {wallet?.shortAddress}</p>
      <p>Balance: ${formattedBalance} USDC</p>
    </div>
  );
}
```

## Configuration Options

```typescript theme={null}
interface UseChipiWalletConfig {
  // Required
  externalUserId: string | null | undefined;
  getBearerToken: () => Promise<string | null | undefined>;
  
  // Optional
  defaultToken?: ChainToken;  // Default: "USDC"
  enabled?: boolean;          // Default: true
}
```

| Option | Type | Default | Description |
| - | - | - | - |
| `externalUserId` | `string \| null` | Required | User ID from your auth provider (Clerk, Firebase, etc.) |
| `getBearerToken` | `() => Promise<string>` | Required | Function to get the auth token |
| `defaultToken` | `ChainToken` | `"USDC"` | Token to fetch balance for |
| `enabled` | `boolean` | `true` | Whether to fetch wallet on mount |

## Return Values

### Wallet Data

| Property | Type | Description |
| - | - | - |
| `wallet` | `ChipiWalletData \| null \| undefined` | Wallet data with computed properties |
| `hasWallet` | `boolean` | Whether the user has a wallet |
| `isLoadingWallet` | `boolean` | Wallet fetch loading state |
| `walletError` | `Error \| null` | Any error from fetching |

### Balance Data

| Property | Type | Description |
| - | - | - |
| `balance` | `GetTokenBalanceResponse \| undefined` | Raw balance data |
| `formattedBalance` | `string` | Formatted balance (e.g., "1,234.56") |
| `isLoadingBalance` | `boolean` | Balance fetch loading state |

### Create Wallet

| Property | Type | Description |
| - | - | - |
| `createWallet` | `(params) => Promise<CreateWalletResponse>` | Create a new wallet |
| `isCreating` | `boolean` | Creation loading state |
| `createdWallet` | `CreateWalletResponse \| undefined` | Last created wallet data |

### Actions

| Method | Description |
| - | - |
| `refetchWallet()` | Refetch wallet data |
| `refetchBalance()` | Refetch balance data |
| `refetchAll()` | Refetch both wallet and balance |

## Computed Wallet Properties

The `wallet` object includes these computed properties:

```typescript theme={null}
interface ChipiWalletData extends GetWalletResponse {
  supportsSessionKeys: boolean;  // true for CHIPI wallets
  shortAddress: string;          // Truncated address for display
}
```

## Example: Full Implementation with Clerk

```tsx theme={null}
"use client";

import { useState } from "react";
import { useAuth, SignInButton, SignedIn, SignedOut } from "@clerk/nextjs";
import { useChipiWallet } from "@chipi-stack/nextjs";

export function WalletDashboard() {
  const { userId, getToken } = useAuth();
  const [pin, setPin] = useState("");
  
  const {
    wallet,
    hasWallet,
    formattedBalance,
    createWallet,
    isCreating,
    isLoadingWallet,
    refetchAll,
  } = useChipiWallet({
    externalUserId: userId,
    getBearerToken: getToken,
  });

  const handleCreateWallet = async (walletType: "CHIPI" | "READY") => {
    if (!pin || pin.length < 4) {
      alert("Please enter a 4-digit PIN");
      return;
    }
    
    try {
      const result = await createWallet({
        encryptKey: pin,
        walletType,
      });
      alert(`Wallet created! Address: ${result.publicKey}`);
    } catch (err) {
      console.error(err);
      alert("Failed to create wallet");
    }
  };

  return (
    <div className="p-6 space-y-6">
      <SignedOut>
        <SignInButton mode="modal">
          <button className="btn">Sign In</button>
        </SignInButton>
      </SignedOut>
      
      <SignedIn>
        {isLoadingWallet ? (
          <p>Loading wallet...</p>
        ) : hasWallet ? (
          <div className="space-y-4">
            <div>
              <p className="text-sm text-gray-500">Wallet Address</p>
              <p className="font-mono">{wallet?.shortAddress}</p>
            </div>
            
            <div>
              <p className="text-sm text-gray-500">Balance</p>
              <p className="text-3xl font-bold">${formattedBalance} USDC</p>
            </div>
            
            <div>
              <p className="text-sm text-gray-500">Session Keys</p>
              <p>{wallet?.supportsSessionKeys ? "Supported" : "Not Supported"}</p>
            </div>
            
            <button onClick={() => refetchAll()} className="btn-secondary">
              Refresh
            </button>
          </div>
        ) : (
          <div className="space-y-4">
            <input
              type="password"
              placeholder="Enter 4-digit PIN"
              value={pin}
              onChange={(e) => setPin(e.target.value)}
              maxLength={4}
              className="input"
            />
            
            <div className="flex gap-2">
              <button
                onClick={() => handleCreateWallet("CHIPI")}
                disabled={isCreating}
                className="btn-primary"
              >
                Create Chipi Wallet
              </button>
              
              <button
                onClick={() => handleCreateWallet("READY")}
                disabled={isCreating}
                className="btn-secondary"
              >
                Create Argent Wallet
              </button>
            </div>
          </div>
        )}
      </SignedIn>
    </div>
  );
}
```

## Wallet Types

When creating a wallet, you can specify the type:

| Type | Session Keys | Description |
| - | - | - |
| `CHIPI` | ✅ Yes | OpenZeppelin account with SNIP-9 session key support |
| `READY` | ❌ No | Argent X compatible wallet |

```typescript theme={null}
// Create a CHIPI wallet (supports session keys)
await createWallet({
  encryptKey: pin,
  walletType: "CHIPI",
});

// Create a READY wallet (no session keys)
await createWallet({
  encryptKey: pin,
  walletType: "READY",
});
```

## Migration from Individual Hooks

If you're currently using separate hooks, here's how to migrate:

### Before

```typescript theme={null}
const { data: wallet, isLoading } = useGetWallet({
  params: { externalUserId: userId },
  getBearerToken: getToken,
  enabled: !!userId,
});

const { createWalletAsync } = useCreateWallet();

const { data: balance } = useGetTokenBalance({
  params: { walletPublicKey: wallet?.publicKey, ... },
  getBearerToken: getToken,
  enabled: !!wallet?.publicKey,
});
```

### After

```typescript theme={null}
const {
  wallet,
  hasWallet,
  balance,
  formattedBalance,
  createWallet,
  isLoadingWallet,
} = useChipiWallet({
  externalUserId: userId,
  getBearerToken: getToken,
});
```

> [!NOTE]
>
> `useChipiWallet` automatically handles the dependency chain - it only fetches balance after the wallet is loaded.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.