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

## Usage

```typescript theme={null}
// Default SHHH wallet (STARK signer, session keys)
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 | `"SHHH"` (default), `"CHIPI"` (legacy) or `"READY"`. SHHH with the default STARK signer and CHIPI support session keys. 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 | Only changes the error message when `encryptKey` is missing. The server SDK never creates a passkey: in the browser, `useCreateWallet` with `usePasskey: true` derives the key on the device. |
| `encryptKeyBackup` | string | No | A second key (e.g. a PIN) that encrypts a backup copy of the private key, stored as `encryptedPrivateKeyBackup` |
| `authMethod` | string | No | `"passkey"`, `"passkey+pin"` or `"pin"`, stored on the wallet row |
| `credentialId` | string | No | WebAuthn credential ID, stored so `getWallet` can return it on any device |
| `prfSupported` | boolean | No | Whether the passkey was created with WebAuthn PRF |

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

## Wallet Types

| Type | Account | Session Keys | Passkeys | Use Case |
| - | - | - | - | - |
| `SHHH` | V8.5 ShhhAccount (pluggable signer; V8.4 before 14.17.0) | Yes (STARK / ED25519 signer) | Yes | Default. |
| `CHIPI` | OpenZeppelin + SNIP-9 | Yes | Yes | Legacy (v29). |
| `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


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