createWallet

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

// 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.
`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

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;
}

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
`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

getWallet - Retrieve existing wallet information
transfer - Send tokens from the created wallet
prepareWalletUpgrade - Upgrade wallet to a different type
Custom Wallet Types Guide - Using custom account implementations

Quickstart

Session Keys

Methods

Usage

Parameters

Return Value

Example Implementation

Wallet Types

​Usage

​Parameters

​Return Value

​Example Implementation

​Wallet Types

​Related Methods

Usage

Parameters

Return Value

Example Implementation

Wallet Types

Related Methods