Advanced Permissions reference

When executing on a MetaMask user's behalf, you can request the following permission types. Learn how to use Advanced Permissions types.

ERC-20 token permissions

ERC-20 allowance permission

Ensures a fixed ERC-20 token allowance. Transfers are allowed until the total transferred amount reaches the allowance amount.

Parameters

Name	Type	Required	Description
tokenAddress	Address	Yes	The ERC-20 token contract address.
allowanceAmount	bigint	Yes	The maximum total amount of tokens that can be transferred.
startTime	number	No	The start timestamp in seconds. The default is the current time.
justification	string	No	A human-readable explanation of why the permission is being requested.

Example

import { parseUnits } from 'viem'

const currentTime = Math.floor(Date.now() / 1000)
const expiry = currentTime + 604800

const permission = {
  type: 'erc20-token-allowance',
  data: {
    tokenAddress: '0x1c7D4B196Cb0C7B01d743Fbc6116a902379C7238',
    allowanceAmount: parseUnits('50', 6),
    startTime: currentTime,
    justification: 'Permission to transfer up to 50 USDC in total',
  },
  isAdjustmentAllowed: true,
}

ERC-20 periodic permission

Ensures a per-period limit for ERC-20 token transfers. At the start of each new period, the allowance resets.

Parameters

Name	Type	Required	Description
tokenAddress	Address	Yes	The ERC-20 token contract address as a hex string.
periodAmount	bigint	Yes	The maximum amount of tokens that can be transferred per period.
periodDuration	number	Yes	The duration of each period in seconds.
startTime	number	No	The start timestamp in seconds. The default is the current time.
justification	string	No	A human-readable explanation of why the permission is being requested.

Example

import { parseUnits } from 'viem'

const currentTime = Math.floor(Date.now() / 1000)
const expiry = currentTime + 604800

const permission = {
  type: 'erc20-token-periodic',
  data: {
    tokenAddress: '0x1c7D4B196Cb0C7B01d743Fbc6116a902379C7238',
    periodAmount: parseUnits('10', 6),
    periodDuration: 86400,
    justification: 'Permission to transfer 10 USDC every day',
  },
  isAdjustmentAllowed: true,
}

ERC-20 stream permission

Ensures a linear streaming transfer limit for ERC-20 tokens. Token transfers are blocked until the defined start timestamp. At the start, a specified initial amount is released, after which tokens accrue linearly at the configured rate, up to the maximum allowed amount.

Parameters

Name	Type	Required	Description
tokenAddress	Address	Yes	The ERC-20 token contract address.
initialAmount	bigint	No	The initial amount that can be transferred at start time. The default is 0.
maxAmount	bigint	No	The maximum total amount that can be unlocked. The default is no limit.
amountPerSecond	bigint	Yes	The rate at which tokens accrue per second.
startTime	number	No	The start timestamp in seconds. The default is the current time.
justification	string	No	A human-readable explanation of why the permission is being requested.

Example

import { parseUnits } from 'viem'

const currentTime = Math.floor(Date.now() / 1000)
const expiry = currentTime + 604800

const permission = {
  type: 'erc20-token-stream',
  data: {
    tokenAddress: '0x1c7D4B196Cb0C7B01d743Fbc6116a902379C7238',
    amountPerSecond: parseUnits('0.1', 6),
    initialAmount: parseUnits('1', 6),
    maxAmount: parseUnits('2', 6),
    startTime: currentTime,
    justification: 'Permission to use 0.1 USDC per second',
  },
  isAdjustmentAllowed: true,
}

Native token permissions

Native token allowance permission

Ensures a fixed native token allowance. Transfers are allowed until the total transferred amount reaches the allowance amount.

Parameters

Name	Type	Required	Description
allowanceAmount	bigint	Yes	The maximum total amount of tokens that can be transferred.
startTime	number	No	The start timestamp in seconds. The default is the current time.
justification	string	No	A human-readable explanation of why the permission is being requested.

Example

import { parseEther } from 'viem'

const currentTime = Math.floor(Date.now() / 1000)
const expiry = currentTime + 604800

const permission = {
  type: 'native-token-allowance',
  data: {
    allowanceAmount: parseEther('0.05'),
    startTime: currentTime,
    justification: 'Permission to transfer up to 0.05 ETH in total',
  },
  isAdjustmentAllowed: true,
}

Native token periodic permission

Ensures a per-period limit for native token transfers. At the start of each new period, the allowance resets.

Parameters

Name	Type	Required	Description
periodAmount	bigint	Yes	The maximum amount of tokens that can be transferred per period.
periodDuration	number	Yes	The duration of each period in seconds.
startTime	number	No	The start timestamp in seconds. The default is the current time.
justification	string	No	A human-readable explanation of why the permission is being requested.

Example

import { parseEther } from 'viem'

const currentTime = Math.floor(Date.now() / 1000)
const expiry = currentTime + 604800

const permission = {
  type: 'native-token-periodic',
  data: {
    periodAmount: parseEther('0.001'),
    periodDuration: 86400,
    startTime: currentTime,
    justification: 'Permission to use 0.001 ETH every day',
  },
  isAdjustmentAllowed: true,
}

Native token stream permission

Ensures a linear streaming transfer limit for native tokens. Token transfers are blocked until the defined start timestamp. At the start, a specified initial amount is released, after which tokens accrue linearly at the configured rate, up to the maximum allowed amount.

Parameters

Name	Type	Required	Description
initialAmount	bigint	No	The initial amount that can be transferred at start time. The default is 0.
maxAmount	bigint	No	The maximum total amount that can be unlocked. The default is no limit.
amountPerSecond	bigint	Yes	The rate at which tokens accrue per second.
startTime	number	No	The start timestamp in seconds. The default is the current time.
justification	string	No	A human-readable explanation of why the permission is being requested.

Example

import { parseEther } from 'viem'

const currentTime = Math.floor(Date.now() / 1000)
const expiry = currentTime + 604800

const permission = {
  type: 'native-token-stream',
  data: {
    amountPerSecond: parseEther('0.0001'),
    initialAmount: parseEther('0.1'),
    maxAmount: parseEther('1'),
    startTime: currentTime,
    justification: 'Permission to use 0.0001 ETH per second',
  },
  isAdjustmentAllowed: true,
}

Token approval revocation permission

Enables revoking an existing token approvals on behalf of the user.

Parameters

Name	Type	Required	Description
erc20Approve	boolean	Yes	Whether to allow revoking ERC-20 allowances.
erc721Approve	boolean	Yes	Whether to allow revoking ERC-721 per-token approvals.
erc721SetApprovalForAll	boolean	Yes	Whether to allow revoking ERC-721 and ERC-1155 operator approvals.
permit2Approve	boolean	Yes	Whether to allow revoking Permit2 approvals.
permit2Lockdown	boolean	Yes	Whether to allow locking down Permit2.
permit2InvalidateNonces	boolean	Yes	Whether to allow invalidating Permit2.
justification	string	No	A human-readable explanation of why the permission is being requested.

Example

const permission = {
  type: 'token-approval-revocation',
  data: {
    erc20Approve: true,
    erc721Approve: true,
    erc721SetApprovalForAll: true,
    permit2Approve: false,
    permit2Lockdown: false,
    permit2InvalidateNonces: false,
    justification: 'Permission to revoke ERC-20, ERC-721, and ERC-115 token approvals',
  },
  isAdjustmentAllowed: false,
}