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