Skip to main content

​
Overview

Smart wallets enable banks to create ERC-4337 compatible wallets for customers who have no existing wallet address. Each wallet deploys as a separate smart contract with dual-key architecture: customers control the owner key while your institution holds the guardian key for compliance operations. Banks provide only a customer identifier (email, customer ID, or name) - the system generates everything else including the wallet address and private keys. Your backend never stores customer private keys.

​
Architecture

Wallets deploy via CREATE2 for deterministic addresses, allowing you to compute wallet addresses before deployment. Each wallet uses a minimal proxy pattern pointing to a shared implementation contract, reducing deployment costs by 90% versus full contract deployment. The guardian key enables freeze operations, force transfers for court orders or compliance violations, and owner key recovery if customers lose access. The owner key signs normal transactions and retains full custody of assets under standard operation.

​
Deployment Process

​
Address Generation

Generate wallet components without requiring any existing wallet address. The system creates a random owner key pair, computes a deterministic salt, and predicts the final wallet address using CREATE2. Customer receives the private key and recovery phrase immediately—your backend never sees these credentials. 
POST /api/v1/wallets/generate-wallet-data
{
  "customerAddress": "[email protected]",
  "instanceId": "clx123..."
}
Note: customerAddress is a customer identifier (email, ID, or name), not a wallet address.

​
On-Chain Deployment

Deploy the wallet contract using guardian credentials and fund it with initial ETH for gas. The factory contract creates a minimal proxy, initializes owner and guardian addresses, and returns the deployed wallet address matching the predicted address from generation. 
POST /api/v1/wallets/create
{
  "customerAddress": "[email protected]",
  "instanceId": "clx123...",
  "ownerAddress": "0x1234...",
  "salt": "0x9abc...",
  "encryptedBackup": "base64_encoded_backup_data"
}
Deployment completes in a single transaction. Gas costs approximately 150,000 gas units per wallet.

​
Customer Workflow

  1. Bank initiates wallet creation - Provide customer identifier (email, ID, or name)
  2. System generates credentials - New wallet address and private keys created
  3. Customer receives backup - Private key and recovery phrase downloaded securely
  4. Bank deploys wallet - Smart contract deployed and optionally funded
  5. Customer uses wallet - Full control with owner key, bank retains guardian oversight
The customer identifier associates the smart wallet with your internal customer records. The generated smart wallet address becomes the customer’s on-chain identity.

​
Guardian Operations

​
Freeze and Unfreeze

Freeze wallets for regulatory compliance, suspicious activity investigation, or court order compliance. Frozen wallets reject all outgoing transactions from the owner key but accept incoming transfers. Guardian operations continue during freeze status. 
POST /api/v1/wallets/{walletAddress}/freeze
{
  "instanceId": "clx123..."
}
Unfreeze restores normal operation immediately with no time delay or additional approvals required.

​
Force Transfer

Execute transfers without owner signature for asset recovery, court-ordered seizures, or compliance violations. Supports both native ETH and ERC-20 token transfers with automatic balance verification. 
POST /api/v1/wallets/{walletAddress}/force-transfer
{
  "instanceId": "clx123...",
  "token": "0x...",
  "to": "0x...",
  "amount": "1000000000000000000"
}
Use token: null or omit the field for ETH transfers. Token amounts require raw values without decimal adjustment.

​
Owner Recovery

Change the owner address if customers lose their private keys. This operation transfers full control to a new owner key pair generated through the same process as initial deployment. The old owner key becomes permanently invalid after recovery completes.
Guardian operations execute immediately without owner consent. Implement internal approval workflows before enabling guardian features. All guardian actions create permanent audit logs with transaction hashes, executor addresses, and timestamps.

​
Security Model

Your backend never stores customer private keys. The generation process creates keys and provides them directly to customers through encrypted download. You store only the encrypted backup blob—decryption requires the customer identifier and instance credentials. The guardian private key remains on your secure backend infrastructure. Use hardware security modules or key management services for guardian key storage in production deployments. A compromised guardian key allows complete control over all wallets in that instance. Customer identifiers (email, ID, name) link smart wallets to your internal systems without exposing on-chain. The smart wallet address serves as the customer’s public blockchain identity.

​
Integration

Access wallet management through the customer detail panel in your issuer dashboard. The interface provides wallet status, balance display, freeze controls, force transfer forms, and transaction history with automated refresh. For programmatic access, use the Wallet Management API:
  • POST /api/v1/wallets/generate-wallet-data - Generate wallet credentials (requires customer identifier)
  • POST /api/v1/wallets/create - Deploy wallet contract
  • POST /api/v1/wallets/{address}/fund - Fund wallet with ETH
  • POST /api/v1/wallets/{address}/freeze - Freeze wallet operations
  • POST /api/v1/wallets/{address}/unfreeze - Restore wallet operations
  • POST /api/v1/wallets/{address}/force-transfer - Execute forced transfer
  • GET /api/v1/wallets/{address} - Retrieve wallet details and transactions
All endpoints require instance authentication through your API key. The customerAddress parameter accepts any customer identifier - not a blockchain address.

​
Use Cases

​
Onboarding New Customers

Create wallets for customers with no crypto experience. Provide only their email or customer ID - the system handles all blockchain complexity.

​
Retail Banking Integration

Link smart wallets to existing customer accounts using internal customer IDs. Customers access blockchain assets through familiar banking interfaces.

​
Compliance Requirements

Guardian controls ensure regulatory compliance while customers maintain asset ownership through their private keys.

​
Gas Optimization

Smart wallets support ERC-4337 account abstraction for gasless transactions. Configure a paymaster to sponsor customer transactions, eliminating the need for customers to hold ETH. Transaction batching reduces costs by executing multiple operations in a single transaction with shared overhead.

Customer Management

Return to customer management overview

API Reference

View complete API documentation