DEV Community

Cover image for 4-Tier Security Model: From INSTANT to APPROVAL for AI Agent Transactions
Wallet Guy
Wallet Guy

Posted on

4-Tier Security Model: From INSTANT to APPROVAL for AI Agent Transactions

#ai #architecture #security #web3

4-Tier Security Model: How WAIaaS Puts Guardrails on AI Agent Wallets

Giving an AI agent a wallet without guardrails is like giving a toddler a credit card — the agent will enthusiastically do exactly what you told it to do, including the parts you didn't think through. If you're building systems where AI agents hold and move real funds, the security model underneath that wallet isn't an afterthought. It's the entire game.

Why This Problem Is Harder Than It Looks

The naive approach to AI agent wallets goes something like this: generate a private key, give the agent signing authority, and let it rip. That works fine in a sandbox. In production, with real money, it creates a single point of catastrophic failure. One compromised session token, one hallucinated recipient address, one runaway trading loop — and the funds are gone.

The challenge is that you need the agent to operate autonomously most of the time. If every transaction requires manual approval, you've built an expensive UI for yourself, not an autonomous agent. What you actually need is a system that lets small, routine transactions flow through instantly while catching anything unusual before it executes. That's a policy engine problem, and it requires thinking carefully about the threat model: what are the realistic ways this goes wrong?

WAIaaS approaches this with three distinct layers between your agent and your funds, and a default-deny stance that means if you haven't explicitly configured something, it's blocked.

Layer 1: Three Authentication Roles

Before we get to the policy engine, it's worth understanding that WAIaaS separates who can do what at the authentication level. There are three distinct auth roles:

masterAuth (Argon2id) — The system administrator role. Creates wallets, manages sessions, configures policies. This is the password you set once and lock away. AI agents never see it.

sessionAuth (JWT HS256) — What the AI agent actually uses. Scoped to a specific wallet. Time-limited. The agent carries this token and uses it for transactions, balance queries, and DeFi actions.

ownerAuth (SIWS/SIWE — ed25519 or secp256k1 signature) — The fund owner. Used for approving pending transactions, recovery, and the kill switch. This maps to a wallet you control, not a password stored anywhere on the server.

This separation means that even if an attacker gets hold of the agent's session token, they can't create new wallets, modify policies, or approve high-value transactions. The blast radius is bounded.

# masterAuth — system administrator (wallet creation, session management, policies)
-H "X-Master-Password: my-secret-password"

# sessionAuth — AI agent (transactions, balance queries, DeFi actions)
-H "Authorization: Bearer wai_sess_eyJhbGciOiJIUzI1NiJ9..."

# ownerAuth — fund owner (transaction approval, kill switch recovery)
-H "X-Owner-Signature: <ed25519-or-secp256k1-signature>"
-H "X-Owner-Message: <signed-message>"
Enter fullscreen mode Exit fullscreen mode

Sessions also carry per-session TTL, maxRenewals, and absoluteLifetime controls. A session issued to a short-lived agent job can be configured to expire when the job ends.

Layer 2: Default-Deny Policies

This is the part that actually prevents your agent from draining your wallet. WAIaaS enforces a default-deny posture on two critical policy types:

  • ALLOWED_TOKENS — If you haven't explicitly whitelisted a token, the agent cannot transfer it. Your agent can't suddenly start moving tokens you didn't know it could see.
  • CONTRACT_WHITELIST — If a contract address isn't on the list, the agent can't call it. This stops the agent from interacting with arbitrary DeFi protocols you haven't reviewed.

That's not "secure by default" as a marketing claim. It's a hard block at the policy evaluation stage. The transaction pipeline runs a policy check before execution, and a missing whitelist entry returns POLICY_DENIED.

The policy engine supports 21 policy types in total. Beyond the two default-deny types above, you have tools for controlling approved spenders, method selectors, network restrictions, DeFi-specific limits (LTV ratios, leverage caps, position sizes), and more. Here's the full list:

SPENDING_LIMIT          — Amount-based 4-tier security
WHITELIST               — Allowed recipient addresses
TIME_RESTRICTION        — Allowed transaction hours
RATE_LIMIT              — Max transactions per period
ALLOWED_TOKENS          — Token transfer whitelist (default-deny)
CONTRACT_WHITELIST      — Contract call whitelist (default-deny)
METHOD_WHITELIST        — Allowed function selectors
APPROVED_SPENDERS       — Token approval whitelist (default-deny)
APPROVE_AMOUNT_LIMIT    — Max approve amount, block unlimited
APPROVE_TIER_OVERRIDE   — Force tier for APPROVE transactions
ALLOWED_NETWORKS        — Network restriction
X402_ALLOWED_DOMAINS    — x402 payment domain whitelist
LENDING_LTV_LIMIT       — Max loan-to-value ratio for DeFi lending
LENDING_ASSET_WHITELIST — Allowed lending assets
PERP_MAX_LEVERAGE       — Max perpetual futures leverage
PERP_MAX_POSITION_USD   — Max position size in USD
PERP_ALLOWED_MARKETS    — Allowed perpetual markets
REPUTATION_THRESHOLD    — ERC-8004 onchain reputation threshold
ERC8128_ALLOWED_DOMAINS — ERC-8128 HTTP signing domains
VENUE_WHITELIST         — Allowed trading venues
ACTION_CATEGORY_LIMIT   — DeFi action category limits
Enter fullscreen mode Exit fullscreen mode

The DeFi-specific policy types are worth calling out for trading agents in particular. PERP_MAX_LEVERAGE means your perpetuals agent literally cannot open a position above your configured leverage cap, regardless of what the LLM decides is a good idea. LENDING_LTV_LIMIT prevents your lending agent from borrowing against collateral right up to the liquidation threshold.

Layer 3: The 4-Tier Security Model

This is the architecture that lets you have autonomous operation without losing control. Every transaction is assigned to one of four security tiers based on your policy configuration:

INSTANT — Execute immediately, no notification. For small, routine operations that you've decided carry acceptable risk. A $5 transaction to a whitelisted address shouldn't wake you up at 3am.

NOTIFY — Execute immediately, but send a notification. You're informed, but the transaction doesn't wait for you. Useful for mid-range amounts where you want visibility without friction.

DELAY — Queue the transaction for a configured delay period (e.g., 15 minutes), then execute. The window is cancellable. If the agent did something wrong — or if you notice an anomaly — you can stop it before it settles.

APPROVAL — Block until the fund owner explicitly approves. High-value transactions, unusual patterns, anything you've decided requires a human in the loop.

The tier assignment happens automatically based on your SPENDING_LIMIT policy rules. Here's what that configuration looks like:

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": 100,
      "notify_max_usd": 500,
      "delay_max_usd": 2000,
      "delay_seconds": 900,
      "daily_limit_usd": 5000
    }
  }'
Enter fullscreen mode Exit fullscreen mode

With this configuration: transactions under $100 execute immediately. $100-$500 execute immediately with a notification. $500-$2000 are queued for 15 minutes before execution. Anything above $2000 waits for your manual approval. There's also a $5000 daily aggregate limit — if the agent somehow exhausts that in a session, subsequent transactions are blocked for the rest of the day.

The tier logic is straightforward: amount <= instant_max → INSTANT, <= notify_max → NOTIFY, <= delay_max → DELAY, > delay_max → APPROVAL. Every transaction that enters the 7-stage pipeline gets evaluated against this.

Human Approval Channels

When a transaction hits the APPROVAL tier, something needs to reach you. WAIaaS provides three signing channels: a push relay channel, a Telegram channel, and a wallet notification channel. The WalletConnect integration means you can approve transactions directly from your existing wallet app.

Approving a pending transaction via the API looks like this:

curl -X POST http://127.0.0.1:3100/v1/transactions/<tx-id>/approve \
  -H "X-Owner-Signature: <ed25519-or-secp256k1-signature>" \
  -H "X-Owner-Message: <signed-message>"
Enter fullscreen mode Exit fullscreen mode

The ownerAuth signature is what makes this secure. Approval requires a cryptographic signature from the owner's key — not just a password or session token. An attacker with access to the server can't approve their own pending transactions without also controlling your private key.

Simulate Before You Execute

One more tool worth knowing about: the dry-run API. Before any transaction executes for real, you can simulate it to see exactly how it would be evaluated — which tier it would hit, whether it would be denied by policy, what the estimated gas cost looks like.

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
  }'
Enter fullscreen mode Exit fullscreen mode

This is particularly useful when you're configuring policies for the first time. You can test edge cases — what happens when the agent tries to send $150? $2500? — without committing real funds.

Quick Start: Setting Up Security in 5 Steps

Here's the minimal path to running an agent with real guardrails:

Step 1: Install and start the daemon

npm install -g @waiaas/cli
waiaas init
waiaas start
Enter fullscreen mode Exit fullscreen mode

Step 2: Create a wallet

curl -X POST http://127.0.0.1:3100/v1/wallets \
  -H "Content-Type: application/json" \
  -H "X-Master-Password: my-secret-password" \
  -d '{"name": "trading-wallet", "chain": "solana", "environment": "mainnet"}'
Enter fullscreen mode Exit fullscreen mode

Step 3: Set a 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": 100,
      "notify_max_usd": 500,
      "delay_max_usd": 2000,
      "delay_seconds": 900,
      "daily_limit_usd": 5000
    }
  }'
Enter fullscreen mode Exit fullscreen mode

Step 4: Whitelist the tokens your agent should touch

Configure an ALLOWED_TOKENS policy for the specific tokens the agent needs. Anything not on the list stays untouchable.

Step 5: Issue a session token for the agent and connect

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>"}'
Enter fullscreen mode Exit fullscreen mode

Hand that session token to your agent. It's scoped, time-limited, and bounded by every policy you just configured.

What the Error Response Tells You

When a transaction is blocked, the error response is explicit about why:

{
  "error": {
    "code": "POLICY_DENIED",
    "message": "Transaction denied by SPENDING_LIMIT policy",
    "domain": "POLICY",
    "retryable": false
  }
}
Enter fullscreen mode Exit fullscreen mode

retryable: false on a policy denial is intentional — the agent shouldn't retry. It should surface the denial upstream so a human can decide whether the policy needs adjustment or whether the agent's behavior was wrong. Clear error semantics matter for building reliable agent systems.

What's Next

The security model described here is one layer of a larger system — the WAIaaS monorepo also includes MCP integration for connecting agents to Claude and other frameworks, DeFi protocol integrations across 15 providers, and NFT support for EVM and Solana. If you're building an agent that needs to operate in production, the right starting point is the full documentation and the open-source codebase.

Browse the source and open issues on GitHub: https://github.com/minhoyoo-iotrust/WAIaaS

Learn more about the project and deployment options at: https://waiaas.ai

Top comments (0)