Architecture

Security Model

The agent wallet uses a layered security model:

ARC-58 Escrow

The agent operates within a sandboxed escrow on the owner’s wallet. The escrow can be locked or revoked at any time by the wallet owner. The agent has no direct access to the wallet’s main account — all operations go through the escrow.

Plugin System

Each action (pay, stake, swap) is a plugin that must be explicitly installed on the escrow. The agent can only execute actions for installed plugins. Uninstalled plugins are completely inaccessible.

Spending Allowances

The wallet owner sets daily spending limits per asset per escrow:

Type	Behavior
Flat	A fixed total spending limit
Window	Replenishes after a time interval
Drip	Continuous linear replenishment up to a maximum

The agent cannot exceed these limits, even if it has the plugin installed.

Vault Signing

The agent’s private key never leaves HashiCorp Vault. Transactions are signed remotely via the Vault transit engine. Even if the agent’s process is compromised, the key remains secure.

Intermezzo Auth

Two-step authentication:

1. Vault AppRole — Initial authentication with role ID + secret ID
2. Pawn JWT — Token-based session management with automatic caching and renewal

Intermezzo Services

The setup wizard runs two Docker containers:

Service	Port	Description
Vault (HashiCorp)	8200	Key storage and transaction signing via transit engine
Pawn (Intermezzo)	3100	REST API layer over Vault, manages ed25519 keys and JWTs

These services must be running whenever the agent signs transactions.

Managing Docker Services

# Start services
docker compose -f packages/cli/docker/docker-compose.yml up -d

# Stop services
docker compose -f packages/cli/docker/docker-compose.yml down

# Reset (removes Vault data — will need to re-run setup)
docker compose -f packages/cli/docker/docker-compose.yml down
docker compose -f packages/cli/docker/docker-compose.yml up -d

Monorepo Structure

agent-wallet/
├── packages/
│   ├── core/                       # @akta/agent-wallet
│   │   └── src/
│   │       ├── agent-kit.ts        # AgentKit class (main entry point)
│   │       ├── types.ts            # Config and result types
│   │       ├── zod-to-json-schema.ts
│   │       ├── wallet-provider/
│   │       │   ├── local.ts        # LocalWalletProvider (dev/testing)
│   │       │   └── intermezzo.ts   # IntermezzoWalletProvider (production)
│   │       └── action-providers/
│   │           ├── wallet-info.ts  # Balance, escrow info, allowances
│   │           ├── pay.ts          # ALGO/ASA payments
│   │           ├── optin.ts        # Asset opt-in
│   │           ├── staking.ts      # Stake/withdraw
│   │           ├── dao.ts          # Proposals and voting
│   │           ├── marketplace.ts  # NFT listings
│   │           ├── swap.ts         # HyperSwap
│   │           ├── social.ts       # Posts and follows
│   │           ├── subscriptions.ts
│   │           ├── mint.ts         # Asset minting
│   │           ├── auction.ts      # Auction bids
│   │           ├── raffle.ts       # Raffle entries
│   │           ├── poll.ts         # Poll voting
│   │           └── rewards.ts      # Reward claims
│   ├── mcp/                        # @akta/agent-wallet-mcp
│   │   └── src/
│   │       ├── index.ts            # Entry point, env loading
│   │       ├── server.ts           # MCP server creation
│   │       ├── tools.ts            # Register actions as MCP tools
│   │       ├── resources.ts        # Wallet config/balance/allowance resources
│   │       └── prompts.ts          # wallet-overview, send-payment prompts
│   └── cli/                        # @akta/agent-wallet-cli
│       ├── src/
│       │   ├── index.ts            # CLI entry point and command routing
│       │   ├── setup.ts            # Interactive setup wizard
│       │   ├── bootstrap.ts        # Load .env and create AgentKit
│       │   ├── config-output.ts    # .env and MCP config generation
│       │   ├── skill-output.ts     # Claude Code SKILL.md generation
│       │   ├── signal.ts           # WebRTC signaling (liquid-auth)
│       │   └── commands/
│       │       ├── info.ts         # Wallet status
│       │       ├── actions.ts      # List actions
│       │       └── exec.ts         # Execute action
│       └── docker/
│           └── docker-compose.yml  # Vault + Pawn services
└── package.json                    # Root monorepo config

Connection Flow

When an agent wallet is set up:

1. CLI generates a key in Vault and creates a connect URI
2. QR code is displayed — the user scans it with the Akita mobile app
3. WebRTC connection is established via the liquid-auth signaling server
4. Install request is sent with agent config (plugins, allowances, escrow name)
5. Mobile app creates the escrow, installs plugins, sets allowances, and sends confirmation
6. CLI writes config — .env, MCP config, and Claude Code skill file

After setup, the agent can execute actions independently within its configured limits.

Available Plugins

During setup, the user chooses which plugins to install:

Plugin	Description
Pay	Send ALGO and ASA payments
Opt In	Opt into receiving new assets
Social	Post, follow, and interact on Akita social
Rewards	Claim staking and participation rewards
Staking	Stake tokens to earn rewards
DAO	Participate in DAO governance
Subscriptions	Enable recurring payments
Marketplace	List and purchase NFTs
Hyper Swap	Execute instant token swaps

Dependency Requirements

• algosdk and @algorandfoundation/algokit-utils must be pinned to exact versions (3.5.2 and 9.1.2) to match @akta/sdk peer dependencies
• .npmrc uses shamefully-hoist=true to prevent duplicate installations
• The typecheck script builds core before checking MCP/CLI, since they resolve core from dist/