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.
useMigrateWalletToPasskey in your framework’s hook docs.Usage
// 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. |
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 addressencryptedPrivateKey: The encrypted private key (store securely)walletType: The wallet type that was createdclassHash: 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 |
|---|---|---|---|---|
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 - 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