Overview
By default, the SDK creates CHIPI wallets (OpenZeppelin account with SNIP-9 session keys) or READY wallets (Argent X v0.4.0). You can also pass a custom classHash to deploy any StarkNet account that implements SNIP-9.
When to Use Custom Class Hashes
- Your project has a custom account contract with special features (spending limits, social recovery, multisig)
- You need a specific audited account version (e.g., CHIPI v33 with spending policy)
- You’re building on top of an account standard not yet included in the SDK defaults
Requirements
Your custom account must:
| Requirement | Standard | Why |
|---|
| Be declared on StarkNet mainnet | starknet_getClass returns the class | SDK computes the wallet address from the class hash |
| Implement SRC-6 | __validate__, __execute__ | Standard StarkNet account interface |
| Implement SNIP-9 v2 | execute_from_outside_v2 | Required for Chipi paymaster to sponsor gas |
Accounts without SNIP-9 support cannot use the Chipi paymaster. Transactions will fail at estimation with TRANSACTION_EXECUTION_ERROR.
Creating a Wallet with Custom Class Hash
const wallet = await serverClient.createWallet({
params: {
encryptKey: "user-pin",
externalUserId: "user-123",
chain: "STARKNET",
classHash: "0x0484bbd2404b3c7264bea271f7267d6d4004821ac7787a9eed7f472e79ef40d1",
},
});
classHash is provided:
- The SDK uses your class hash instead of the default CHIPI or READY hash
- The wallet address is computed from your class hash + constructor calldata
- The Chipi paymaster sponsors the deployment (if your account supports SNIP-9)
Known Compatible Class Hashes
| Account | Version | Class Hash | Features |
|---|
| CHIPI (default) | v29 | 0x053f4f8...459f2a | Session keys, passkeys, SNIP-9 v2 |
| CHIPI | v33 | 0x0484bbd...f40d1 | + Spending policy, audit fixes |
| READY (Argent X) | v0.4.0 | 0x036078...927f | Argent X compatible, SNIP-9 v2 |
Upgrading Custom Wallets
Custom wallets can be upgraded to newer class hashes using the wallet upgrade flow:
const upgrade = await serverClient.prepareWalletUpgrade({
publicKey: wallet.publicKey,
targetClassHash: "0x<new-class-hash>",
});
Feature Compatibility
| Feature | CHIPI | READY | Custom (SNIP-9) |
|---|
| Gasless transactions | Yes | Yes | Yes |
| Session keys | Yes | No | Depends on contract |
| Passkey auth | Yes | No | Depends on contract |
| Wallet upgrade | Yes | Yes | Yes |
| x402 payments | Yes | Yes | Yes |
