Why agents need scoped keys

Autonomous agents handle complex tasks like sending tokens and interacting with smart contracts. To do this, they need cryptographic permissions. If you give an agent your main private key, you are handing over the master control. A compromised agent can drain your entire wallet, and there is no way to revoke that access later.

Smart agent keys solve this by acting as session keys with limited scope. Instead of a master key, you generate a temporary key that can only perform specific actions, such as swapping tokens on a single decentralized exchange. This limits the damage if the agent is compromised. You can also set expiration times, ensuring the key becomes useless after the task is done.

This approach follows the principle of least privilege. You grant only the permissions necessary for the immediate task. The agent cannot move funds to a different wallet or interact with contracts outside the defined scope. This makes autonomous operations safe and manageable.

For deeper technical details on key management strategies for autonomous agents, see the discussion on ethresear.ch. They outline how scoped keys fit into broader agent architectures.

Generate a session key pair

Your main wallet holds the ultimate authority. If that single key is compromised, your entire identity and assets are at risk. Smart agent keys solve this by acting as a separate, limited-privilege identity. They allow your agent to perform specific tasks without touching your primary holdings.

To create this isolated identity, you need to generate a new cryptographic key pair. This process creates a private key that only your agent software will hold and a public key that you will register with your wallet or smart contract. The public key serves as the agent's address, while the private key remains hidden in memory, ready to sign transactions.

1
Initialize the cryptographic library

Start by importing a standard cryptographic library like ethers.js or web3.js into your project. These libraries provide the low-level functions needed to generate secure elliptic curve keys. Ensure you are using a stable version that supports the specific signature scheme (like EIP-191 or EIP-712) required by your target wallet.

2
Generate the key pair programmatically

Call the library's key generation function. This creates a fresh private key and its corresponding public key. The private key is a 256-bit random number that must never leave your secure environment. Store it in a secure variable or memory buffer. Do not log it to the console or write it to a plain text file during this step.

3
Verify the new keys

Before registering the agent, verify that the keys are mathematically valid. Use the library to derive the public key from the private key and confirm it matches the generated public key. This step ensures the cryptographic relationship is intact and the agent will be able to sign messages correctly when deployed.

4
Export the public key for registration

Once verified, export the public key in the format expected by your wallet or smart contract (usually a hex string or uncompressed point). You will use this public key to register the smart agent key in the next phase. Keep the private key secure and ready for the agent's runtime environment.

Deploy the authorization contract

This step connects your main wallet to the smart agent keys using an authorization contract. You are not transferring ownership; you are granting specific permissions. This setup ensures the agent can only act within defined boundaries, such as a swap limit or an approved contract address.

The deployment process typically follows one of two standards: EIP-7702 or ERC-4337. EIP-7702 allows your main wallet to delegate authority to a smart contract, while ERC-4337 (Account Abstraction) uses a dedicated smart contract account to manage transactions. Choose the path that matches your wallet’s current capabilities.

1
Define the permission scope

Before signing, determine the exact limits. Set a maximum daily swap amount to prevent large-scale drains. Specify which contracts the agent is allowed to interact with, such as Uniswap or Aave. Restricting permissions reduces risk if the agent’s logic is compromised.

2
Construct the authorization transaction

Use your wallet interface or a developer tool to build the transaction. If using EIP-7702, you will sign a delegation message. For ERC-4337, you will deploy or configure the smart account entry point. Ensure the owner or delegate address is set to your agent’s public key.

3
Sign and broadcast

Review the transaction details carefully. Confirm the gas fees and the specific permissions being granted. Sign the transaction with your main wallet. Broadcast it to the network and wait for the block confirmation.

4
Verify the connection

Once confirmed, check the blockchain explorer. Verify that the authorization contract shows your main wallet as the owner and the agent key as the authorized delegate. Test the connection with a small, non-critical transaction to ensure the agent can execute its tasks.

This deployment creates a secure bridge between your primary control and the agent’s operational capacity. The agent can now perform its assigned tasks autonomously, but only within the strict limits you defined. Regularly review these permissions to ensure they align with your current needs.

Connect the agent to the key

The smart agent keys are useless if the runtime environment cannot find them. You need to configure your agent framework to load the session key securely and use it for automatic transaction signing.

This process involves two main steps: storing the key in a secure environment variable and initializing the agent client with that credential.

1
Store the session key securely

Never hardcode your private key or mnemonic phrase into your source code. Instead, use an environment variable file (like .env) to store the SESSION_KEY or PRIVATE_KEY.

Most modern agent frameworks rely on secure variable injection to keep credentials out of version control. This ensures that even if your code is public, your wallet access remains private.

2
Initialize the agent with the key

When you start your agent script, pass the environment variable to your wallet provider. For example, if you are using a Python or Node.js script, load the key from process.env or os.environ and pass it to the signer constructor.

This binds the smart agent keys to your specific runtime instance, allowing the agent to sign transactions without manual intervention.

3
Test the connection

Run a small, low-value transaction or a dry-run simulation to verify that the agent can sign and broadcast transactions automatically.

If the agent fails to sign, check that the environment variable is correctly named and that the key format matches the wallet provider's requirements (e.g., hex string vs. raw bytes).

By following this sequence, you ensure that your autonomous wallet operates securely and efficiently. The smart agent keys remain isolated from your codebase while being readily available for the agent's runtime needs.

Test and revoke access safely

Before giving your smart agent keys full operational capacity, you need to verify they work within their intended limits. Start by defining a clear scope for your initial test. If your smart agent key is configured to interact with a specific DeFi protocol, send a small, non-critical transaction to that protocol. For example, if the key is meant to swap tokens, execute a minimal swap. Monitor the transaction on a block explorer to ensure it completes as expected. This step validates that the key’s permissions are active and correctly scoped.

While testing, pay close attention to gas limits and execution time. If the agent fails to execute within the expected timeframe, it may indicate that the transaction parameters are too aggressive or that the underlying network is congested. Adjust these parameters accordingly and retest. Once the agent demonstrates reliable performance within its constraints, you can proceed with confidence.

Verify Permissions

Confirm that the smart agent key can only access the specific contracts and functions you authorized. Review the permission settings in your wallet interface or smart contract dashboard. Ensure that read-only permissions are not mistakenly granted write access, and vice versa. This verification step is critical for maintaining the principle of least privilege.

Execute a Test Transaction

Send a small, test transaction using the smart agent key. This could be a minimal token transfer, a test interaction with a smart contract, or a simulated trade. Observe the transaction hash and confirm that it was signed and broadcast correctly by the agent. This proves that the key is functional and connected to the network.

Confirm Revocation Method

Before finalizing the setup, ensure you have a clear and immediate method to revoke the smart agent key’s access. This might involve calling a specific function on a smart contract, updating a policy in your wallet, or using a multi-signature scheme to cancel the key. Test this revocation process in a separate, isolated environment if possible, so you know exactly how to act if something goes wrong.

  • Verify permissions match the intended scope
  • Execute a small test transaction
  • Set an expiration date for the key
  • Confirm the revocation method works

If something goes wrong during testing or if you suspect unauthorized activity, immediate revocation is essential. Most smart agent implementations allow for instant revocation through a simple transaction or contract call. This capability ensures that even if a key is compromised, the damage can be contained quickly. Always keep your revocation instructions handy and test them regularly to ensure they remain effective.