Docker Compose makes it possible to run your own crypto wallet infrastructure for AI agents in just one command, giving you complete control over your private keys without trusting any third-party service. Self-hosted wallet infrastructure eliminates custody risks while providing unlimited API access without rate limits or monthly fees.

Why Self-Custody Matters for AI Agents

When your AI agents handle real money, custody becomes critical. Hosted wallet services create a fundamental contradiction: you're building autonomous agents while surrendering control to centralized providers. Every transaction flows through someone else's infrastructure, subject to their terms, rate limits, and potential service interruptions.

Self-hosting puts you back in control. Your private keys never leave your server. Your transaction policies run on your hardware. Your AI agents operate with the sovereignty that crypto was designed to enable. It's the difference between renting computational power and owning your infrastructure.

WAIaaS: Docker-First Wallet Infrastructure

WAIaaS delivers enterprise-grade wallet functionality through a 15-package monorepo designed for self-hosting. The Docker deployment supports 2 Docker images (the main daemon plus push-relay for notifications), auto-provision for zero-touch setup, and production secrets overlay via docker-compose.secrets.yml.

The architecture provides 39 REST API route modules accessible through a simple session-based authentication system. AI agents authenticate with JWT tokens while owners retain ultimate control through cryptographic signatures. This separation lets you grant spending permissions without giving up custody.

Quick Start: Zero to Running

Clone and start — that's it:

git clone https://github.com/minhoyoo-iotrust/WAIaaS.git
cd WAIaaS
docker compose up -d

For completely hands-off deployment with auto-generated credentials:

docker run -d \
 --name waiaas \
 -p 127.0.0.1:3100:3100 \
 -v waiaas-data:/data \
 -e WAIAAS_AUTO_PROVISION=true \
 ghcr.io/minhoyoo-iotrust/waiaas:latest

# Retrieve auto-generated master password
docker exec waiaas cat /data/recovery.key

The default port binding (127.0.0.1:3100:3100) keeps your API private to localhost unless you explicitly expose it. Auto-provision generates a secure master password and saves it to /data/recovery.key for later hardening.

Production Deployment with Secrets

For production environments, use Docker Secrets to avoid environment variable exposure:

# Create secret files
mkdir -p secrets
echo "your-secure-password" > secrets/master_password.txt
chmod 600 secrets/master_password.txt

# Deploy with secrets overlay
docker compose -f docker-compose.yml -f docker-compose.secrets.yml up -d

The secrets overlay supports production patterns like external secret management and automated rotation. The daemon runs as non-root (UID 1001) with healthcheck endpoints and restart policies.

Multi-Chain Support Out of the Box

WAIaaS supports 2 chain types (evm, solana) across 18 networks, from Ethereum mainnet to Solana devnet. Chain configuration happens through environment variables:

WAIAAS_RPC_SOLANA_MAINNET=https://api.mainnet-beta.solana.com
WAIAAS_RPC_EVM_ETHEREUM_MAINNET=https://eth-mainnet.g.alchemy.com/v2/YOUR-KEY
WAIAAS_DAEMON_PORT=3100
WAIAAS_DAEMON_LOG_LEVEL=info

No external dependencies beyond your chosen RPC providers. You can use public endpoints for testing or private RPC services for production workloads.

Policy-Driven Security

Self-hosting doesn't mean self-endangering. WAIaaS includes a sophisticated policy engine with 21 policy types and 4 security tiers (INSTANT/NOTIFY/DELAY/APPROVAL) that let you define exactly what your AI agents can do.

Create spending limits that escalate based on transaction size:

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,
 "monthly_limit_usd": 5000
 }
 }'

The policy system follows default-deny enforcement — transactions are blocked unless explicitly allowed by ALLOWED_TOKENS or CONTRACT_WHITELIST policies. This prevents your agents from interacting with unknown contracts or tokens without your approval.

Time-based restrictions, rate limiting, and network restrictions provide additional guardrails. Your agents operate within bounds you define, with escalation paths for larger transactions.

API-First Architecture

The 39 REST API endpoints expose every wallet function through consistent HTTP interfaces. AI agents authenticate with session tokens and interact through standard HTTP:

# Check wallet balance (sessionAuth)
curl http://127.0.0.1:3100/v1/wallet/balance \
 -H "Authorization: Bearer wai_sess_eyJhbGciOiJIUzI1NiJ9..."

# Execute DeFi action (sessionAuth)
curl -X POST http://127.0.0.1:3100/v1/actions/jupiter-swap/swap \
 -H "Content-Type: application/json" \
 -H "Authorization: Bearer wai_sess_<token>" \
 -d '{
 "inputMint": "So11111111111111111111111111111111111111112",
 "outputMint": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
 "amount": "1000000000"
 }'

The API includes OpenAPI 3.0 spec auto-generated at /doc with interactive Scalar API reference UI at /reference. Standard error codes and consistent response formats make integration straightforward.

The 7-stage transaction pipeline (validate, auth, policy, wait, execute, confirm) provides full visibility into transaction state. Dry-run API support lets you test transactions before execution.

DeFi Integration Without Vendor Lock-in

WAIaaS integrates 15 DeFi protocol providers covering swaps, lending, staking, and bridges. Your agents can interact with Jupiter, Aave, Lido, Hyperliquid, and other major protocols without depending on external aggregator APIs.

curl -X POST http://127.0.0.1:3100/v1/actions/lido-staking/stake \
 -H "Content-Type: application/json" \
 -H "Authorization: Bearer wai_sess_<token>" \
 -d '{"amount": "1000000000000000000"}'

Cross-chain bridging via LI.FI and Across protocols enables multi-chain strategies. Liquid staking via Lido (EVM) and Jito (Solana) generates yield. Hyperliquid integration provides perpetual futures, spot trading, and sub-accounts.

All DeFi interactions respect your policy constraints and follow the same authentication model. No separate API keys or external service dependencies.

Monitoring and Observability

The Admin Web UI (Preact) provides wallet management, policy editor, and DeFi positions dashboard through a clean interface at /admin. Real-time monitoring shows transaction status, policy violations, and system health.

Incoming transaction monitoring with real-time notifications ensures you know when funds arrive. Push notifications through Telegram or custom webhooks keep you informed of significant events.

Structured logging and health check endpoints support standard monitoring tools. The Docker healthcheck uses curl -f http://localhost:3100/health with configurab...

DEV Community: devops

Message History

Delivery option(s)