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

# useCreateWallet

> Creates a new Argent-compatible wallet on StarkNet. This hook deploys the wallet contract behind the scenes and uses Avnus gasless to sponsor gas fees, resulting in a frictionless onboarding experience.

## Usage

```typescript theme={null}
const { createWalletAsync, data, isLoading, error } = useCreateWallet();
```

### Parameters

The mutation accepts an object with:

* `params` (`CreateWalletParams`):
  * `encryptKey` (string): PIN or passkey-derived key used to encrypt the private key
  * `externalUserId` (string): Your application's unique identifier for the user
  * `chain` (`Chain`): The blockchain network. Use `Chain.STARKNET`
  * `walletType` (`"SHHH" | "CHIPI" | "READY"`, optional): **defaults to `"SHHH"`** (the pluggable-signer ShhhAccount — guardian recovery, multisig). `"CHIPI"` is the legacy account that supports session keys; `"READY"` is Argent X compatible. Whatever you create here, persist `walletType` (and `signerKind`) and pass them back on every transfer/approve/call.
  * `usePasskey` (boolean, optional): Set `true` when `encryptKey` was derived from a passkey (via `@chipi-stack/chipi-passkey`)
* `bearerToken` (string): Bearer token for authentication

### Return Value

Returns an object containing:

* `createWallet`: Function to trigger wallet creation (fire-and-forget)
* `createWalletAsync`: Promise-based function that resolves with the wallet data
* `data`: The created wallet (`CreateWalletResponse`) — flat object with `publicKey`, `encryptedPrivateKey`, `walletType`, `chain`, etc.
* `isLoading`: Boolean indicating if the operation is in progress
* `isError`: Boolean indicating if an error occurred
* `error`: Error instance when `isError` is true, otherwise `null`
* `isSuccess`: Boolean indicating if wallet creation succeeded
* `reset`: Function to reset the mutation state

## Example Implementation

```typescript theme={null}
import { useState } from "react";
import { useAuth } from "@clerk/nextjs";
import { useCreateWallet, Chain } from "@chipi-stack/nextjs";

export function CreateWallet() {
  const { userId, getToken } = useAuth();
  const {
    createWalletAsync,
    data,
    isLoading,
    error
  } = useCreateWallet();

  const [pin, setPin] = useState('');

  const handleSubmit = async (e: React.FormEvent) => {
    e.preventDefault();
    const bearerToken = await getToken();
    if (!bearerToken || !userId) {
      console.error('No bearer token or user ID available');
      return;
    }
    try {
      const wallet = await createWalletAsync({
        params: {
          encryptKey: pin,
          externalUserId: userId,
          chain: Chain.STARKNET,
          // Omit walletType to get the default SHHH account, or set it
          // explicitly. Use "CHIPI" only if you need legacy session keys.
          walletType: "SHHH",
        },
        bearerToken,
      });
      alert('Wallet created successfully!');
    } catch (err) {
      console.error('Wallet creation failed:', err);
    }
  };

  return (
    <div className="bg-white rounded-lg shadow-md p-6">
      <h2 className="text-xl font-semibold mb-4">Create New Wallet</h2>

      <form onSubmit={handleSubmit} className="space-y-4">
        <div>
          <label className="block text-sm font-medium text-gray-700">
            Set PIN Code
          </label>
          <input
            type="password"
            value={pin}
            onChange={(e) => setPin(e.target.value)}
            className="mt-1 block w-full rounded-md border-gray-300 shadow-sm focus:border-green-500 focus:ring-green-500"
            required
            minLength={4}
          />
        </div>

        <button
          type="submit"
          disabled={isLoading}
          className="w-full bg-green-600 text-white py-2 px-4 rounded-md hover:bg-green-700 disabled:bg-gray-400"
        >
          {isLoading ? 'Creating...' : 'Create Wallet'}
        </button>
      </form>

      {error && (
        <div className="mt-4 p-3 bg-red-50 text-red-700 rounded-md">
          Error: {error.message}
        </div>
      )}

      {data && (
        <div className="mt-6">
          <div className="flex items-center justify-between mb-2">
            <h3 className="text-sm font-semibold">Wallet Details</h3>
            <a
              href={`https://starkscan.co/contract/${data.publicKey}`}
              target="_blank"
              rel="noopener"
              className="text-green-600 hover:text-green-800 text-sm flex items-center gap-1"
            >
              View Contract
              <svg className="w-4 h-4" fill="none" stroke="currentColor" viewBox="0 0 24 24">
                <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={2} d="M10 6H6a2 2 0 00-2 2v10a2 2 0 002 2h10a2 2 0 002-2v-4M14 4h6m0 0v6m0-6L10 14" />
              </svg>
            </a>
          </div>
          <div className="space-y-2">
            <p className="text-sm">
              <span className="font-medium">Address:</span>
              <span className="ml-2 font-mono break-all">
                {data.publicKey}
              </span>
            </p>
          </div>
        </div>
      )}
    </div>
  );
}
```

## Security Considerations

* PINs should always be collected client-side
* Never log or store raw PIN values
* Use secure encryption before any transmission
* Store encrypted private key securely
* Associate with user session (not persistent storage)

## Error Handling

* Catch and handle RPC connection errors
* Monitor gasless API limits
* Implement retry logic for failed deployments

<Note>
  Wallet creation is free! Gas fees are covered by our gasless integration.
</Note>