Skip to main content

Snaps permissions

Snaps can request the following permissions.

RPC API permissions​

You must request permission to call Snaps API methods. For example, to request to call snap_dialog, add the following to the manifest file:

snap.manifest.json
"initialPermissions": {
  "snap_dialog": {}
}

Endowments​

endowment:cronjob​

To run cron jobs for the user, a Snap must request the endowment:cronjob permission. This permission allows the Snap to specify cron jobs that trigger the onCronjob entry point.

This permission takes an object with an array of jobs, each containing two parameters:

  • expression - A cron expression that defines the schedule of the job.
  • request - A JSON-RPC request object that will be sent to the Snap's onCronjob entry point when the job is executed.
tip

You can modify the cron job's execution limit using Snap-defined timeouts.

Specify this permission in the manifest file as follows:

snap.manifest.json
"initialPermissions": {
  "endowment:cronjob": {
    "jobs": [
      {
        "expression": "* * * * *",
        "request": {
          "method": "exampleMethodOne",
          "params": {
            "param1": "foo"
          }
        }
      },
      {
        "expression": "*/2 * * * *",
        "request": {
          "method": "exampleMethodTwo",
          "params": {
            "param1": "bar"
          }
        }
      }
    ]
  }
}

endowment:ethereum-provider​

To communicate with a node using MetaMask, a Snap must request the endowment:ethereum-provider permission. This permission exposes the ethereum global to the Snap execution environment, allowing Snaps to call some MetaMask JSON-RPC API methods. This global is an EIP-1193 provider.

Specify this permission in the manifest file as follows:

snap.manifest.json
"initialPermissions": {
  "endowment:ethereum-provider": {}
}
note

The ethereum global available to Snaps has fewer capabilities than window.ethereum for dapps. See the list of methods not available to Snaps.

endowment:page-home​

To display a home page within MetaMask, a Snap must request the endowment:page-home permission. This permission allows the Snap to present a dedicated UI by exposing the onHomePage entry point.

Specify this permission in the manifest file as follows:

snap.manifest.json
"initialPermissions": {
  "endowment:page-home": {}
}

endowment:keyring​

For a dapp to call Account Management API methods on an account management Snap to integrate custom EVM accounts, the Snap must configure a list of allowed dapp URLs using the allowedOrigins field of the endowment:keyring permission. This permission grants a Snap access to Account Management API requests sent to the Snap, using the onKeyringRequest entry point.

If a dapp hosted on a domain not listed in the allowedOrigins attempts to call a Keyring API method, MetaMask rejects the request.

tip

You can modify the Account Management API's execution limit using Snap-defined timeouts.

Specify this permission in the manifest file as follows:

snap.manifest.json
"initialPermissions": {
  "endowment:keyring": {
    "allowedOrigins": ["https://<dapp domain>"]
  }
}

endowment:lifecycle-hooks​

To implement a lifecycle hook that runs an action when a user installs or updates a Snap, the Snap must request the endowment:lifecycle-hooks permission. This permission allows the Snap to expose the onInstall and onUpdate entry points, which MetaMask calls after a successful installation or update, respectively.

tip

You can modify the lifecycle hooks' execution limit using Snap-defined timeouts.

Specify this permission in the manifest file as follows:

snap.manifest.json
"initialPermissions": {
  "endowment:lifecycle-hooks": {}
}

endowment:name-lookup​

To provide custom name resolution, a Snap must request the endowment:name-lookup permission. This permission grants the Snap read-only access to user input or an address by exporting the onNameLookup entry point.

This permission takes an object with two optional properties:

  • chains - An array of CAIP-2 chain IDs for which the Snap can resolve names and addresses. Pass this array to reduce overhead on your Snap by making sure it only receives requests for chains it can resolve.
  • matchers - An object that helps reduce overhead by filtering the domains passed to your Snap. This must contain at least one of the following properties:
    • tlds - An array of strings for top-level domains that the Snap supports. For example, to support domains of the form my-domain.crypto, specify ["crypto"].
    • schemes - An array of strings for schemes that the Snap supports. For example, to support schemes of the form farcaster:my-user, specify ["farcaster"].
tip

You can modify the name lookup logic's execution limit using Snap-defined timeouts.

Specify this permission in the manifest file as follows:

snap.manifest.json
"initialPermissions": {
  "endowment:name-lookup": {
    "chains": ["eip155:1"],
    "matchers": {
      "tlds": ["crypto"],
      "schemes": ["farcaster"]
    }
  }
},

In this example, the Snap's onNameLookup entry point would be called for domains such as someuser.crypto or schemes such as farcaster:someuser, as long as the domain resolution is happening on Ethereum Mainnet.

endowment:network-access​

To access the internet, a Snap must request the endowment:network-access permission. This permission exposes the global fetch API to the Snaps execution environment.

Specify this permission in the manifest file as follows:

snap.manifest.json
"initialPermissions": {
  "endowment:network-access": {}
}

endowment:rpc​

To handle arbitrary JSON-RPC requests, a Snap must request the endowment:rpc permission. This permission grants a Snap access to JSON-RPC requests sent to the Snap, using the onRpcRequest entry point.

This permission requires an object with a snaps or dapps property (or both), to signal if the Snap can receive JSON-RPC requests from other Snaps, or dapps, respectively. The default for both properties is false.

tip

You can modify the RPC API's execution limit using Snap-defined timeouts.

Specify this permission in the manifest file as follows:

snap.manifest.json
"initialPermissions": {
  "endowment:rpc": {
    "dapps": true,
    "snaps": false
  }
}

Allowed origins​

Alternatively, you can specify the caveat allowedOrigins to restrict all requests to specific domains or Snap IDs. Calls from any other origins are rejected.

Specify this caveat in the manifest file as follows:

snap.manifest.json
"initialPermissions": {
  "endowment:rpc": {
    "allowedOrigins": [
      "https://metamask.io",
      "https://consensys.io",
      "npm:@metamask/example-snap"
    ]
  }
}
note

If you specify allowedOrigins, you should not specify dapps or snaps.

If you want to grant a dapp or Snap an automatic connection to your Snap, skipping the need for users to confirm a connection, you can use initialConnections.

endowment:signature-insight​

To provide signature insights, a Snap must request the endowment:signature-insight permission. This permission grants a Snap read-only access to raw signature payloads, before they're accepted for signing by the user, by exposing the onSignature entry point.

This permission requires an object with an allowSignatureOrigin property to signal if the Snap should pass the signatureOrigin property as part of the onSignature parameters. This property represents the signature initiator origin. The default is false.

Specify this permission in the manifest file as follows:

snap.manifest.json
"initialPermissions": {
  "endowment:signature-insight": {
    "allowSignatureOrigin": true
  }
},

endowment:transaction-insight​

To provide transaction insights before a user signs a transaction, a Snap must request the endowment:transaction-insight permission. This permission grants a Snap read-only access to raw transaction payloads, before they're accepted for signing by the user, by exposing the onTransaction entry point.

This permission requires an object with an allowTransactionOrigin property to signal if the Snap should pass the transactionOrigin property as part of the onTransaction parameters. This property represents the transaction initiator origin. The default is false.

tip

You can modify the transaction insight logic's execution limit using Snap-defined timeouts.

Specify this permission in the manifest file as follows:

snap.manifest.json
"initialPermissions": {
  "endowment:transaction-insight": {
    "allowTransactionOrigin": true
  }
}

endowment:webassembly​

To use WebAssembly, a Snap must request the endowment:webassembly permission. This permission exposes the global WebAssembly API to the Snap execution environment.

Specify this permission in the manifest file as follows:

snap.manifest.json
"initialPermissions": {
  "endowment:webassembly": {}
}

Snap-defined timeouts​

Many endowments entail having MetaMask run arbitrary code defined in the Snap. The default execution timeout is 60000 milliseconds, or one minute.

You can modify this execution timeout by adding a caveat maxRequestTime to the permission. It can take values from 5000 (5 seconds) to 180000 (3 minutes). For example:

snap.manifest.json
"initialPermissions": {
  "endowment:transaction-insight": {
    "maxRequestTime": 10000
  }
}

The following endowments accept this caveat:

Dynamic permissions​

eth_accounts​

A Snap can request permission to call the eth_accounts MetaMask JSON-RPC API method by calling eth_requestAccounts. Calling eth_requestAccounts requires the endowment:ethereum-provider permission:

snap.manifest.json
"initialPermissions": {
  "endowment:ethereum-provider": {}
}

You can check the presence of the permission by calling wallet_getPermissions. If the permission is present, the result contains a permission with a parentCapability of eth_accounts. The permission contains a restrictReturnedAccounts caveat, an array of all the accounts the user allows for this Snap. The following is an example eth_accounts permission:

{
  "id": "47vm2UUi1pccNAeYKGmwF",
  "parentCapability": "eth_accounts",
  "invoker": "npm:SNAP_ID",
  "caveats": [
    {
      "type": "restrictReturnedAccounts",
      "value": ["0xc403b37bf1e700cb214ea1be9de066824b420de6"]
    }
  ],
  "date": 1692616452846
}

The user can revoke this permission by going to the Snap's settings under Snap permissions.

Initial connections​

A Snap can authorize specific dapps or Snaps to automatically connect, skipping the need for users to manually confirm a connection when the dapp or Snap calls wallet_requestSnaps.

The following is an example of specifying initialConnections for a dapp:

snap.manifest.json
"initialConnections": {
  "https://voyager-snap.linea.build": {}
}

When a user visits the dapp and the dapp calls wallet_requestSnaps, if the Snap is already installed, the dapp connects immediately and can make further calls to the Snap. If the Snap is not installed, the user sees a confirmation to install the Snap.

Learn more about allowing automatic connections.

important

initialConnections is not a replacement for endowment:rpc. endowment:rpc is still required to allow dapps or Snaps to call RPC methods of your Snap.