---
summary: Design SigID agent wallet models, signing controls, spending limits, human approval gates, and incident response practices.
tags:
  - agents
  - wallets
  - signing
  - approvals
  - incident response
categories:
  - AI Agents
  - Security
---

# Agent Wallets

<!-- agent:page
You are a coding agent designing or wiring SigID agent wallet access by following this reference.
First collect: wallet owner subject, tenant context, chain, custody model, signing algorithm, budget limits, allowlists, delegation requirements, approval gates, and incident-response contacts.
Provision wallets only for allowed human or agent subjects, enforce app-layer wallet access after route-scope checks, mask cross-subject denials as not_found where the API does so, and keep Identity personal wallet flows distinct from tenant-wide reporting.
For signing, take delegation context only from validated token claims, never from request JSON; enforce delegation limits first, wallet limits second, allowlists and frozen state before signing, and atomic spend accounting around transaction status changes.
Verify blocked paths for frozen wallets, self-custody server signing, wrong chain, missing budget, exceeded delegation caps, exceeded wallet caps, disallowed recipients, and revoked delegated access.
-->

Agents can have managed crypto wallets for on-chain interactions, payments,
and ERC-8004 ecosystem participation.

## Wallet Models

| Model | Trust Model |
|---|---|
| Self-Custody Keys | Non-custodial: agent holds private key. IDP verifies against registered public key. |
| Software-Signed Wallet | Keys encrypted in SigID's database (AES-256-GCM). Signing performed in-process. |
| HSM-Signed Wallet | Keys generated and held in external HSM. Signing via external API call. |
| TSS (Threshold Signing) | Threshold signature scheme via external API call. |
| ERC-4337 Smart Account | On-chain session key constraints. Defense-in-depth. |

## Budget Enforcement

Agents can have spending limits:

- Per-transaction limits
- Daily spending caps
- Monthly spending caps
- Recipient allowlists
- Contract allowlists
- Emergency freeze

For ERC-4337 smart accounts, session policies constrain direct
`account.execute(...)` actions. Installed executor modules, such as x402
payment executors, run under the wallet's module-install authority; their
internal callbacks are not checked again against the session action
allowlist. Treat executor installation and replacement as high-trust wallet
administration.

## Human Approval

Require approval for:

| Action | Recommended gate |
|---|---|
| Sending messages or emails | User confirmation or policy allowlist |
| Changing billing or ownership | Fresh MFA and human approval |
| Deleting data | Delegated token plus explicit approval |
| Signing wallet transactions | Wallet budget, allowlist, and approval |
| Exporting data | Audit event and limited scope |

## Incident Response

If an agent is compromised:

1. Suspend the agent
2. Revoke active agent keys
3. Revoke delegated tokens and vault grants
4. Freeze wallet signing if relevant
5. Review recent audit logs and webhooks
6. Rotate downstream credentials if the agent could access them

## API Surface

| Endpoint | Use |
|---|---|
| `GET /api/v1/wallets` | List wallets |
| `POST /api/v1/wallets` | Create a wallet |
| `GET /api/v1/wallets/{id}` | Read wallet details |
| `POST /api/v1/wallets/{id}/sign` | Sign a transaction |
| `POST /api/v1/wallets/{id}/freeze` | Emergency freeze |
| `POST /api/v1/wallets/{id}/unfreeze` | Resume signing after review |
| `DELETE /api/v1/wallets/{id}` | Deprovision a wallet |
| `GET /api/v1/wallets/{id}/budget` | Inspect budget and spend state |
| `PUT /api/v1/wallets/{id}/budget` | Set spending and allowlist controls |
| `GET /api/v1/wallets/{id}/transactions` | Review transaction history |

## See Also

- [Agent Authentication](agent-auth.md) - Agent identity
- [OAuth And OIDC](../reference/oauth-oidc.md) - OAuth and login integration