Session Keys

Session keys are a powerful feature of the Alchemy Wallets API that allow you to create a session for a user’s smart account with specific permissions. This enables secure, permissioned access to the user’s wallet, allowing your app’s server to perform actions on behalf of the user without needing their private key. Session keys allow another account to operate on a user’s smart account with given permissions. After creating a session, you will be able to sign transactions for the generated wallet within the defined permissions using that session key. See here for a list of permissions!

To use this guide, you’ll need:

• An account you can sign with (e.g. an Alchemy Signer or an EOA)
• An Alchemy API key
• A gas manager policy ID if sponsoring gas

Create A Session With Permissions

We’ll demonstrate how to create and use session keys using the SDK client or by using platform-agnostic JSON-RPC APIs.

Permission Types

To specify permissions during a session key installation, include them in the permissions array when calling client.grantPermission() via the SDK or wallet_createSession via the API.

1
const permissions = await client.grantPermissions({
2
  account: account.address,
3
  expirySec: Math.floor(Date.now() / 1000) + 60 * 60,
4
  key: {
5
    publicKey: await sessionKey.getAddress(),
6
    type: "secp256k1",
7
  },
8
  permissions: [{ PERMISSION_ONE }, { PERMISSION_TWO }],
9
});

Native Token Transfer

This permission allows transfer of native tokens (like Ether) from the account.

1
{
2
  type: "native-token-transfer";
3
  data: {
4
    allowance: Hex; // a hexadecimal encoded transfer limit, for example, 1 ETH would be 0xde0b6b3a7640000 (1e18 in hex)
5
  }
6
}

ERC20 Token Transfer

This permission allows transfer or approval of erc20 tokens from the account. Both transfers and approvals count towards the limit.

1
{
2
  type: "erc20-token-transfer";
3
  data: {
4
    address: Address; // erc20 token contract address
5
    allowance: Hex; // a hexadecimal encoded transfer limit
6
  }
7
}

Gas Limit

This permission allows the session key to spend gas for user operations up to a specified limit.

1
{
2
  type: "gas-limit";
3
  data: {
4
    limit: Hex; // a hexadecimal encoded gas limit, for example 300000 gas would be 0x493e0
5
  }
6
}

Contract Access

This permission grants access to all functions in a specific contract.

1
{
2
  type: "contract-access";
3
  data: {
4
    address: Address; // the target contract’s address
5
  }
6
}

Account Functions

This permission grants access to specific functions on the smart account itself.

1
{
2
  type: "account-functions";
3
  data: {
4
    functions: Hex[]; // array of allowed function selectors, e.g. ["0xabcdef01", "0x12345678"]
5
  };
6
}

Functions On All Contracts

This permission grants access to a set of function selectors across any address.

1
{
2
  type: "functions-on-all-contracts";
3
  data: {
4
    functions: Hex[]; // array of function selectors allowed globally, e.g. ["0xddf252ad"]
5
  };
6
}

Functions On Contract

This permission grants access to specific function selectors on one contract.

1
{
2
  type: "functions-on-contract";
3
  data: {
4
    address: Address;  // the contract address you’re targeting
5
    functions: Hex[];  // array of allowed function selectors for that contract, e.g. ["0xddf252ad"]
6
  };
7
}

Root

This permission grants full access to everything. Needless to say, this is a very dangerous permission to grant.

1
{
2
  type: "root"; // no additional data required
3
}