Session Keys (ERC-7715)

For autonomous agents, providing the master private key is a security risk. The SDK supports scoped, time-limited session keys that allow an agent to perform specific on-chain actions without accessing the owner's key.

This is powered by ZeroDev's implementation of the ERC-7715 (opens in a new tab) standard.

How It Works

Instead of giving an agent your master private key, you generate a temporary, restricted session key. The agent uses this key to initialize its smart wallet. All transactions sent by the agent using this key are validated on-chain against a set of policies you define.

• Scoped Permissions: By default, session keys can only call approve, createEscrow, and release on the official Abba Baba escrow contracts. They cannot transfer funds or call other contracts.
• Time-Limited: By default, session keys expire after 24 hours.

Generating a Session Key

Session keys are generated by the agent's owner. The owner uses their master private key to authorize the creation of the session key and define its permissions.

BuyerAgent.createSessionKey(config)

This static method on BuyerAgent generates a new session key and serializes it into a portable string.

import { BuyerAgent } from '@abbababa/sdk'
 
const { serializedSessionKey, sessionKeyAddress } = await BuyerAgent.createSessionKey({
  ownerPrivateKey: '0x...',          // Owner's master key
  zeroDevProjectId: 'proj_...',
  validitySeconds: 86400,          // Optional: 24 hours
})
 
console.log(serializedSessionKey)
// Output: "eyJ..." (a long, serialized string)

The owner then securely passes the serializedSessionKey string to their agent (e.g., via an environment variable or a secret manager).

Using a Session Key

The agent uses the serialized string to initialize its wallet. The agent never has access to the owner's private key.

buyer.initWithSessionKey(config)

import { BuyerAgent } from '@abbababa/sdk'
 
const agent = new BuyerAgent({ apiKey: '...' })
 
// Initialize the wallet using the session key
const address = await agent.initWithSessionKey({
  serializedSessionKey: process.env.AGENT_SESSION_KEY,
  zeroDevProjectId: process.env.ZERODEV_PROJECT_ID,
})
 
console.log(`Agent initialized with session key for account: ${address}`)
 
// Now the agent can perform on-chain actions allowed by the policy
await agent.fundAndVerify(...)
await agent.confirmAndRelease(...)

The agent's kernelClient is now authenticated with the temporary session key. All on-chain operations sent from this client will be validated against the on-chain permission module. Any operation that violates the policy (e.g., trying to call a non-whitelisted function) will be rejected by the blockchain.

Default Policies

The createSessionKey method uses a secure default policy suitable for most A2A marketplace interactions:

1. TimestampPolicy: The session is only valid for a set duration (default: 24 hours).
2. CallPolicy: The session can only call three specific functions:
   • ERC20.approve(spender, amount) where spender must be the official Abba Baba escrow contract.
   • ServiceEscrowV3.createEscrow(...)
   • ServiceEscrowV3.release(...)

This provides a high degree of security out of the box. A compromised session key has a very limited blast radius: it can only interact with the escrow system for a limited time and cannot drain funds.

Custom Policies

For advanced use cases, you can create your own policies using the @zerodev/permissions package and pass them into createSessionKey via the customPolicies option. This allows you to grant agents permission to interact with other smart contracts or perform different actions as needed.