DEV Community

Cover image for 14-Package Monorepo: How We Structured WAIaaS for AI Agent Builders
Wallet Guy
Wallet Guy

Posted on

14-Package Monorepo: How We Structured WAIaaS for AI Agent Builders

#web3 #ai #opensource #tutorial

When you're building complex AI infrastructure like WAIaaS—a Wallet-as-a-Service that lets AI agents interact with blockchains—you face a classic problem: how do you organize code that spans everything from transaction pipelines to admin UIs to MCP integrations? The answer isn't a single massive codebase, but a carefully structured monorepo that makes it easy for AI agent builders to grab exactly what they need.

Why Monorepo Architecture Matters for AI Agent Infrastructure

WAIaaS isn't just a wallet service—it's a complete ecosystem. AI agents need wallets, but they also need policy engines, transaction pipelines, admin interfaces, SDK integration, and connections to 14 different DeFi protocols. When your users are building autonomous agents that handle real money, every component needs to work together seamlessly.

The traditional approach of separate repositories creates dependency hell. Version mismatches between the core daemon and the SDK. Breaking changes in the transaction schema that don't propagate to the admin UI. MCP tools that work with v1.2 of the API but break with v1.3. For developers building AI agents, this friction is deadly—they want to focus on agent logic, not infrastructure debugging.

The 15-Package Structure: Separation by Purpose, Not Technology

WAIaaS uses a 15-package monorepo that separates concerns by what developers actually need, not by technical implementation details. Here's how it breaks down:

Core Infrastructure (3 packages):

  • core — Schemas, types, and shared business logic
  • daemon — Main API server with 39 REST routes and 7-stage transaction pipeline
  • shared — Network definitions and utilities

Developer Interfaces (4 packages):

  • sdk — TypeScript SDK with 40+ methods for agent builders
  • mcp — 45 MCP tools for Claude Desktop integration
  • openclaw-plugin — 5 tools for external AI frameworks
  • cli — 20 commands for setup and management

User Interfaces (2 packages):

  • admin — Preact-based web UI for wallet management and policy configuration
  • desktop-spike — Desktop wallet prototype

Protocol Integration (2 packages):

  • actions — 14 DeFi protocol providers (Jupiter, Aave, Hyperliquid, etc.)
  • adapters — Blockchain adapters for EVM and Solana

Supporting Services (4 packages):

  • push-relay — Real-time notifications for transaction approvals
  • wallet-sdk — Low-level wallet operations
  • skills — Pre-built agent skills
  • e2e-tests — Integration test suite

This structure means AI agent builders can import exactly what they need. Building a trading bot? You want the SDK and maybe the MCP package. Integrating with a custom framework? Grab the actions package directly. Need to extend DeFi support? The actions package is self-contained with clear provider interfaces.

How the Packages Work Together

Let's trace through what happens when an AI agent wants to swap tokens on Jupiter:

Step 1: Agent calls SDK

import { WAIaaSClient } from '@waiaas/sdk';

const client = new WAIaaSClient({
  baseUrl: 'http://127.0.0.1:3100',
  sessionToken: process.env.WAIAAS_SESSION_TOKEN,
});

const result = await client.executeAction('jupiter-swap', 'swap', {
  inputMint: 'So11111111111111111111111111111111111111112', // SOL
  outputMint: 'EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v', // USDC
  amount: '1000000000' // 1 SOL
});
Enter fullscreen mode Exit fullscreen mode

Step 2: SDK calls daemon API
The SDK (TypeScript, zero dependencies) makes an HTTP request to the daemon's /v1/actions/jupiter-swap/swap endpoint.

Step 3: Daemon validates and routes
The daemon (packages/daemon) validates the session token, checks policies from core schemas, and routes to the Jupiter provider in actions.

Step 4: Jupiter provider executes

// In packages/actions/src/providers/jupiter-swap/
export async function swap(params: SwapParams) {
  const quote = await getQuote(params);
  const transaction = await buildSwapTransaction(quote);
  return { transaction, quote };
}
Enter fullscreen mode Exit fullscreen mode

Step 5: Transaction pipeline processes
The daemon runs the transaction through its 7-stage pipeline (validate → auth → policy → wait → execute → confirm → stages), using policy types from core and network definitions from shared.

Step 6: Real-time updates
If the transaction needs approval, push-relay sends real-time notifications. The admin UI updates the pending transactions view.

Every package has a clear role, but they compose into a complete system. The agent builder only sees the SDK interface, but underneath, the entire monorepo is working together.

MCP Integration: 45 Tools in One Package

The MCP integration showcases why the monorepo structure works so well. Claude Desktop users get 45 tools through a single npm package:

{
  "mcpServers": {
    "waiaas": {
      "command": "npx",
      "args": ["-y", "@waiaas/mcp"],
      "env": {
        "WAIAAS_BASE_URL": "http://127.0.0.1:3100",
        "WAIAAS_SESSION_TOKEN": "wai_sess_<your-token>"
      }
    }
  }
}
Enter fullscreen mode Exit fullscreen mode

The MCP package (packages/mcp) provides tools like get-balance, send-token, execute-action, and x402-fetch, but it doesn't reimplement any business logic. Instead, it:

  1. Uses schemas from core for request validation
  2. Makes API calls to daemon endpoints
  3. Leverages shared utilities for address formatting
  4. Benefits from the full DeFi integration in actions

Because everything is in the same repo with shared tooling, the MCP tools stay in sync with API changes automatically. When we add a new policy type to core, the MCP tools immediately understand it. When actions adds a new DeFi protocol, the execute-action tool can use it without updates.

Docker Deployment: Multiple Images, Single Repo

The monorepo also simplifies deployment. We ship 2 Docker images from the same codebase:

services:
  daemon:
    image: ghcr.io/minhoyoo-iotrust/waiaas:latest
    ports:
      - "127.0.0.1:3100:3100"
    environment:
      - WAIAAS_AUTO_PROVISION=true
    restart: unless-stopped
Enter fullscreen mode Exit fullscreen mode

The main Dockerfile builds the daemon with the admin UI bundled in. A separate Dockerfile in packages/push-relay/ builds the notification service. Both use the same shared and core packages, ensuring consistency.

For AI agent builders, this means one docker compose up -d gets you the entire wallet service, with all 14 DeFi protocols and the full API surface available immediately.

Policy Engine: 21 Types, 4 Tiers

The policy engine demonstrates the power of the monorepo structure. It uses 21 policy types and 4 security tiers (INSTANT, NOTIFY, DELAY, APPROVAL), but the complexity is hidden behind clean interfaces:

curl -X POST http://localhost:3100/v1/policies \
  -H 'Content-Type: application/json' \
  -H 'X-Master-Password: <password>' \
  -d '{
    "walletId": "<wallet-uuid>",
    "type": "SPENDING_LIMIT",
    "rules": {
      "instant_max_usd": 10,
      "notify_max_usd": 100,
      "delay_max_usd": 1000,
      "delay_seconds": 300,
      "daily_limit_usd": 500
    }
  }'
Enter fullscreen mode Exit fullscreen mode

The policy definitions live in core/src/enums/policy.ts, the validation logic in core/src/schemas/policy.schema.ts, the enforcement in daemon/src/pipeline/stage3-policy.ts, and the UI in admin/src/components/PolicyEditor.tsx. But they're all validated by the same TypeScript compiler, tested by the same test suite, and versioned together.

What This Means for AI Agent Builders

This structure gives you flexibility without complexity:

Option 1: Use the SDK (most common)

import { WAIaaSClient } from '@waiaas/sdk';
// Full wallet functionality, 40+ methods, zero dependencies
Enter fullscreen mode Exit fullscreen mode

Option 2: Use MCP with Claude

waiaas mcp setup --all  # Auto-register with Claude Desktop
# Claude gets 45 wallet tools automatically
Enter fullscreen mode Exit fullscreen mode

Option 3: Build custom integrations

import { executeAction } from '@waiaas/actions';
// Direct access to DeFi protocols
Enter fullscreen mode Exit fullscreen mode

Option 4: Extend the system

// Add new DeFi protocols in packages/actions/src/providers/
// Add new policy types in packages/core/src/enums/policy.ts
// Everything stays in sync
Enter fullscreen mode Exit fullscreen mode

You can start simple with the SDK and grow into deeper integration as your agent becomes more sophisticated. The monorepo ensures that whatever level you engage at, you're working with a consistent, well-tested system.

Getting Started: From Zero to AI Agent Wallet

Here's how to get your AI agent connected to the blockchain in under 5 minutes:

  1. Install and start WAIaaS: 
npm install -g @waiaas/cli
waiaas init
waiaas start
waiaas quickset --mode mainnet  # Creates wallets + MCP sessions
Enter fullscreen mode Exit fullscreen mode
  1. Set up Claude integration: 
waiaas mcp setup --all  # Auto-configure Claude Desktop
Enter fullscreen mode Exit fullscreen mode
  1. Test with your AI agent: 
import { WAIaaSClient } from '@waiaas/sdk';

const client = new WAIaaSClient({
  baseUrl: 'http://127.0.0.1:3100',
  sessionToken: process.env.WAIAAS_SESSION_TOKEN,
});

const balance = await client.getBalance();
console.log(`Agent wallet: ${balance.balance} ${balance.symbol}`);
Enter fullscreen mode Exit fullscreen mode

The monorepo structure means this simple setup gives you access to everything: 14 DeFi protocols, 21 policy types, NFT support, cross-chain bridging, liquid staking, and more. All from packages that are tested together, versioned together, and designed to work together.

Ready to Give Your AI Agent a Wallet?

WAIaaS's 15-package monorepo isn't just about code organization—it's about making blockchain integration as simple as adding another tool to your AI agent's toolkit. Whether you're building with Claude's MCP, LangChain, or custom frameworks, the structured approach means you can start simple and scale up without architectural rewrites.

Check out the full codebase and documentation at https://github.com/minhoyoo-iotrust/WAIaaS, or visit https://waiaas.ai to see what's possible when your AI agents can finally handle their own money.

Top comments (0)