Web3 development using MetaMask Smart Accounts Kit. Use when the user wants to build dApps with ERC-4337 smart accounts, send user operations, batch transactions, configure signers (EOA, passkey, multisig), implement gas abstraction with paymasters, create delegations, or request advanced permissions (ERC-7715). Supports Viem integration, multiple signer types (Dynamic, Web3Auth, Wagmi), gasless transactions, and the Delegation Framework.
This skill file provides quick access to the MetaMask Smart Accounts Kit v0.3.0. For detailed information, refer to the specific reference files.
📚 Detailed References:
npm install @metamask/[email protected]
For custom caveat enforcers:
forge install metamask/[email protected]
Three implementation types:
Implementation.Hybrid) - EOA + passkey signersImplementation.MultiSig) - Multiple signers with thresholdImplementation.Stateless7702) - EIP-7702 upgraded EOAGrant permissions from delegator to delegate:
Request permissions via MetaMask extension:
import { Implementation, toMetaMaskSmartAccount } from '@metamask/smart-accounts-kit'
import { privateKeyToAccount } from 'viem/accounts'
const account = privateKeyToAccount('0x...')
const smartAccount = await toMetaMaskSmartAccount({
client: publicClient,
implementation: Implementation.Hybrid,
deployParams: [account.address, [], [], []],
deploySalt: '0x',
signer: { account },
})
import { createDelegation } from '@metamask/smart-accounts-kit'
import { parseUnits } from 'viem'
const delegation = createDelegation({
to: delegateAddress,
from: delegatorSmartAccount.address,
environment: delegatorSmartAccount.environment,
scope: {
type: 'erc20TransferAmount',
tokenAddress: '0x1c7D4B196Cb0C7B01d743Fbc6116a902379C7238',
maxAmount: parseUnits('10', 6),
},
caveats: [
{ type: 'timestamp', afterThreshold: now, beforeThreshold: expiry },
{ type: 'limitedCalls', limit: 5 },
],
})
const signature = await smartAccount.signDelegation({ delegation })
const signedDelegation = { ...delegation, signature }
import { createExecution, ExecutionMode } from '@metamask/smart-accounts-kit'
import { DelegationManager } from '@metamask/smart-accounts-kit/contracts'
import { encodeFunctionData, erc20Abi } from 'viem'
const callData = encodeFunctionData({
abi: erc20Abi,
args: [recipient, parseUnits('1', 6)],
functionName: 'transfer',
})
const execution = createExecution({ target: tokenAddress, callData })
const redeemCalldata = DelegationManager.encode.redeemDelegations({
delegations: [[signedDelegation]],
modes: [ExecutionMode.SingleDefault],
executions: [[execution]],
})
// Via smart account
const userOpHash = await bundlerClient.sendUserOperation({
account: delegateSmartAccount,
calls: [{ to: delegateSmartAccount.address, data: redeemCalldata }],
})
// Via EOA
const txHash = await delegateWalletClient.sendTransaction({
to: environment.DelegationManager,
data: redeemCalldata,
})
import { erc7715ProviderActions } from '@metamask/smart-accounts-kit/actions'
const walletClient = createWalletClient({
transport: custom(window.ethereum),
}).extend(erc7715ProviderActions())
const grantedPermissions = await walletClient.requestExecutionPermissions([
{
chainId: chain.id,
expiry: now + 604800,
signer: {
type: 'account',
data: { address: sessionAccount.address },
},
permission: {
type: 'erc20-token-periodic',
data: {
tokenAddress,
periodAmount: parseUnits('10', 6),
periodDuration: 86400,
justification: 'Transfer 10 USDC daily',
},
},
isAdjustmentAllowed: true,
},
])
// Smart account
import { erc7710BundlerActions } from '@metamask/smart-accounts-kit/actions'
const bundlerClient = createBundlerClient({
client: publicClient,
transport: http(bundlerUrl),
}).extend(erc7710BundlerActions())
const permissionsContext = grantedPermissions[0].context
const delegationManager = grantedPermissions[0].signerMeta.delegationManager
const userOpHash = await bundlerClient.sendUserOperationWithDelegation({
publicClient,
account: sessionAccount,
calls: [
{
to: tokenAddress,
data: calldata,
permissionsContext,
delegationManager,
},
],
})
// EOA
import { erc7710WalletActions } from '@metamask/smart-accounts-kit/actions'
const walletClient = createWalletClient({
account: sessionAccount,
chain,
transport: http(),
}).extend(erc7710WalletActions())
const txHash = await walletClient.sendTransactionWithDelegation({
to: tokenAddress,
data: calldata,
permissionsContext,
delegationManager,
})
toMetaMaskSmartAccount() - Create smart accountaggregateSignature() - Combine multisig signaturessignDelegation() - Sign delegationsignUserOperation() - Sign user operationsignMessage() / signTypedData() - Standard signingcreateDelegation() - Create delegation with delegatecreateOpenDelegation() - Create open delegationcreateCaveatBuilder() - Build caveats arraycreateExecution() - Create execution structredeemDelegations() - Encode redemption calldatasignDelegation() - Sign with private keygetSmartAccountsEnvironment() - Resolve environmentdeploySmartAccountsEnvironment() - Deploy contractsoverrideDeployedEnvironment() - Override environmenterc7715ProviderActions() - Wallet client extension for requestingrequestExecutionPermissions() - Request permissionserc7710BundlerActions() - Bundler client extensionsendUserOperationWithDelegation() - Redeem with smart accounterc7710WalletActions() - Wallet client extensionsendTransactionWithDelegation() - Redeem with EOA| Permission Type | Description |
|---|---|
erc20-token-periodic | Per-period limit that resets at each period |
erc20-token-streaming | Linear streaming with amountPerSecond rate |
| Permission Type | Description |
|---|---|
native-token-periodic | Per-period ETH limit that resets |
native-token-streaming | Linear ETH streaming with amountPerSecond rate |
| Scope | Description |
|---|---|
erc20TransferAmount | Fixed ERC-20 limit |
erc20PeriodTransfer | Per-period ERC-20 limit |
erc20Streaming | Linear streaming ERC-20 |
nativeTokenTransferAmount | Fixed native token limit |
nativeTokenPeriodTransfer | Per-period native token limit |
nativeTokenStreaming | Linear streaming native |
erc721Transfer | ERC-721 (NFT) transfer |
| Scope | Description |
|---|---|
functionCall | Specific methods/addresses allowed |
ownershipTransfer | Ownership transfers only |
allowedTargets - Limit callable addressesallowedMethods - Limit callable methodsallowedCalldata - Validate specific calldataexactCalldata / exactCalldataBatch - Exact calldata matchexactExecution / exactExecutionBatch - Exact execution matchvalueLte - Limit native token valueerc20TransferAmount - Limit ERC-20 amounterc20BalanceChange - Validate ERC-20 balance changeerc721Transfer / erc721BalanceChange - ERC-721 restrictionserc1155BalanceChange - ERC-1155 validationtimestamp - Valid time range (seconds)blockNumber - Valid block rangelimitedCalls - Limit redemption counterc20PeriodTransfer / erc20Streaming - Time-based ERC-20nativeTokenPeriodTransfer / nativeTokenStreaming - Time-based nativeredeemer - Limit redemption to specific addressesid - One-time delegation with IDnonce - Bulk revocation via noncedeployed - Auto-deploy contractownershipTransfer - Ownership transfer onlynativeTokenPayment - Require paymentnativeBalanceChange - Validate native balancemultiTokenPeriod - Multi-token period limits| Mode | Chains | Processing | On Failure |
|---|---|---|---|
SingleDefault | One | Sequential | Revert |
SingleTry | One | Sequential | Continue |
BatchDefault | Multiple | Interleaved | Revert |
BatchTry | Multiple | Interleaved | Continue |
| Contract | Address |
|---|---|
| EntryPoint | 0x0000000071727De22E5E9d8BAf0edAc6f37da032 |
| SimpleFactory | 0x69Aa2f9fe1572F1B640E1bbc512f5c3a734fc77c |
| DelegationManager | 0xdb9B1e94B5b69Df7e401DDbedE43491141047dB3 |
| MultiSigDeleGatorImpl | 0x56a9EdB16a0105eb5a4C54f4C062e2868844f3A7 |
| HybridDeleGatorImpl | 0x48dBe696A4D990079e039489bA2053B36E8FFEC4 |
valueLte)const delegation = createDelegation({
to: delegate,
from: delegator,
environment,
scope: {
type: 'erc20TransferAmount',
tokenAddress,
maxAmount: parseUnits('100', 6),
},
caveats: [
{ type: 'timestamp', afterThreshold: now, beforeThreshold: expiry },
{ type: 'limitedCalls', limit: 10 },
{ type: 'redeemer', redeemers: [delegate] },
],
})
const delegation = createDelegation({
to: delegate,
from: delegator,
environment,
scope: {
type: 'functionCall',
targets: [contractAddress],
selectors: ['transfer(address,uint256)'],
valueLte: { maxValue: parseEther('0.1') },
},
caveats: [{ type: 'allowedMethods', selectors: ['transfer(address,uint256)'] }],
})
const delegation = createDelegation({
to: delegate,
from: delegator,
environment,
scope: {
type: 'nativeTokenPeriodTransfer',
periodAmount: parseEther('0.01'),
periodDuration: 86400,
startDate: now,
},
})
// Alice → Bob (100 USDC)
const aliceToBob = createDelegation({
to: bob,
from: alice,
environment,
scope: { type: 'erc20TransferAmount', tokenAddress, maxAmount: parseUnits('100', 6) },
})
// Bob → Carol (50 USDC, subset of authority)
const bobToCarol = createDelegation({
to: carol,
from: bob,
environment,
scope: { type: 'erc20TransferAmount', tokenAddress, maxAmount: parseUnits('50', 6) },
parentDelegation: aliceToBob,
caveats: [{ type: 'timestamp', afterThreshold: now, beforeThreshold: expiry }],
})
| Issue | Solution |
|---|---|
| Account not deployed | Use bundlerClient.sendUserOperation() to deploy |
| Invalid signature | Verify chain ID, delegation manager, signer permissions |
| Caveat enforcer reverted | Check caveat parameters match execution, verify order |
| Redemption failed | Check delegator balance, calldata validity, target contracts |
| ERC-7715 not working | Upgrade to Flask 13.5.0+, ensure user has smart account |
| Permission denied | Handle gracefully, provide manual fallback |
| Threshold not met | Add more signers for multisig |
| 7702 not working | Confirm EOA upgraded via EIP-7702 first |
@metamask/smart-accounts-kitmetamask/[email protected]For detailed documentation, see the reference files in the /references directory.