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

# createWallet

> Creates a new wallet on StarkNet. Deploys the wallet contract and sponsors gas fees via the Chipi paymaster, resulting in a frictionless onboarding experience.

<Warning>
  **PIN is weak — not recommended for production.**

  A user-typed PIN is a short, low-entropy string. Anyone who shoulder-surfs the PIN, observes a phishing form, or compromises the browser at typing time can decrypt the wallet's private key. PIN remains in the SDK only as a fallback recovery surface for users who lose access to their platform authenticator.

  **Production embedded-wallet apps should default to a platform passkey** (Touch ID, Face ID, Windows Hello, Android biometrics) via the `@chipi-stack/chipi-passkey` package. For SHHH V8.4 wallets, `signerKind: "WEBAUTHN_P256"` keeps the private key inside the platform authenticator — it never leaves the device, never reaches Chipi servers, and is never derived from a user-typed secret.

  Only prompt for a PIN as the encryption key when:

  * The user explicitly opted into a PIN-only flow (e.g. cold-storage / paper-backup recovery), or
  * The platform genuinely has no WebAuthn / biometric support available.

  If you are migrating an existing PIN-based wallet to a passkey, look up `useMigrateWalletToPasskey` in your framework's hook docs.
</Warning>

## Usage

```typescript theme={null}
// Default CHIPI wallet (session keys, passkey support)
const newWallet = await serverClient.createWallet({
  params: {
    encryptKey: "user-secure-pin",
    externalUserId: "your-user-id-123",
    chain: Chain.STARKNET,
  },
});

// READY wallet (Argent X compatible, no session keys)
const readyWallet = await serverClient.createWallet({
  params: {
    encryptKey: "user-secure-pin",
    externalUserId: "your-user-id-456",
    chain: Chain.STARKNET,
    walletType: "READY",
  },
});

// Custom account implementation (advanced)
const customWallet = await serverClient.createWallet({
  params: {
    encryptKey: "user-secure-pin",
    externalUserId: "your-user-id-789",
    chain: Chain.STARKNET,
    classHash: "0x0484bbd2404b3c7264bea271f7267d6d4004821ac7787a9eed7f472e79ef40d1",
  },
});
```

### Parameters

| Parameter        | Type    | Required | Description                                                                                                                                                                                                  |
| ---------------- | ------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `encryptKey`     | string  | Yes      | User-defined code or password to encrypt the wallet's private key                                                                                                                                            |
| `externalUserId` | string  | Yes      | Your application's unique identifier for the user                                                                                                                                                            |
| `chain`          | `Chain` | Yes      | Blockchain network. Use `Chain.STARKNET`                                                                                                                                                                     |
| `walletType`     | string  | No       | `"CHIPI"` (default) or `"READY"`. CHIPI supports session keys and passkeys. READY is Argent X compatible.                                                                                                    |
| `classHash`      | string  | No       | Custom StarkNet class hash for the wallet contract. Overrides the default for the wallet type. Must be declared on mainnet and implement SNIP-9. See [Custom Wallet Types](/sdk/guides/custom-wallet-types). |
| `usePasskey`     | boolean | No       | Use WebAuthn passkey for encryption instead of PIN                                                                                                                                                           |

### Return Value

Returns a Promise that resolves to an object containing:

* `publicKey`: The wallet's StarkNet address
* `encryptedPrivateKey`: The encrypted private key (store securely)
* `walletType`: The wallet type that was created
* `classHash`: The class hash used for deployment

## Example Implementation

```typescript theme={null}
import { ChipiServerSDK, Chain } from "@chipi-stack/backend";

const serverClient = new ChipiServerSDK({
  apiPublicKey: process.env.CHIPI_PUBLIC_KEY!,
  apiSecretKey: process.env.CHIPI_SECRET_KEY!,
});

async function createUserWallet(userId: string, userPin: string) {
  const newWallet = await serverClient.createWallet({
    params: {
      encryptKey: userPin,
      externalUserId: userId,
      chain: Chain.STARKNET,
    },
  });

  console.log("Wallet created:", newWallet.publicKey);

  // Store wallet data in your database
  await saveWalletToDatabase({
    userId,
    publicKey: newWallet.publicKey,
    encryptedPrivateKey: newWallet.encryptedPrivateKey,
  });

  return newWallet;
}
```

<Note>
  Wallet creation is free! Gas fees are sponsored by the Chipi paymaster for all wallet types.
</Note>

## Wallet Types

| Type    | Account               | Session Keys | Passkeys | Use Case                         |
| ------- | --------------------- | ------------ | -------- | -------------------------------- |
| `CHIPI` | OpenZeppelin + SNIP-9 | Yes          | Yes      | Default. Best for most apps.     |
| `READY` | Argent X v0.4.0       | No           | No       | Argent X ecosystem compatibility |
| Custom  | Any SNIP-9 account    | Depends      | Depends  | Advanced: bring your own account |

## Related Methods

* [getWallet](/sdk/backend/methods/get-wallet) - Retrieve existing wallet information
* [transfer](/sdk/backend/methods/transfer) - Send tokens from the created wallet
* [prepareWalletUpgrade](/sdk/backend/methods/prepare-wallet-upgrade) - Upgrade wallet to a different type
* [Custom Wallet Types Guide](/sdk/guides/custom-wallet-types) - Using custom account implementations