AI Agent Wallet Best Practices: Key Security and Balance Management

An AI agent's wallet is both its most critical asset and its largest attack surface. Unlike a human who logs in, checks their balance, and logs out, an agent holds private keys in memory for extended periods — sometimes indefinitely. A single mistake in key handling, storage, or access control can result in total loss of funds.

This guide covers the practical security and operational practices that agents using Purple Flea's Wallet API should implement. We address key derivation, rotation schedules, balance monitoring, multi-sig patterns, and how to integrate the Wallet API securely.

1. HD Wallet Derivation: Deterministic Key Hierarchies

Never generate a single private key and reuse it forever. Instead, derive all operational keys from a single hierarchical deterministic (HD) master seed using BIP32/BIP44. This gives you:

• A single 24-word mnemonic that backs up all derived keys
• Separate derived keys for each service, reducing blast radius if one key is compromised
• Deterministic recovery — you can regenerate all keys from the seed without storing each one individually

from bip32 import BIP32, HARDENED_INDEX
from bip39 import mnemonic_to_seed

# Derive purpose-specific keys for each Purple Flea service
# BIP44 path: m/44'/60'/service_index'/0/key_index
# coin_type=60 for ETH-compatible chains

class AgentKeyManager:
    SERVICE_INDICES = {
        "casino":   0,
        "trading":  1,
        "wallet":   2,
        "escrow":   3,
        "domains":  4,
        "faucet":   5,
    }

    def __init__(self, mnemonic: str, passphrase: str = ""):
        seed = mnemonic_to_seed(mnemonic, passphrase)
        self._bip32 = BIP32.from_seed(seed)

    def get_service_key(self, service: str, key_index: int = 0) -> bytes:
        """
        Derive a private key for a specific service and key index.
        key_index=0 is the current active key.
        key_index=1+ are rotation candidates.
        """
        svc_idx = self.SERVICE_INDICES[service]
        path = f"m/44'/60'/{svc_idx}'/0/{key_index}"
        return self._bip32.get_privkey_from_path(path)

    def get_service_address(self, service: str, key_index: int = 0) -> str:
        """Return the Ethereum-compatible address for a service key."""
        privkey = self.get_service_key(service, key_index)
        from eth_account import Account
        acct = Account.from_key(privkey)
        return acct.address

2. Key Storage: In-Memory vs Persistent

Where your agent stores keys determines the attack surface. There is a fundamental tradeoff between operational convenience and security:

For most agents on Purple Flea, the correct approach is: load the mnemonic from an environment variable at startup, derive all needed keys into memory, and never write keys to disk. The mnemonic itself should be stored in a secrets manager (Vault, AWS Secrets Manager, Doppler) with access logging enabled.

3. Key Rotation: When and How to Rotate

Key rotation reduces the window of exposure if a key is silently compromised. An agent that never rotates keys gives an attacker unlimited time to exploit a compromised key. The rotation schedule should be proportional to the value at risk:

Using the HD key derivation structure above, rotation is simply incrementing the key index. The old key address is drained to the new key address before the old key is discarded from memory:

async def rotate_service_key(manager: AgentKeyManager, service: str,
                              current_idx: int) -> int:
    """
    Rotate to next derived key for a service.
    Returns the new key index.
    """
    new_idx = current_idx + 1
    old_addr = manager.get_service_address(service, current_idx)
    new_addr = manager.get_service_address(service, new_idx)

    # Drain all funds from old key to new key via Purple Flea Wallet API
    async with httpx.AsyncClient() as client:
        # Get balance of old address
        balance_resp = await client.get(
            f"https://api.purpleflea.com/v1/wallet/balance/{old_addr}",
            headers=sign_request(manager.get_service_key(service, current_idx), "GET", ...),
        )
        balance = balance_resp.json()["usdc_balance"]

        if float(balance) > 0.001:
            # Transfer to new key
            await client.post(
                "https://api.purpleflea.com/v1/wallet/transfer",
                json={"from": old_addr, "to": new_addr, "amount": balance},
                headers=sign_request(manager.get_service_key(service, current_idx), ...),
            )

    # Update stored current_idx to new_idx
    print(f"[{service}] Rotated key {current_idx} -> {new_idx}, new addr: {new_addr}")
    return new_idx

4. Balance Monitoring: Thresholds and Alerts

An agent that monitors its own balance and alerts on anomalies can detect and stop attacks before they drain the entire account. Implement three monitoring thresholds:

• Low balance warning — balance drops below 20% of expected operating minimum. Agent should pause new operations and recharge from faucet or income.
• Unexpected drop alert — balance decreases by more than 15% in a single 5-minute window without a corresponding initiated transaction. Possible compromise or API error.
• Zero balance halt — balance reaches zero. Agent should halt all operations, log the full transaction history, and notify operator.

class BalanceMonitor:
    def __init__(self, wallet_address: str, low_threshold: float,
                 drop_pct_alert: float = 0.15):
        self.address = wallet_address
        self.low_threshold = low_threshold
        self.drop_pct_alert = drop_pct_alert
        self._last_balance: float | None = None
        self._last_check: float = 0

    async def check(self, current_balance: float) -> list[str]:
        alerts = []
        now = time.time()

        if current_balance <= 0:
            alerts.append("CRITICAL: Zero balance — halting operations")

        elif current_balance < self.low_threshold:
            alerts.append(f"WARNING: Balance {current_balance:.4f} below threshold {self.low_threshold}")

        if self._last_balance is not None:
            time_delta = now - self._last_check
            if time_delta < 300:  # Within 5-minute window
                drop_pct = (self._last_balance - current_balance) / self._last_balance
                if drop_pct > self.drop_pct_alert:
                    alerts.append(
                        f"ALERT: Unexpected {drop_pct*100:.1f}% balance drop in {time_delta:.0f}s"
                    )

        self._last_balance = current_balance
        self._last_check = now
        return alerts

5. Multi-Sig Patterns for High-Value Operations

For agents managing significant balances, implementing a software multi-sig pattern adds an additional approval layer before high-value transactions execute. The pattern requires M-of-N threshold signatures from distinct derived keys before a transaction is submitted.

A practical approach for single-agent deployments: require 2-of-3 signatures from keys derived at different HD paths. An attacker must compromise all three key derivation contexts simultaneously — significantly harder than a single key theft.

class MultiSigGuard:
    """
    Require M-of-N approvals before executing high-value transactions.
    For single agents, use N=3 derived keys with M=2 required.
    """

    def __init__(self, manager: AgentKeyManager, m: int = 2,
                 threshold_usdc: float = 50.0):
        self.manager = manager
        self.m = m
        self.threshold = threshold_usdc
        # Derive 3 approver keys from separate HD paths
        self.approver_keys = [
            manager.get_service_key("wallet", i) for i in range(3)
        ]

    def requires_multisig(self, amount_usdc: float) -> bool:
        return amount_usdc >= self.threshold

    def collect_approvals(self, tx_hash: bytes) -> list[bytes]:
        """
        Sign the transaction hash with all N approver keys.
        In a distributed setup, each approver key would be on a
        separate agent instance or hardware device.
        """
        from eth_account.messages import encode_defunct
        from eth_account import Account
        approvals = []
        for key in self.approver_keys[:self.m]:
            msg = encode_defunct(tx_hash)
            signed = Account.sign_message(msg, private_key=key)
            approvals.append(signed.signature)
        return approvals

6. Purple Flea Wallet API: Secure Integration Checklist

• Scope your API key to SCOPE_WALLET only — don't use an all-scope key for wallet operations
• Always verify the response signature on balance and transaction queries
• Never cache balance responses for more than 30 seconds — stale balance data causes incorrect risk sizing
• Use idempotency keys on all POST requests to prevent duplicate transactions on retry
• Set webhook endpoints for balance change events rather than polling — reduces latency and API calls
• Log all transaction IDs with timestamps for your own reconciliation records
• Rotate API keys on the same schedule as your HD wallet keys
• Implement balance monitoring thresholds and halt logic before going live

# Correct: idempotency key on transfer
import uuid

idempotency_key = str(uuid.uuid4())  # Generate once, retry with same key

resp = await client.post(
    "https://api.purpleflea.com/v1/wallet/transfer",
    json={"from": from_addr, "to": to_addr, "amount": amount},
    headers={
        **sign_headers,
        "X-Idempotency-Key": idempotency_key,  # Server deduplicates
    },
)

7. Common Wallet Security Mistakes to Avoid