Add session keys

By default, every transaction requires the user to sign. Session keys let your app hold a scoped key that can sign on the user’s behalf, within limits you define. The user approves once and your app executes freely until the session expires or limits are hit. This tutorial walks through a one-click trading scenario: the user grants your app permission to execute USDC transfers up to a spending limit, without prompting for every trade. This tutorial builds on the Quickstart. You’ll need a working smart account before continuing.

Prerequisites

Completed the Quickstart
A Rhinestone dashboard API key

Steps

Install smart sessions on the account

Enable the Smart Sessions module when creating the account:

import { RhinestoneSDK } from '@rhinestone/sdk'

const rhinestone = new RhinestoneSDK({
  apiKey: process.env.RHINESTONE_API_KEY as string,
})

const rhinestoneAccount = await rhinestone.createAccount({
  owners: {
    type: 'ecdsa',
    accounts: [ownerAccount],
  },
  sessions: {
    enabled: true,
  },
})

If the account is already deployed, you can install the module in a separate transaction:

import { enable } from '@rhinestone/sdk/actions/smart-sessions'

const transaction = await rhinestoneAccount.prepareTransaction({
  chain: base,
  calls: [enable()],
})
const signed = await rhinestoneAccount.signTransaction(transaction)
const result = await rhinestoneAccount.submitTransaction(signed)
await rhinestoneAccount.waitForExecution(result)

Generate a session key

Create an ephemeral key pair that your app will use to sign on the user’s behalf. In production, store this key securely. Use localStorage for client-side sessions, or a KMS/secrets manager for server-side automation.

import { generatePrivateKey, privateKeyToAccount } from 'viem/accounts'

const sessionPrivateKey = generatePrivateKey()
const sessionOwnerAccount = privateKeyToAccount(sessionPrivateKey)

Define the session

Specify what the session key is allowed to do. Here we restrict it to USDC transfers only, with a 100 USDC spending limit:

import { erc20Abi, parseUnits } from 'viem'
import { base } from 'viem/chains'

const usdcAddress = '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913' // USDC on Base

const session = await rhinestone.createSession({
  chain: base,
  owners: {
    type: 'ecdsa',
    accounts: [sessionOwnerAccount],
  },
  permissions: [
    {
      abi: erc20Abi,
      address: usdcAddress,
      functions: {
        transfer: {
          spendingLimit: {
            token: usdcAddress,
            amount: parseUnits('100', 6), // 100 USDC
          },
        },
      },
    },
  ],
})

By default, a session with no permissions allows any transaction. Always restrict sessions to the minimum necessary permissions.

Enable the session

The account owner signs to approve the session. This is the one-time approval the user sees:

import { enableSession } from '@rhinestone/sdk/actions/smart-sessions'

const sessions = [session]
const sessionDetails = await rhinestoneAccount.getSessionDetails(sessions)
const enableSignature = await rhinestoneAccount.signEnableSession(sessionDetails)
const sessionIndex = 0

const transaction = await rhinestoneAccount.prepareTransaction({
  chain: base,
  calls: [
    enableSession(
      session,
      enableSignature,
      sessionDetails.hashesAndChainIds,
      sessionIndex,
    ),
  ],
})
const signed = await rhinestoneAccount.signTransaction(transaction)
const result = await rhinestoneAccount.submitTransaction(signed)
await rhinestoneAccount.waitForExecution(result)

Execute transactions with the session key

Now your app can execute USDC transfers without prompting the user. The session key signs instead of the owner:

import { encodeFunctionData, erc20Abi } from 'viem'

const recipient = '0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045'
const amount = parseUnits('10', 6) // 10 USDC

const prepared = await rhinestoneAccount.prepareTransaction({
  chain: base,
  calls: [
    {
      to: usdcAddress,
      data: encodeFunctionData({
        abi: erc20Abi,
        functionName: 'transfer',
        args: [recipient, amount],
      }),
    },
  ],
  signers: {
    type: 'session',
    session,
  },
})
const signed = await rhinestoneAccount.signTransaction(prepared)
const result = await rhinestoneAccount.submitTransaction(signed)

const status = await rhinestoneAccount.waitForExecution(result)
console.log('Executed without user prompt:', status)

The user’s MetaMask (or other wallet) is never involved. Your app signed with the session key, within the spending limit the user approved.

What you built

A smart account with Smart Sessions installed
A scoped session key (USDC transfers only, 100 USDC limit)
One-time user approval flow
App-signed transactions with no user prompts

Security checklist

Before shipping session keys to production:

Store the session key securely. Use localStorage for browser-side sessions, a KMS or secrets manager for server-side automation.
Apply the principle of least privilege. Only request the actions your app actually needs.
Set a timeframe policy. Add an expiry so sessions don’t live forever.
Set spending limits. Cap ERC20 transfers to a sensible amount.

See it in action: session-keys example — approve a scoped session once, then execute with the session key.

Next steps

Smart Sessions reference

Full details on owners, actions, policies, and multi-session signatures.

Policies

Explore all available policies: timeframe, usage limit, call restrictions.

Sponsor fees

Combine session keys with fee sponsorship for a fully frictionless UX.

Tutorials

Smart account setup

Gas & fee sponsorship

Smart Sessions

More features

Configuration

Module development

SDK Reference

Prerequisites

Steps

What you built

Security checklist

Next steps

Smart Sessions reference

Policies

Sponsor fees

​Prerequisites

​Steps

​What you built

​Security checklist

​Next steps

Smart Sessions reference

Policies

Sponsor fees

Prerequisites

Steps

What you built

Security checklist

Next steps