Agent Wallets

What Is an Agent Wallet?

An agent wallet is a wallet whose private key is held and used by an autonomous process (an AI system, an automated service, or a programmatic agent) rather than directly by a human.

On the protocol level, an agent wallet is indistinguishable from any other wallet. It has an address, signs transactions, and appears in every block it participates in. What distinguishes it is:

Ownership: It is created by and subordinate to a human (or organizational) wallet.
Entity type: It is associated with a SERVICE, DEVICE, or AGENT entity (leaf types with no children).
Scope: Its permissions are bounded by capabilities that define exactly what it can do, how many times, and until when.
Traceability: Every transaction it signs is permanently attributed to it, and through it, to the entire chain of principals that authorized its existence.

Why Agent Wallets Instead of API Keys

Traditional autonomous systems operate with shared API keys or service accounts:

Shared API Key	Agent Wallet
No per-action attribution; any process using the key looks the same.	Every action is signed by a specific wallet address.
Logs are mutable; any authorized admin can alter or delete them.	Transactions are immutable once committed to a block.
Key scope is coarse, all-or-nothing for the service.	Capabilities scope the key to specific actions, resource addresses, counts, and block-height expiry.
Revocation requires cycling the key and updating all consumers.	Disabling the parent wallet cascades instantly to all child agent wallets.
Audit trail lives in application logs, siloed per system.	Audit trail is on-chain, visible to any authorized auditor without system access.
Post-quantum vulnerable (most API key schemes use symmetric or classical crypto).	ML-DSA-87 chains are post-quantum secure by construction.

The audit trail is the primary value. An agent wallet produces authored transactions: each one cryptographically signed, cross-Merkleized with the rest of the council's output, and anchored in a STARK checkpoint proof that an auditor can verify without access to any live system.

Procuring an Agent Wallet

"Procuring" an agent wallet means: a human (or organizational) wallet creates a child wallet and a corresponding AGENT entity, scopes that wallet's capabilities, and hands the private key file to the autonomous process.

Step 1: Generate the Agent Wallet

go run ./cmd/generate_wallets --type=mldsa87

This creates a .ukey file (the agent's private key). The human principal retains custody of this file and provides it to the autonomous process at runtime.

Step 2: Register the Wallet

go run ./cmd/register_wallets

Submits TX_CREATE_WALLET to on-board the wallet. The submitting (parent) wallet becomes the Parent of the new wallet.

Step 3: Create the AGENT Entity

{
    "name": "alice-research-agent",
    "entityType": "AGENT",
    "parent": "<alice-personal-entity-address>",
    "metadata": {
        "description": "Autonomous market research assistant",
        "pref:budget_monthly": "5000"
    }
}

The AGENT entity is the organizational identity for this autonomous process. It is a child of Alice's PERSONAL entity, making Alice the organizational principal.

Step 4: Link the Agent Wallet to the AGENT Entity

{
    "entityAddress": "<agent-entity-address>",
    "walletAddress": "<agent-wallet-address>",
    "role": "admin",
    "permissions": {
        "ManageWallets": false,
        "ManageChildren": false,
        "ManageAccessList": false,
        "ManageMetadata": true,
        "TransferOwnership": false
    }
}

The agent wallet is linked to its entity. ManageMetadata: true allows the agent to update its own metadata (e.g., record its last task). Other permissions are withheld; the agent cannot create sub-entities or manage its own access lists.

Step 5: Attach Capabilities

Capabilities are the primary gate on what an agent wallet can do. Without an explicit capability for an action, the wallet cannot perform it, even if the contract would otherwise allow it. For the full field reference, action types, and patterns see Capabilities.

Example: scoping an agent to one contract and one token:

{
    "walletAddress": "<agent-wallet-address>",
    "capabilities": [
        {
            "action": "contract:invoke",
            "resource": "<council-contract-address>",
            "limits": { "maxInvocations": 500 },
            "notAfter": 100000
        },
        {
            "action": "token:transfer",
            "resource": "<work-token-address>",
            "limits": { "maxAmount": "10000" },
            "notAfter": 100000
        }
    ]
}

The Agent Wallet Lifecycle

CREATION
    Human parent wallet → TX_CREATE_WALLET → agent wallet on-chain
    Human parent → CREATE_ENTITY (AGENT type) → agent entity
    Human parent → LINK_WALLET_TO_ENTITY → wallet linked to agent entity
    Human parent → ALTER_WALLET (capabilities) → agent scoped

OPERATION
    Agent wallet signs TX → submits via SDK or HTTP
    Node validates: ancestry enabled? capabilities match? scope not exceeded?
    Transaction executes → state committed → block produced
    Helix checkpoint anchors the block into the STARK proof chain

ADMINISTRATION
    Human parent → ALTER_WALLET (enable=false) → agent suspended
    Human parent → ALTER_ENTITY (enabled=false) → agent entity suspended
    Human parent → ALTER_WALLET (new capabilities) → agent re-scoped
    Human parent → ALTER_WALLET (enable=true) → agent re-activated

TERMINATION
    Human parent → ALTER_WALLET (enable=false, permanent)
    Agent wallet address remains in history; its transactions are permanent
    Recovery config handles succession if the parent wallet is lost

The Audit Trail

Every transaction the agent wallet submits is permanently recorded:

Who: the agent wallet's address (and through wallet.Parent, its human principal).
What: the transaction type, payload, and target (contract, entity, token).
When: the block height at which it was committed.
In what context: the entity hierarchy at the time (ORG → DEPT → PERSONAL → AGENT).
Under what scope: the capability that authorized the action.
Provably ordered: by the Merkle chain of blocks, anchored by Helix STARK checkpoints.

An auditor with the council's public keys and the checkpoint proofs can reconstruct and verify this trail without any access to the live system, the SDK, or the wallet files.

Multi-Agent Hierarchies

An agent can own sub-wallets, but only if its entity type allows it (AGENT does not allow children). If you need a hierarchy of agents, use nested PERSONAL or SERVICE entities:

PERSONAL: "alice"
├── AGENT: "alice-orchestrator" (manages sub-tasks)
│   (Cannot own child agents; AGENT is a leaf type)
│
└── SERVICE: "alice-pipeline-service"
    (Can own child SERVICE/DEVICE/AGENT entities if SERVICE hierarchy is desired)

For multi-agent orchestration where one agent coordinates others, the recommended pattern is:

The orchestrating agent holds the parent wallet.
Sub-task agent wallets are children of the orchestrating wallet.
Capabilities on sub-task wallets are scoped to the specific contracts and actions they need.
The orchestrating agent can disable sub-task agents by disabling their parent wallet.

Agent Wallet in the Council Voting Pattern

The board-council demo illustrates the most common human+agent collaboration pattern: human council members each delegate an AI voting agent, agents vote autonomously within a time window, and a human chair finalizes on-chain.

For the full governance model description see Pattern 3: Hybrid Council. For a complete end-to-end walkthrough see Board Council Demo.

What Is an Agent Wallet?​

Why Agent Wallets Instead of API Keys​

Procuring an Agent Wallet​

Step 1: Generate the Agent Wallet​

Step 2: Register the Wallet​

Step 3: Create the AGENT Entity​

Step 4: Link the Agent Wallet to the AGENT Entity​

Step 5: Attach Capabilities​

The Agent Wallet Lifecycle​

The Audit Trail​

Multi-Agent Hierarchies​

Agent Wallet in the Council Voting Pattern​