Inside the 7-Stage Transaction Pipeline: How AI Agents Validate Before They Execute

Inside the 7-Stage Transaction Pipeline: How AI Agents Validate Before They Execute

The transaction pipeline is the part of your AI agent's wallet stack that stands between "I want to send tokens" and "tokens sent" — and if you're building agents that touch real money, understanding what happens in those stages is the difference between a trustworthy system and a very expensive mistake. WAIaaS implements a 7-stage transaction pipeline that every on-chain action passes through before execution, giving you programmatic control over validation, policy enforcement, and human approval without writing any of that logic yourself.

Why This Actually Matters for Agent Builders

Here's the core problem. AI agents are getting genuinely capable. Claude can browse the web, write code, call APIs, and reason across long context windows. CrewAI agents can coordinate complex workflows. LangChain pipelines can chain dozens of tool calls. But the moment any of these agents need to do something with money — swap a token, pay for an API, stake assets — you're suddenly operating without a safety net.

You could bolt on some ad-hoc validation logic. Check the amount before sending. Whitelist a few addresses. But you'd be reinventing a security problem that has real consequences when you get it wrong. A misconfigured AI agent with unchecked financial access is a bug that costs money, not just credibility.

What you actually want is a structured pipeline: every transaction goes through the same sequence of checks, every time, before a single signature is produced. That's what WAIaaS ships out of the box.

The 7 Stages, Explained

WAIaaS runs every transaction through 7 pipeline stages in order. Each stage can halt the transaction entirely — the next stage only runs if the previous one passes.

stage1-validate → stage2-auth → stage3-policy → stage4-wait → stage5-execute → stage6-confirm → stages

Here's what each stage is actually doing:

Stage 1 — Validate: The transaction request is parsed and validated against one of 7 supported transaction types: Transfer, TokenTransfer, ContractCall, Approve, Batch, NftTransfer, or ContractDeploy. Malformed requests die here before anything else happens.

Stage 2 — Auth: The session token is verified. WAIaaS uses three authentication layers: masterAuth (Argon2id) for system administration, sessionAuth (JWT HS256) for AI agents, and ownerAuth (SIWS/SIWE signatures) for fund owners. An agent's session token is checked at this stage — expired tokens, revoked sessions, or tokens scoped to a different wallet all fail here.

Stage 3 — Policy: This is where the 21-policy engine runs. Every active policy on the wallet is evaluated against the transaction. A SPENDING_LIMIT policy assigns the transaction to one of 4 security tiers (INSTANT, NOTIFY, DELAY, APPROVAL) based on USD value. CONTRACT_WHITELIST blocks calls to non-whitelisted contracts. ALLOWED_TOKENS enforces a token transfer whitelist. If any policy blocks the transaction, you get back a structured error — not a crash.

Stage 4 — Wait: If the policy engine assigned the transaction to the DELAY tier, it sits in queue here for the configured delay_seconds. During this window the transaction is cancellable. If it was assigned to APPROVAL, it waits for a human signature via WalletConnect, Telegram, or the push relay signing channel.

Stage 5 — Execute: The transaction gets signed and submitted to the network. This stage only runs if stages 1-4 all passed.

Stage 6 — Confirm: On-chain confirmation is tracked. The transaction status moves from PENDING to COMPLETED (or FAILED).

Understanding this pipeline changes how you design your agents. Instead of writing defensive code around every sendToken call, you configure the pipeline once and let it run.

Setting Up the Policy Layer

Before your agent sends a single transaction, you want policies in place. Here's the most important one to configure first — SPENDING_LIMIT:

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
    }
  }'

What this configures: any transaction under $100 executes immediately. Between $100-$500, it executes but you get notified. Between $500-$2000, it waits 15 minutes (900 seconds) before executing — long enough for you to cancel it. Over $2000, it requires your explicit approval via your wallet connection.

The tier assignment happens automatically in Stage 3. Your agent code doesn't need to know anything about this — it just calls sendToken and the pipeline handles the rest.

The policy engine uses default-deny for the most security-critical policies. If you haven't configured ALLOWED_TOKENS, token transfers are blocked. If you haven't configured CONTRACT_WHITELIST, contract calls are blocked. This means a misconfigured agent that tries to interact with an unexpected contract will fail safely rather than silently succeed.

What the Agent Side Looks Like

Here's a minimal TypeScript agent that sends tokens and handles the pipeline's response correctly:

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

const client = new WAIaaSClient({
  baseUrl: process.env['WAIAAS_BASE_URL'] ?? 'http://localhost:3100',
  sessionToken: process.env['WAIAAS_SESSION_TOKEN'],
});

// Step 1: Check wallet balance
const balance = await client.getBalance();
console.log(`Balance: ${balance.balance} ${balance.symbol} (${balance.chain}/${balance.network})`);

// Step 2: Send tokens — pipeline handles validation, policy, and execution
const sendResult = await client.sendToken({
  type: 'TRANSFER',
  to: 'recipient-address',
  amount: '0.001',
});
console.log(`Transaction submitted: ${sendResult.id} (status: ${sendResult.status})`);

// Step 3: Poll for confirmation — the pipeline moves status through stages
const POLL_TIMEOUT_MS = 60_000;
const startTime = Date.now();
while (Date.now() - startTime < POLL_TIMEOUT_MS) {
  const tx = await client.getTransaction(sendResult.id);
  if (tx.status === 'COMPLETED') {
    console.log(`Transaction confirmed! Hash: ${tx.txHash}`);
    break;
  }
  if (tx.status === 'FAILED') {
    console.error(`Transaction failed: ${tx.error}`);
    break;
  }
  await new Promise(resolve => setTimeout(resolve, 1000));
}

Notice what the agent doesn't have to do: validate the transaction format, check its own permissions, enforce spending limits, or manage confirmation polling logic beyond a simple status check. The 7-stage pipeline handles stages 1-6. The SDK gives you COMPLETED, FAILED, or a status that means "still working through the pipeline."

The error handling is worth looking at too:

try {
  const tx = await client.sendToken({ to: '...', amount: '1.0' });
} catch (error) {
  if (error instanceof WAIaaSError) {
    console.error(`API Error: [${error.code}] ${error.message}`);
    // error.code examples: INSUFFICIENT_BALANCE, POLICY_DENIED, TOKEN_EXPIRED
  }
}

A POLICY_DENIED error means Stage 3 stopped the transaction — your spending limit, token whitelist, or contract whitelist blocked it. This is structured data your agent can reason about. A TOKEN_EXPIRED means Stage 2 failed — the session needs renewal. Your agent can handle these programmatically without any crypto-specific knowledge.

Simulating Before You Execute

One of the more useful pipeline features for agent builders is dry-run mode. Before executing any real transaction, your agent can simulate it through the full pipeline to see what would happen:

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 runs stages 1-3 — validation, auth, and policy — without touching Stage 5 (execute). If a policy would block the transaction, you find out now rather than after the agent has committed to the action. This is particularly useful in agentic workflows where you want the agent to check feasibility before reporting back to the user that it's about to do something.

Connecting via MCP: The Fastest Path

If you're building with Claude specifically, the fastest way to expose the full pipeline to your agent is through the MCP integration. WAIaaS ships 45 MCP tools, including simulate-transaction, send-token, get-policies, and the full DeFi action set.

Setup is one command:

waiaas mcp setup --all    # Auto-register all wallets with Claude Desktop

This writes the configuration your Claude Desktop needs. The full config looks like this if you want to set it up manually:

{
  "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>",
        "WAIAAS_DATA_DIR": "~/.waiaas"
      }
    }
  }
}

Once connected, Claude can call simulate_transaction before executing, check get_policies to understand what's allowed, and call send_token knowing the pipeline will enforce all the rules you've configured. The agent doesn't need to know the policy configuration — it just hits the pipeline and gets back a result.

Quick Start: Pipeline in 5 Steps

Here's the minimal path from zero to a working pipeline:

Step 1 — Install and initialize

npm install -g @waiaas/cli
waiaas init
waiaas start

Step 2 — Create a wallet and session

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"}'

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>"}'

Step 3 — Configure a spending policy

Use the SPENDING_LIMIT example from earlier. At minimum, set instant_max_usd to an amount you're comfortable with your agent spending without notification.

Step 4 — Simulate a transaction

Before running your agent against mainnet, use dryRun: true to verify the pipeline accepts the transaction type and amount your agent will produce.

Step 5 — Connect your agent

For Claude: waiaas mcp setup --all. For TypeScript agents: npm install @waiaas/sdk and use the examples above. For Python agents: pip install waiaas.

Approving Transactions That Need Human Sign-Off

When Stage 4 holds a transaction for APPROVAL, you need to sign off as the wallet owner. WAIaaS supports WalletConnect for this, plus Telegram and push relay signing channels. The API call for owner approval 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>"

The three-tier auth model (masterAuth, sessionAuth, ownerAuth) means your agent never has access to the owner's signing credentials. The agent uses its session token. You as the owner use your wallet signature. The master password manages system configuration. These are intentionally separated so a compromised agent session can't bypass the approval stage.

What You've Actually Built

When you wire up WAIaaS to your AI agent, you're not just giving it a wallet. You're giving it a wallet with a structured safety system that runs on every transaction. The agent can propose any action it wants — the pipeline decides whether that action is allowed, at what tier, and whether a human needs to sign off.

For agent builders, this is the right abstraction. Your LangChain chain, your CrewAI crew, your Claude MCP setup — none of them need to contain financial policy logic. That logic lives in the pipeline, configured once, enforced consistently.

What's Next

The WAIaaS GitHub repository has the full codebase including the pipeline stage implementations, all 21 policy type schemas, and the SDK packages. The interactive API reference at http://localhost:3100/reference (after you start the daemon) documents all 39 REST API route modules with live examples. If you want to go deeper on any specific pipeline stage or policy type, https://waiaas.ai has the full documentation.