Agent Wallets

Overview

Agent wallets are delegated wallets that can sign orders on behalf of your main wallet, enabling one-click trading without repeated MetaMask popups. They provide the perfect balance between security (maintaining self-custody) and usability (eliminating signature friction).

Key Benefits:

One-Click Trading: Submit orders without wallet confirmations
High-Frequency Trading: Enable programmatic and bot trading
Limited Risk: Agents have restricted permissions, main wallet stays safe
Revocable Access: Disable agent wallets anytime
Session-Based: Temporary agents auto-expire

How Agent Wallets Work

Architecture

Main Wallet
│
├── Session Agent (Unnamed)
│   ├── Browser-generated private key
│   ├── Stored in SessionStorage
│   ├── Auto-expires when browser closes
│   └── One per main wallet
│
└── API Agents (Named)
    ├── Agent 1: "Trading Bot"
    ├── Agent 2: "Market Maker"
    └── Agent 3: "Grid Strategy"
    └── Up to 3 per main wallet

Core Concept:

Registration: Main wallet signs EIP-712 message authorizing agent
Mapping: System maps agent address → main wallet address
Trading: Agent signs orders, system credits/debits main wallet
Nonces: Each agent has independent nonce tracking

Wallet Types

Master Accounts

Your primary trading account:

Allowed Agents:

1 Session Agent: Unnamed, browser-based, auto-expires
3 Named Agents: Persistent API keys for bots

Use Cases:

Personal trading with session agent
Multiple trading strategies via named agents
Market making and grid bots

Subaccounts

Additional accounts under your main wallet:

Allowed Agents:

0 Session Agents: Not permitted
2 Named Agents: API-only access

Use Cases:

Isolated strategy accounts
Team member delegation
Separate risk pools

Session Wallets (Browser Trading)

Setup Process

1. Connect Main Wallet:

User clicks "Connect Wallet"
→ MetaMask prompts for connection
→ Main wallet address retrieved

2. Generate Session Key:

Browser generates new private key
→ Derives Ethereum address
→ Stores in SessionStorage (secure, auto-clears)

3. Sign Authorization:

Main wallet signs EIP-712 message:
"Authorize agent wallet 0x... to trade on my behalf"
→ Signature proves ownership
→ Registration stored on-chain

4. One-Click Trading:

Place order
→ Session wallet signs order
→ No MetaMask popup
→ Order executes on main wallet

Security Properties

Browser-Based Security:

Private key never leaves browser
SessionStorage (not LocalStorage)
Cleared when tab/browser closes
Unique per session

Limited Exposure:

Only trading permissions
Cannot withdraw funds
Cannot modify wallet settings
Revocable by main wallet

Auto-Expiry:

Optional expiry timestamp
Automatically disabled after timeout
Session ends when browser closes
Re-registration required for new session

Example Flow

Day 1, 9:00 AM:
1. Open trading app
2. Connect MetaMask
3. Sign agent authorization (one-time)
4. Trade all day with one-click

Day 1, 5:00 PM:
- Close browser
- Session wallet private key deleted
- Agent authorization remains but key is gone

Day 2, 9:00 AM:
1. Open trading app
2. Connect MetaMask
3. Generate new session key
4. Sign new authorization
5. Trade with new session

API Wallets (Programmatic Trading)

Setup Process

1. Create Named Agent:

Navigate to Settings → API Wallets
→ Click "Create New API Wallet"
→ Enter name: "My Trading Bot"
→ Sign authorization with main wallet

2. Receive Credentials:

Private Key: 0x1234... (shown once, copy securely)
Agent Address: 0xabcd...
→ Store private key in secure location
→ Never shown again

3. Configure Bot:

from eth_account import Account

# Load agent wallet
agent = Account.from_key('0x1234...')

# Sign orders with agent
order = create_order(...)
signed = agent.sign_message(order)
submit_order(signed)

Security Considerations

Private Key Management:

Critical: Store securely (environment variables, secrets manager)
Never: Commit to git, share publicly, hardcode
Best Practice: Use hardware security modules for production

Access Control:

Each agent is independently revocable
Monitor agent activity regularly
Rotate keys periodically
Delete unused agents

Risk Mitigation:

Start with small balances
Test with testnet first
Implement rate limiting
Monitor for unusual activity

Registration Process

EIP-712 Authorization Message

Message Structure:

Register Agent Wallet
├── Agent Address: 0xabcd...
├── Real Wallet: 0x1234... (your main wallet)
├── Name: "Trading Bot" (optional, None for session)
├── Nonce: 1678901234567 (millisecond timestamp)
└── Expiry: 1678987634567 (optional)

Signing:

Main wallet signs authorization
→ Proves ownership of main wallet
→ Authorizes specific agent address
→ Cryptographically verifiable
→ Cannot be forged

Validation

System Checks:

Signature valid: Recovered address matches main wallet
Limits not exceeded: Within agent count limits
Agent unique: Agent address not already registered
Nonce valid: Fresh timestamp, not reused
Not expired: If expiry set, current time < expiry

On Success:

Agent mapping stored: agents[agent_address] = main_wallet
Nonce tracker created for agent
Agent marked as active
Can now sign orders

Agent Limits

Master Account Limits

Session Agents (Unnamed):

Maximum: 1
Behavior: New session replaces old one
Auto-cleanup: Old session invalidated

Named Agents (API):

Maximum: 3
Behavior: Error if limit exceeded
Management: Must delete old agent to add new one

Subaccount Limits

Session Agents:

Maximum: 0 (not allowed)
Reason: Subaccounts are API-only

Named Agents:

Maximum: 2
Use case: Focused strategies, team delegation

Enforcement

Registration Time:

// Simplified from agent_wallet.rs
if wallet_type == Master {
    if unnamed && unnamed_count >= 1 {
        // Allow replacing existing session
        revoke_old_session()
    }
    if named && named_count >= 3 {
        return Error::AgentLimitExceeded
    }
} else if wallet_type == Subaccount {
    if unnamed {
        return Error::InvalidConfiguration
    }
    if named && named_count >= 2 {
        return Error::AgentLimitExceeded
    }
}

Agent Nonce Management

Independent Nonce Tracking

Each agent has its own nonce tracker:

Structure:

Agent A → NonceTracker A
Agent B → NonceTracker B
Main Wallet → NonceTracker Main

Benefits:

Parallel order submission from multiple agents
No nonce coordination needed
Each agent independently tracked
No conflicts between agents

Nonce Validation

Per-Agent Rules:

Must be unique within agent's 100-nonce window
Must be timestamp (millisecond precision)
Must be within valid time bounds
Must be higher than lowest stored nonce

Example:

Agent A submits order with nonce 1678901234567
Agent B submits order with nonce 1678901234567
→ Both valid! Different nonce trackers
→ No conflict

Agent A submits another order with nonce 1678901234567
→ Invalid! Nonce already used by Agent A

Revocation

Revoking Agents

Via UI:

Settings → Agent Wallets
→ Click "Revoke" next to agent
→ Sign revocation message
→ Agent immediately disabled

Via API:

POST /v1/agents/revoke
{
  "agent_address": "0xabcd...",
  "signature": "0x..."
}

Effects of Revocation

Immediate:

Agent can no longer sign orders
Pending orders remain valid
Agent removed from active list
Nonce tracker retained (prevent replay)

Not Affected:

Main wallet balance
Existing open orders
Order history
Other agents

Automatic Revocation

Expiry-Based:

If agent created with expiry timestamp
System checks expiry on each use
Automatically disabled after expiry
Must re-register to continue

Example:

Create session agent with 8-hour expiry
Expiry = now + (8 * 60 * 60 * 1000) ms

After 8 hours:
→ Agent automatically inactive
→ Orders rejected
→ Must create new session

Security Best Practices

For Session Wallets

Do:

Use for short trading sessions
Close browser when done
Re-authorize each session
Trade on trusted devices only

Don't:

Share session on public computers
Leave sessions open indefinitely
Trust browser extensions you don't know

For API Wallets

Do:

Store keys in environment variables
Use secrets management systems
Rotate keys periodically
Monitor activity regularly
Start with small balances
Test on testnet first

Don't:

Commit keys to git
Share keys publicly
Hardcode in source code
Reuse same key across systems
Trust untrusted code with keys

For Main Wallets

Do:

Use hardware wallets for large accounts
Verify agent authorizations carefully
Review agent list regularly
Revoke unused agents
Keep wallet software updated

Don't:

Authorize unknown agents
Share private keys ever
Ignore suspicious activity
Skip signature verification prompts

Common Workflows

Daily Trading (Session Wallet)

Morning:
1. Open trading app → Connect wallet
2. Sign agent authorization → One-time
3. Trade all day → One-click orders

Evening:
4. Close browser → Session ends
5. Next day, repeat from step 1

Bot Trading (API Wallet)

Setup (One-Time):
1. Create named agent "Trading Bot"
2. Save private key securely
3. Configure bot with agent key

Daily Operation:
1. Bot loads agent key
2. Bot signs orders with agent
3. Orders execute on main wallet
4. Monitor via dashboard

Shutdown:
1. Stop bot
2. Revoke agent (optional)
3. Delete private key

Market Making (Multiple Agents)

Setup:
1. Create agent "MM_BTC" for BTC pair
2. Create agent "MM_ETH" for ETH pair
3. Create agent "MM_SOL" for SOL pair

Operation:
- Each bot uses its own agent
- Independent nonce tracking
- Parallel order submission
- No coordination needed

Troubleshooting

"Agent Limit Exceeded"

Problem: Trying to create more agents than allowed

Solution:

List existing agents
Revoke unused agents
Try creating new agent again

"Agent Already Exists"

Problem: Agent address already registered

Solution:

Check if you already created this agent
Use different private key for new agent
Revoke old agent if you want to re-register

"Invalid Agent Signature"

Problem: Order signed by unregistered agent

Solution:

Verify agent is registered
Check agent hasn't been revoked
Ensure agent hasn't expired
Re-register if needed

"Session Lost on Refresh"

Problem: Browser refresh clears session wallet

Expected Behavior:

SessionStorage cleared on refresh in some browsers
Re-authorization required
Security feature, not bug

Solution:

Re-connect wallet
Sign new authorization
Consider using named agent for persistent sessions

Technical Implementation

Data Structure (from codebase)

pub struct AgentWallet {
    pub agent_address: [u8; 20],      // Agent's address
    pub real_wallet: [u8; 20],        // Main wallet address
    pub name: Option<String>,          // None = session, Some = named
    pub wallet_type: WalletType,       // Master or Subaccount
    pub created_at: u64,              // Creation timestamp
    pub last_used: u64,               // Last activity timestamp
    pub expires_at: Option<u64>,      // Optional expiry
    pub is_active: bool,              // Currently active?
}

pub struct AgentWalletRegistry {
    // O(1) lookups
    agents: HashMap<AgentAddress, AgentWallet>,
    by_real_wallet: HashMap<RealWallet, Vec<AgentAddress>>,
    wallet_types: HashMap<RealWallet, WalletType>,
    agent_nonce_trackers: HashMap<AgentAddress, NonceTracker>,
}

Conclusion

Agent wallets provide a powerful mechanism for delegated trading while maintaining security. They enable high-frequency, automated, and user-friendly trading experiences without compromising the self-custody model.

Key Takeaways:

Session wallets for browser trading (1 per main wallet)
Named agents for API/bot trading (3 per main wallet)
Independent nonce tracking per agent
Revocable access, limited permissions
Secure by default, flexible by design

Next Steps:

EIP-712 Signing Authentication Nonce Management

PreviousSecurity & Signatures NextEIP-712 Signing

Last updated 1 month ago

Good morning

Overview

How Agent Wallets Work

Architecture

Wallet Types

Master Accounts

Subaccounts

Session Wallets (Browser Trading)

Setup Process

Security Properties

Example Flow

API Wallets (Programmatic Trading)

Setup Process

Security Considerations

Registration Process

EIP-712 Authorization Message

Validation

Agent Limits

Master Account Limits

Subaccount Limits

Enforcement

Agent Nonce Management

Independent Nonce Tracking

Nonce Validation

Revocation

Revoking Agents

Effects of Revocation

Automatic Revocation

Security Best Practices

For Session Wallets

For API Wallets

For Main Wallets

Common Workflows

Daily Trading (Session Wallet)

Bot Trading (API Wallet)

Market Making (Multiple Agents)

Troubleshooting

"Agent Limit Exceeded"

"Agent Already Exists"

"Invalid Agent Signature"

"Session Lost on Refresh"

Technical Implementation

Data Structure (from codebase)

Conclusion