API Key Security for AI Agents: Credential Management in Self-Hosted Wallets

API key security for AI agents becomes critical when those agents control cryptocurrency wallets — one leaked credential or compromised system could drain entire treasury balances. Unlike traditional API keys that might expose data or incur service charges, wallet credentials give direct access to irreversible financial transactions.

Why This Matters More Than Traditional API Security

Traditional API security focuses on rate limiting, token expiration, and access logging. But when AI agents hold wallet private keys, the stakes escalate dramatically. A compromised trading bot doesn't just leak your customer database — it can transfer your entire SOL balance to an attacker's address in seconds.

The challenge multiplies with autonomous agents. While a human developer might notice suspicious API activity, AI agents operate continuously, making thousands of micro-decisions without human oversight. Standard security practices like "rotate keys monthly" become meaningless when the key unlocks actual money.

The Three-Layer Security Model

WAIaaS addresses these risks through layered defense: session authentication controls what agents can access, policy engines enforce spending rules, and human approval channels provide final oversight for high-risk transactions.

Layer 1: Session-Based Authentication

Instead of giving AI agents direct wallet access, WAIaaS uses session tokens with limited scope and automatic expiration:

# Create a session for AI agent (masterAuth required)
curl -X POST http://127.0.0.1:3100/v1/sessions \
  -H "Content-Type: application/json" \
  -H "X-Master-Password: my-secret-password" \
  -d '{"walletId": "<wallet-uuid>"}'

Sessions use JWT HS256 tokens with configurable TTL, maximum renewals, and absolute lifetime limits. Even if an agent's session token leaks, the exposure window is bounded. The agent never sees the actual private key — only a time-limited session that can be revoked instantly.

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

const client = new WAIaaSClient({
  baseUrl: 'http://127.0.0.1:3100',
  sessionToken: process.env.WAIAAS_SESSION_TOKEN, // Limited-scope token, not private key
});

// Agent can check balance
const balance = await client.getBalance();

// But transactions require policy approval
const tx = await client.sendToken({
  to: 'recipient-address',
  amount: '0.1',
});

Layer 2: Default-Deny Policy Engine

WAIaaS implements 21 policy types across 4 security tiers (INSTANT, NOTIFY, DELAY, APPROVAL). The critical principle: transactions are denied unless explicitly allowed by policy configuration.

# Create spending limit policy
curl -X POST http://127.0.0.1:3100/v1/policies \
  -H "Content-Type: application/json" \
  -H "X-Master-Password: my-secret-password" \
  -d '{
    "walletId": "<wallet-uuid>",
    "type": "SPENDING_LIMIT",
    "rules": {
      "instant_max_usd": 10,
      "notify_max_usd": 100,
      "delay_max_usd": 1000,
      "delay_seconds": 900,
      "daily_limit_usd": 5000
    }
  }'

This spending policy creates a security gradient: small amounts execute instantly, medium amounts trigger notifications, larger amounts wait 15 minutes (allowing cancellation), and amounts above $1000 require explicit human approval.

The default-deny approach prevents the classic attack vector where agents interact with malicious contracts not anticipated during development. Without CONTRACT_WHITELIST and ALLOWED_TOKENS policies, the agent simply cannot execute those transactions:

# Whitelist specific tokens only
curl -X POST http://127.0.0.1:3100/v1/policies \
  -H "Content-Type: application/json" \
  -H "X-Master-Password: my-secret-password" \
  -d '{
    "walletId": "<wallet-uuid>",
    "type": "ALLOWED_TOKENS",
    "rules": {
      "tokens": [
        {"address": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v", "symbol": "USDC", "chain": "solana"}
      ]
    }
  }'

Layer 3: Human Approval Channels

For high-value transactions exceeding policy thresholds, WAIaaS routes approval requests through 3 signing channels: push notifications, Telegram bots, and WalletConnect integration.

# Transaction exceeding limits gets queued for approval
curl -X POST http://127.0.0.1:3100/v1/transactions/send \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer wai_sess_<token>" \
  -d '{
    "type": "TRANSFER",
    "to": "recipient-address",
    "amount": "5.0"
  }'

# Returns: {"id": "tx-uuid", "status": "PENDING_APPROVAL"}

The human owner receives push notification with transaction details and can approve/deny through their preferred channel. This creates an air gap between the AI agent and high-value transactions while maintaining operational efficiency for routine activities.

Credential Isolation and Recovery

WAIaaS separates three distinct credential types with different privilege levels:

• masterAuth (Argon2id): System administration — wallet creation, policy configuration, session management
• sessionAuth (JWT HS256): AI agent operations — balance queries, small transactions, DeFi interactions
• ownerAuth (SIWS/SIWE): Fund owner control — transaction approval, emergency kill switch

This separation means compromising one credential doesn't grant access to others. An agent's leaked session token cannot modify spending policies or create new wallets. A compromised master password cannot approve pending transactions — that requires cryptographic signatures from the fund owner.

# Different auth for different operations
# AI agent checks balance (sessionAuth)
curl http://127.0.0.1:3100/v1/wallet/balance \
  -H "Authorization: Bearer wai_sess_<token>"

# Human approves large transaction (ownerAuth)
curl -X POST http://127.0.0.1:3100/v1/transactions/<tx-id>/approve \
  -H "X-Owner-Signature: <ed25519-signature>" \
  -H "X-Owner-Message: <signed-message>"

Operational Security in Practice

The 7-stage transaction pipeline validates every request through multiple checkpoints before execution:

1. Validate — Schema validation, parameter checking
2. Auth — Session token verification, scope checking
3. Policy — Rule evaluation, tier assignment
4. Wait — Delay enforcement for DELAY-tier transactions
5. Execute — Blockchain transaction submission
6. Confirm — Transaction monitoring and finalization
7. Log — Audit trail recording

# Simulate before executing to catch policy violations
curl -X POST http://127.0.0.1:3100/v1/transactions/send \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer wai_sess_<token>" \
  -d '{
    "type": "TRANSFER",
    "to": "recipient-address",
    "amount": "0.1",
    "dryRun": true
  }'

The dry-run capability lets agents validate transactions against current policies without submitting to the blockchain. This prevents failed transactions and helps agents adapt their behavior to policy constraints.

Self-Hosted Control

Since WAIaaS runs entirely self-hosted, credential security doesn't depend on third-party services. Your session tokens, master passwords, and private keys never leave your infrastructure:

services:
  daemon:
    image: ghcr.io/minhoyoo-iotrust/waiaas:latest
    ports:
      - "127.0.0.1:3100:3100"  # Localhost only by default
    volumes:
      - waiaas-data:/data      # Local encrypted storage
    environment:
      - WAIAAS_DATA_DIR=/data

The Docker deployment binds to localhost by default, preventing external network exposure. All sensitive data stays encrypted in local volumes under your direct control.

Quick Start: Secure Agent Setup

1. Deploy with auto-provisioning:

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

2. Retrieve auto-generated master password:

docker exec waiaas cat /data/recovery.key

3. Create wallet with spending limits:

waiaas quickset --mode testnet  # Creates wallet + policies + session

4. Connect AI agent with session token:

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

5. Test with small transaction to verify policy enforcement before production use.

Understanding these security layers helps you deploy AI agents with confidence, knowing that multiple failsafes protect against both technical vulnerabilities and operational mistakes.

Self-Hosting Wallet Infrastructure: Docker Deployment Guide for AI Agents provides detailed deployment security configurations, while Policy Engine Deep Dive: 4-Tier Security for AI Agent Transactions explores advanced policy patterns for different risk profiles.

What's Next

Start with testnet deployment to experiment with policy configurations before handling real funds. The WAIaaS documentation at https://waiaas.ai covers advanced topics like multi-signature integration and custom policy development. Explore the complete implementation on GitHub at https://github.com/minhoyoo-iotrust/WAIaaS to understand the security architecture in detail.