Are you an LLM? Read llms.txt for a summary of the docs, or llms-full.txt for the full context.
Wallet patterns for agents · Boson Protocol
Skip to content

Wallet patterns for agents

Agent wallets have different operational requirements than human wallets. There's no human to click MetaMask; the agent must sign autonomously, often hundreds of times a day.

For the general wallet discussion, see Concepts → Wallets & key management. This page is agent-specific.

Pick the right pattern

PatternUse whenCaveats
Server EOA in a managed signer (KMS, Vault, Fireblocks, Privy, Turnkey)Default for backend agentsLimit blast radius — separate wallet per agent role
Session key delegated from a Safe / 4337 accountAgents with bounded authority (max spend, max ops/day)Requires smart-account wallet for the principal
MPC-controlled keyMulti-party operational controlHigher latency per signature
Local EOA in env varDemo / dev onlyNever in production

Server EOA pattern

The agent process never holds the raw key. It calls a signing API ("please sign this typed-data / this tx"). The SDK accepts a signer object — wire your KMS client into it.

Session keys

If your agent runs untrusted code (an LLM with broad tool access), bound its authority:

  1. Master wallet: a Safe or ERC-4337 smart account. Owners are humans (or another agent).
  2. Master authorizes a session key with rules: max value per tx, allowed function selectors, expiry.
  3. Agent uses the session key for day-to-day Boson calls.
  4. Master can revoke any time.

The Diamond's MetaTransactionsHandlerFacet accepts EIP-1271 signatures, so smart-account signing works out of the box.

Funding & gas

Alerts at 0.5× / 0.2× / 0.1× expected daily burn. Don't let an agent go dark from running out of gas.

Nonce management

If your agent fires transactions in tight loops:

  • Sequential: easiest. Block on receipt of tx N before sending tx N+1.
  • Parallel: track nonce yourself; bump after each sendTransaction. Handle out-of-order receipts.

For very high throughput, use meta-tx + a forwarder/facilitator — the relayer manages nonces for you.

Common footguns

  • Reused keys across staging / production. Always separate. A staging compromise must not affect production.
  • Logging full transaction objects. They contain signatures. Logs leak.
  • Race conditions on approve. Two parallel approves of the same allowance fight; the second may fail. Serialize approvals per token.

Next