For AI agents: a documentation index is available at /llms.txt. A markdown version of this page is available at the same URL with .md appended (or via Accept: text/markdown).
Skip to main content

MetaMask Smart Accounts API reference

The following API methods are related to creating, managing, and signing with MetaMask Smart Accounts.

aggregateSignature​

Aggregates multiple partial signatures into a single combined multisig signature.

Parameters​

NameTypeRequiredDescription
signaturesPartialSignature[]YesCollection of partial signatures provided by signers, to be merged into an aggregated signature.

Example​

import {
  bundlerClient,
  aliceSmartAccount,
  bobSmartAccount,
  aliceAccount,
  bobAccount,
} from './config.ts'
import { aggregateSignature } from '@metamask/smart-accounts-kit'

const userOperation = await bundlerClient.prepareUserOperation({
  account: aliceSmartAccount,
  calls: [
    {
      target: zeroAddress,
      value: 0n,
      data: '0x',
    },
  ],
})

const aliceSignature = await aliceSmartAccount.signUserOperation(userOperation)
const bobSignature = await bobSmartAccount.signUserOperation(userOperation)

const aggregatedSignature = aggregateSignature({
  signatures: [
    {
      signer: aliceAccount.address,
      signature: aliceSignature,
      type: 'ECDSA',
    },
    {
      signer: bobAccount.address,
      signature: bobSignature,
      type: 'ECDSA',
    },
  ],
})

encodeCalls​

Encodes calls for execution by a MetaMask smart account. If there's a single call directly to the smart account, it returns the call data directly. For multiple calls or calls to other addresses, it creates executions and encodes them for the smart account's execute function.

The execution mode is set to SingleDefault for a single call to other address, or BatchDefault for multiple calls.

Parameters​

NameTypeRequiredDescription
callsCall[]YesList of calls to be encoded.

Example​

import { smartAccount } from './config.ts'

const calls = [
  {
    to: zeroAddress,
    data: '0x',
    value: 0n,
  },
]

const executeCallData = await smartAccount.encodeCalls(calls)

getFactoryArgs​

Returns the factory address and factory data that can be used to deploy a smart account.

Example​

import { smartAccount } from './config.ts'

const { factory, factoryData } = await smartAccount.getFactoryArgs()

getNonce​

Returns the nonce for a smart account.

Parameters​

NameTypeRequiredDescription
keybigintNoThe nonce key to retrieve the nonce. Different keys maintain independent nonce sequences, enabling parallel user operation execution.

Example​

import { smartAccount } from './config.ts'

const nonce = await smartAccount.getNonce()

isDeployed​

Checks whether the MetaMask smart account has been deployed on the current chain.

Example​

import { smartAccount } from './config.ts'

const isDeployed = await smartAccount.isDeployed()

isValid7702Implementation​

Checks whether an EOAExternally owned account (EOA) A private-key-controlled account with no built-in programmable execution logic. has been upgraded to MetaMask smart account using EIP-7702.

Parameters​

NameTypeRequiredDescription
clientClientYesViem Client used to read the account's bytecode.
accountAddressAddressYesThe address to check for an EIP-7702 delegation.
environmentSmartAccountsEnvironmentYesEnvironment to resolve EIP7702StatelessDeleGatorImpl smart account address for the current chain.

Example​

import { isValid7702Implementation } from '@metamask/smart-accounts-kit/actions'
import { publicClient, environment, accountAddress } from './config.ts'

const isUpgraded = await isValid7702Implementation({
  client: publicClient,
  accountAddress,
  environment,
})

signDelegation​

Signs the delegation and returns the delegation signature.

Parameters​

NameTypeRequiredDescription
delegationOmit<Delegation, "signature">YesThe unsigned delegation object to sign.
chainIdnumberNoThe chain ID on which the Delegation Manager is deployed.

Example​

import {
  createDelegation,
  getSmartAccountsEnvironment,
  ScopeType,
} from '@metamask/smart-accounts-kit'
import { delegatorSmartAccount } from './config.ts'

// The address to which the delegation is granted. It can be an EOA address, or
// smart account address.
const delegate = '0x2FcB88EC2359fA635566E66415D31dD381CF5585'

const delegation = createDelegation({
  to: delegate,
  from: account.address,
  environment: delegatorSmartAccount.environment,
  scope: {
    type: ScopeType.NativeTokenTransferAmount,
    // 0.001 ETH in wei format.
    maxAmount: 1000000000000000n,
  },
})

const signature = delegatorSmartAccount.signDelegation({ delegation })

signMessage​

Generates the EIP-191 signature using the MetaMaskSmartAccount signer. The Smart Accounts Kit uses Viem under the hood to provide this functionality.

Parameters​

See the Viem signMessage parameters.

Example​

import { smartAccount } from './config.ts'

const signature = smartAccount.signMessage({
  message: 'hello world',
})

signTypedData​

Generates the EIP-712 signature using the MetaMaskSmartAccount signer. The Smart Accounts Kit uses Viem under the hood to provide this functionality.

Parameters​

See the Viem signTypedData parameters.

Example​

import { smartAccount } from './config.ts'

const signature = smartAccount.signTypedData({
  domain,
  types,
  primaryType: 'Mail',
  message: {
    from: {
      name: 'Cow',
      wallet: '0xCD2a3d9F938E13CD947Ec05AbC7FE734Df8DD826',
    },
    to: {
      name: 'Bob',
      wallet: '0xbBbBBBBbbBBBbbbBbbBbbbbBBbBbbbbBbBbbBBbB',
    },
    contents: 'Hello, Bob!',
  },
})

signUserOperation​

Signs a user operationUser operation A pseudo-transaction object defined by ERC-4337 that describes what a smart account should execute. User operations are submitted to the alternate mempool managed by bundlers. with the MetaMaskSmartAccount signer. The Delegation Toolkit uses Viem under the hood to provide this functionality.

Parameters​

See the Viem signUserOperation parameters.

Example​

import { smartAccount } from './config.ts'

const userOpSignature = smartAccount.signUserOperation({
  callData: '0xdeadbeef',
  callGasLimit: 141653n,
  maxFeePerGas: 15000000000n,
  maxPriorityFeePerGas: 2000000000n,
  nonce: 0n,
  preVerificationGas: 53438n,
  sender: '0xE911628bF8428C23f179a07b081325cAe376DE1f',
  verificationGasLimit: 259350n,
  signature: '0x',
})

toMetaMaskSmartAccount​

Creates a MetaMaskSmartAccount instance.

Parameters​

NameTypeRequiredDescription
clientClientYesViem Client to retrieve smart account data.
implementationTImplementationYesImplementation type for the smart account. Can be HybridHybrid smart account A smart account implementation that supports both an EOA owner and passkey signers., MultisigMultisig smart account A smart account implementation that requires multiple signers to generate a valid signature., or Stateless7702EIP-7702 smart account A stateless MetaMask smart account implementation that represents an upgraded EOA..
signerSignerConfigByImplementation <TImplementation>NoSigner for the smart account. Can be a Viem Account, Viem Wallet Client, or a WebAuthn Account. WebAuthn accounts are only supported for Hybrid implementations. If omitted, non-signing operations still work, but signing operations such as signUserOperation, signDelegation, signMessage, and signTypedData will throw an error.
environmentSmartAccountsEnvironmentNoEnvironment to resolve the smart contracts.
deployParamsDeployParams<TImplementation>Required if address is not providedThe parameters that will be used to deploy the smart account and generate its deterministic address.
deploySaltHexRequired if address is not providedThe salt that will be used to deploy the smart account.
addressAddressRequired if deployParams and deploySalt are not provided, or if the implementation is Stateless7702.The address of the smart account. If an address is provided, the smart account will not be deployed. This should be used if you intend to interact with an existing smart account.
nonceKeyManagerNonceManagerNoA custom nonce key manager for managing nonces. If provided, it enables support for multiple nonce keys to avoid collisions during parallel user operation execution.

Hybrid implementation​

deployParams​

All Hybrid deploy parameters are required:

NameTypeDescription
ownerHexThe owner's account address. The owner can be the zero address, indicating that there is no owner configured.
p256KeyIdsHex[]An array of key identifiers for passkey signers.
p256XValuesbigint[]An array of public key x-values for passkey signers.
p256YValuesbigint[]An array of public key y-values for passkey signers.

Example​

import { Implementation, toMetaMaskSmartAccount } from '@metamask/smart-accounts-kit'
import { publicClient, account } from './config.ts'

const smartAccount = await toMetaMaskSmartAccount({
  client: publicClient,
  implementation: Implementation.Hybrid,
  deployParams: [account.address, [], [], []],
  deploySalt: '0x',
  signer: { account: account },
})

Multisig implementation​

deployParams​

All Multisig deploy parameters are required:

NameTypeDescription
signersHex[]An array of EOA signer addresses.
thresholdbigintThe number of signers required to execute a transaction.

Example​

import { publicClient, aliceAccount, bobAccount } from './config.ts'
import { Implementation, toMetaMaskSmartAccount } from '@metamask/smart-accounts-kit'

const signers = [aliceAccount.address, bobAccount.address]
const threshold = 2n

const aliceSmartAccount = await toMetaMaskSmartAccount({
  client: publicClient,
  implementation: Implementation.MultiSig,
  deployParams: [signers, threshold],
  deploySalt: '0x',
  signer: [{ account: aliceAccount }],
})

Stateless7702 implementation example​

import { Implementation, toMetaMaskSmartAccount } from '@metamask/smart-accounts-kit'
import { publicClient, account } from './config.ts'

const smartAccount = await toMetaMaskSmartAccount({
  client: publicClient,
  implementation: Implementation.Stateless7702,
  address: account.address,
  signer: { account },
})
On this page