DEV Community: Wallet Guy

Self-Documenting AI Agents: OpenAPI 3.0 Spec Generation for MCP Tools

Wallet Guy — Wed, 24 Jun 2026 15:37:47 +0000

Self-Documenting AI Agents: OpenAPI 3.0 Spec Generation for MCP Tools

MCP developers building onchain AI agents often hit the same wall: your Claude agent can reason brilliantly, but it has no idea what tools are actually available, what parameters they expect, or how to authenticate. WAIaaS solves this by combining 45 MCP tools with a live OpenAPI 3.0 spec — so your agent always has accurate, machine-readable documentation for every wallet, transaction, and DeFi action it can take.

Why This Actually Matters

When you wire an AI agent to onchain infrastructure, documentation isn't a nice-to-have — it's load-bearing. If your agent guesses at parameter names, misunderstands authentication requirements, or doesn't know which networks are supported, it makes mistakes with real money. The combination of MCP tooling and a live OpenAPI spec means two things: Claude gets structured tool definitions through the MCP protocol, and any HTTP client (including other agents, scripts, or dashboards you build) can discover the full API surface automatically. Both layers stay in sync because they're generated from the same codebase.

One Line in Your Config

Let's start with the fastest path. Add this to your claude_desktop_config.json:

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

That's it. Restart Claude Desktop and your agent now has access to 45 MCP tools covering wallet management, token transfers, DeFi actions, NFT operations, and x402 HTTP payment — all authenticated, all policy-governed, all with typed parameters that Claude can introspect before calling them.

The MCP server package is @waiaas/mcp on npm, transport is stdio, and tools are served with full schema definitions so Claude understands input shapes without guessing.

What the 45 Tools Actually Cover

The tool list isn't just send-token and check-balance. Here's the full scope across categories:

Wallet & balance: get-wallet-info, get-address, get-balance, get-assets, get-nonce, connect-info

Transactions: send-token, send-batch, sign-transaction, sign-message, simulate-transaction, get-transaction, list-transactions, list-incoming-transactions, get-incoming-summary

DeFi: action-provider, get-defi-positions, get-health-factor, approve-token, list-offchain-actions

Account Abstraction: build-userop, sign-userop, encode-calldata, call-contract

NFT: get-nft-metadata, list-nfts, transfer-nft

Protocols: hyperliquid, polymarket, resolve-asset, get-tokens, get-provider-status

Sessions & auth: list-sessions, list-credentials, get-policies

ERC standards: erc8004-get-agent-info, erc8004-get-reputation, erc8004-get-validation-status, erc8128-sign-request, erc8128-verify-signature

WalletConnect: wc-connect, wc-disconnect, wc-status

Utility: get-rpc-proxy-url, x402-fetch, get-transaction (with full hash resolution)

When Claude sees simulate-transaction in the tool list, it knows it can dry-run before executing. When it sees get-health-factor, it understands DeFi lending positions are trackable. The schema-first design means Claude reasons about what's possible before committing to an action.

The OpenAPI Layer: For Everything Else

The MCP interface handles Claude. But you probably also have scripts, dashboards, or other agents that talk to WAIaaS over HTTP. That's where the OpenAPI 3.0 spec comes in.

WAIaaS auto-generates a live OpenAPI spec at /doc and serves an interactive Scalar API reference at /reference. Both stay current with the actual implementation — 39 REST API route modules feeding a single spec.

# Download the OpenAPI 3.0 spec
curl http://127.0.0.1:3100/doc -o openapi.json

# View the interactive reference in your browser
open http://127.0.0.1:3100/reference

The interactive UI at /reference is useful during development: you can see every endpoint, its authentication requirement, request schema, and response shape without reading source code. When you're building a policy configuration or debugging a DeFi action response, this is significantly faster than grepping through documentation.

The spec is also what you'd feed to another agent or code generator. If you're building a second AI agent that orchestrates WAIaaS over REST rather than MCP, point it at /doc and it has a complete, accurate description of the API surface.

Authentication Is Part of the Schema

One thing that trips up developers building multi-agent systems: WAIaaS uses three distinct authentication methods, and the OpenAPI spec documents which endpoints require which.

# masterAuth — create wallets, manage sessions, set policies
-H "X-Master-Password: my-secret-password"

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

# ownerAuth — human approval for high-value transactions
-H "X-Owner-Signature: <ed25519-or-secp256k1-signature>"
-H "X-Owner-Message: <signed-message>"

In the MCP context, the session token you put in WAIAAS_SESSION_TOKEN handles all agent-facing operations. The session was created by a human operator using masterAuth — the agent never sees the master password. This separation is intentional: the agent has a scoped credential with policy limits, not root access to the wallet system.

Setting Up a Multi-Wallet MCP Configuration

For more sophisticated setups — say, a trading agent and a separate Solana wallet agent — you can run multiple named MCP servers pointing at the same WAIaaS daemon:

{
  "mcpServers": {
    "waiaas-trading": {
      "command": "npx",
      "args": ["-y", "@waiaas/mcp"],
      "env": {
        "WAIAAS_BASE_URL": "http://127.0.0.1:3100",
        "WAIAAS_AGENT_ID": "019c47d6-51ef-7f43-a76b-d50e875d95f4",
        "WAIAAS_AGENT_NAME": "trading-agent",
        "WAIAAS_DATA_DIR": "~/.waiaas"
      }
    },
    "waiaas-solana": {
      "command": "npx",
      "args": ["-y", "@waiaas/mcp"],
      "env": {
        "WAIAAS_BASE_URL": "http://127.0.0.1:3100",
        "WAIAAS_AGENT_ID": "019c4cd2-86e8-758f-a61e-9c560307c788",
        "WAIAAS_AGENT_NAME": "solana-wallet",
        "WAIAAS_DATA_DIR": "~/.waiaas"
      }
    }
  }
}

Each MCP server instance has its own session token scoped to a specific wallet. Claude sees both as separate tool namespaces and can reason about which wallet to use for which operation — all documented through the MCP tool schemas.

What Claude Can Actually Do After This

Here's what the interaction looks like in practice once MCP is connected:

User: "Check my wallet balance"
→ Claude calls get_balance tool → returns balance

User: "Swap 0.1 SOL for USDC on Jupiter"
→ Claude calls execute_action tool with jupiter-swap provider

User: "Show my DeFi positions across all protocols"
→ Claude calls get_defi_positions tool → returns lending/staking positions

The Jupiter swap call hits one of 15 integrated DeFi protocol providers — including Aave v3, Across, Drift, Hyperliquid, Jito staking, Jupiter swap, Kamino, Lido staking, LI.FI, Pendle, Polymarket, XRPL DEX, and 0x swap, among others. Claude doesn't need to know the protocol-specific parameters because the tool schema defines them.

Before any transaction executes, the 7-stage pipeline processes it: validate → auth → policy → wait → execute → confirm. If a policy blocks it, Claude gets back a structured error:

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

That error code is something Claude can reason about — it knows the transaction was blocked by a spending limit, not a network error, and can explain that to the user or suggest alternatives.

Quick Start: From Zero to MCP Tools in 5 Steps

Step 1: Install the CLI and initialize

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

Step 2: Create wallets and sessions in one command

waiaas quickset --mode mainnet

This creates wallets and MCP sessions. The output includes the MCP config JSON.

Step 3: Register with Claude Desktop automatically

waiaas mcp setup --all

Step 4: Verify the OpenAPI spec is live

curl http://127.0.0.1:3100/doc -o openapi.json
# Then open http://127.0.0.1:3100/reference in your browser

Step 5: Set a spending policy so the agent has safe limits

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

Restart Claude Desktop and ask it to check your balance.

The Self-Documenting Part

The reason this system is "self-documenting" isn't marketing language — it's a practical property. The 45 MCP tools and the 39 REST API route modules both derive their schemas from the same source. When WAIaaS adds a new capability, the OpenAPI spec at /doc updates automatically, the interactive reference at /reference reflects it, and the MCP tool definitions that Claude receives are current.

For developers building on top of WAIaaS — whether you're writing an agent orchestration layer, a monitoring dashboard, or a second AI system that talks to WAIaaS over HTTP — you always have an accurate map of the territory. You don't maintain separate documentation, you don't discover parameter mismatches at runtime, and you don't need to read source code to understand what's available.

That's the core value proposition for MCP developers specifically: you get 45 typed, schema-defined tools that Claude can introspect, plus a live HTTP API that any other client can discover — all from a single self-hosted daemon you control.

What's Next

If you want to explore the policy engine in depth — setting spending limits, token whitelists, and DeFi-specific controls like maximum leverage — the 21 policy types give you fine-grained control over what your agent can and can't do autonomously. The Docker deployment path is also worth looking at if you're running this in a persistent server environment rather than locally.

The full codebase, including the MCP package and all 15 DeFi protocol providers, is at https://github.com/minhoyoo-iotrust/WAIaaS. More documentation and the official site are at https://waiaas.ai.

Building the Financial Rails for Machine-to-Machine Commerce

Wallet Guy — Wed, 24 Jun 2026 09:53:56 +0000

Building the Financial Rails for Machine-to-Machine Commerce

AI agents will need to pay for compute, data, and API calls — and right now, almost nothing in the infrastructure stack is built to handle that. We talk endlessly about autonomous agents that book travel, execute trades, and negotiate contracts, but when the conversation turns to how they pay, the answer is usually a hand-wave. Humans still hold the keys, approve every transaction, and act as financial intermediaries for systems that are supposed to operate independently. That's not autonomy. That's a chatbot with extra steps.

The Missing Layer

Think about what a truly autonomous AI agent needs to participate in economic activity. It needs to hold funds. It needs to authorize payments without waking a human up at 3 AM. It needs spending guardrails so it can't accidentally drain a treasury on a bad swap. It needs to handle multiple chains because the internet doesn't run on one blockchain. And it needs to do all of this without a centralized custodian that becomes a single point of failure — or control.

None of the standard wallet tooling was designed for this. Browser extension wallets need a human to click "confirm." Custodial APIs introduce a trust assumption that defeats the purpose of autonomous operation. Raw key management libraries give you signing primitives but nothing resembling a policy engine or an approval workflow.

The financial rails for machine-to-machine commerce aren't missing because the problem is unsolved. They're missing because the industry has been building for human users. Agents are a different actor class entirely, and they need infrastructure built specifically for them.

What Agent-Native Wallet Infrastructure Looks Like

WAIaaS — Wallet-as-a-Service for AI agents — is an open-source, self-hosted daemon that exists specifically to close this gap. It's running today. You can deploy it in under five minutes with Docker. Here's what makes it different from gluing together a keystore and a REST API yourself.

The Architecture: Three Auth Layers for Three Actor Classes

The fundamental insight in WAIaaS's design is that who is touching the wallet matters enormously. There are three distinct actors with three distinct trust levels:

The system administrator sets up wallets, creates sessions, and defines policies. They authenticate with a master password hashed using Argon2id. They should almost never be involved in day-to-day operations.

The AI agent runs transactions, checks balances, executes DeFi actions. It authenticates with a session JWT (wai_sess_...). Sessions have configurable TTL, max renewals, and absolute lifetime. The agent gets exactly the access you scope to it — no more.

The fund owner — the human who actually owns the money — can approve transactions, connect via WalletConnect, and activate a kill switch if something goes wrong. They authenticate with a cryptographic signature (SIWS or SIWE), not a password.

This isn't three passwords for the same interface. It's three genuinely different security principals with different capabilities and different threat models.

The Policy Engine: Rules That Run Without Human Intervention

The reason you can let an agent operate autonomously is that you've already told the system what it's allowed to do. WAIaaS ships a policy engine with 21 policy types and 4 security tiers: INSTANT, NOTIFY, DELAY, and APPROVAL.

The tiers work like this: small transactions execute immediately. Medium transactions execute and notify you. Large transactions queue for a time delay (during which you can cancel). Very large transactions require explicit human approval. You define the dollar thresholds.

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

With this policy in place, an agent paying a $12 API bill executes immediately. An agent trying to move $3,000 in one shot waits 15 minutes and you get a notification. An agent trying to do something truly unusual hits an approval gate.

The default is deny. If you haven't configured ALLOWED_TOKENS or CONTRACT_WHITELIST, transactions are blocked. This is the right default for autonomous systems. You opt into access; you don't opt out of it.

Beyond spending limits, the full policy set covers: token whitelists, contract whitelists, rate limits, time restrictions, allowed networks, approved spenders, approval amount limits, DeFi-specific controls like LTV limits and max perpetual leverage, and even ERC-8004 onchain reputation thresholds. The policy engine isn't an afterthought — it's the thing that makes autonomous operation safe enough to actually deploy.

x402: The Payment Protocol Agents Were Waiting For

The most interesting capability for machine-to-machine commerce specifically is x402 HTTP payment protocol support. x402 extends HTTP with a 402 Payment Required status — when an API returns a 402, the client automatically pays and retries. No human interaction. No pre-negotiated API keys. Just an agent that pays for what it uses.

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

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

// This fetch automatically handles 402 Payment Required responses
const response = await client.x402Fetch('https://api.example.com/premium-data');

From the agent's perspective, it's just an HTTP call. The wallet handles the 402 negotiation transparently. This is what actual machine-to-machine micropayments look like in practice — not a whitepaper concept, but a working implementation you can wire into an agent loop today.

You can lock down which domains an agent is allowed to pay automatically using the X402_ALLOWED_DOMAINS policy, so an agent can't be tricked into paying arbitrary endpoints.

7-Stage Transaction Pipeline

Every transaction — whether it's a simple token transfer, a DeFi action, or an NFT transfer — runs through a 7-stage pipeline: validate, auth, policy, wait, execute, confirm. The "wait" stage is where time-delay policies live. The "policy" stage is where spending limits and whitelists fire. The architecture means every transaction goes through the same safety checks regardless of how it was initiated.

There's also a dry-run mode for simulating transactions before execution:

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

A well-built agent doesn't fire transactions blindly. It simulates first, checks the result, then executes. The infrastructure needs to support that workflow, and WAIaaS does.

Multi-Chain From Day One

Agent commerce doesn't happen on one chain. WAIaaS supports 2 chain types (EVM and Solana) across 18 networks. The same session token works whether the agent is moving USDC on Ethereum, swapping on Jupiter, or staking SOL via Jito. The wallet abstraction handles chain-specific details — nonces, fee structures, address formats — so agent code stays clean.

15 DeFi protocol providers are integrated out of the box: Aave v3, Across, D'CENT Swap, Drift, ERC-8004, Hyperliquid, Jito Staking, Jupiter Swap, Kamino, Lido Staking, LI.FI, Pendle, Polymarket, XRPL DEX, and 0x Swap. An agent that needs to rebalance a portfolio, bridge funds cross-chain, enter a yield position, or trade perpetuals can do all of it through the same interface, subject to the same policy engine.

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

MCP Integration: Agents That Think and Spend

If you're building on the Model Context Protocol — connecting Claude, GPT-4, or another LLM to tools via MCP — WAIaaS ships 45 MCP tools covering wallet operations, transactions, DeFi positions, NFTs, and x402 payments. Setup is one command:

waiaas mcp setup --all

After that, the AI model can check balances, execute swaps, monitor incoming transactions, and pay for API calls as naturally as it calls any other tool. The MCP layer doesn't bypass the policy engine — every tool call still runs through the same 7-stage pipeline. The agent gets capability; you keep control.

Getting It Running

The fastest path from zero to a working agent wallet:

Step 1: Deploy with Docker

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

The Docker image is ghcr.io/minhoyoo-iotrust/waiaas:latest, binding to 127.0.0.1:3100 by default. For production, use the secrets overlay (docker-compose.secrets.yml) to inject credentials via Docker Secrets rather than environment variables.

Step 2: Create a wallet and session

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

# Create agent session
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: Set spending policies before funding

Configure at minimum a SPENDING_LIMIT and ALLOWED_TOKENS policy before you put real funds in. Default-deny means nothing moves without explicit permission.

Step 4: Wire the session token into your agent

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

const client = new WAIaaSClient({
  baseUrl: process.env.WAIAAS_BASE_URL,
  sessionToken: process.env.WAIAAS_SESSION_TOKEN,
});

const balance = await client.getBalance();

Or use the CLI shortcut that handles steps 2-4 in one shot:

waiaas quickset --mode mainnet

Step 5: Connect the interactive API docs

open http://127.0.0.1:3100/reference

The OpenAPI 3.0 spec is auto-generated from the codebase and served at /doc. The interactive Scalar UI at /reference lets you explore all 39 REST API route modules and test calls directly — useful when you're building out agent logic and want to see exactly what each endpoint returns.

What This Means for the Agent Economy

The question of how AI agents pay for things isn't theoretical anymore. The x402 protocol gives APIs a standard way to charge programmatic clients. ERC-4337 Account Abstraction makes gasless transactions and smart account logic practical. ERC-8004 provides a framework for onchain agent reputation. The pieces are assembling.

What's been missing is the infrastructure layer that connects agent logic to these payment primitives with appropriate security controls in between. An agent that can spend without guardrails is a liability. An agent that requires human approval for every transaction isn't autonomous. The right answer is a programmable policy engine that enforces rules at the infrastructure level — so that when the agent acts within its mandate, it acts freely, and when it tries to exceed that mandate, the system stops it.

That's what WAIaaS is built to provide. Not a vision of future infrastructure, but running code you can deploy today.

What's Next

The GitHub repository has the full source, Docker setup, and SDK documentation. The official site covers architecture and integration guides. If you're building agents that need economic agency — the ability to pay for APIs, execute trades, manage positions, or participate in on-chain protocols — the financial rails are ready when you are.

From Symbol to Contract: Asset Resolution APIs for Multi-Chain Trading Bots

Wallet Guy — Tue, 23 Jun 2026 16:06:14 +0000

From Symbol to Contract: Asset Resolution APIs for Multi-Chain Trading Bots

Your trading bot spotted the arbitrage window — SOL/USDC spread across Jupiter and a CEX, closing in seconds. The alpha is there. But before a single swap executes, your bot needs to resolve token addresses, verify it has the right session token, check gas conditions, and route the transaction through policy controls that won't silently reject a $500 move. Most of that infrastructure doesn't exist in your codebase yet. That's the problem this post solves.

Why Infrastructure Debt Kills Good Strategies

Algorithmic trading bots fail in two ways: bad strategy and bad plumbing. Bad strategy is hard to fix. Bad plumbing is just engineering work you haven't done yet.

The plumbing problem for multi-chain bots is specific: you're operating across Solana and EVM chains simultaneously, hitting 15+ DeFi protocols, managing gas costs, and maintaining risk controls that prevent your bot from blowing up a wallet on a bad trade. If you bolt all of that together yourself — custom signing logic, manual address lookups, ad hoc rate limiting, hand-rolled session management — you'll spend more time maintaining infrastructure than improving your edge. WAIaaS is a self-hosted Wallet-as-a-Service that provides that infrastructure as a local API, so you can focus on the strategy layer.

The Asset Resolution Problem

Multi-chain trading bots constantly need to answer a deceptively annoying question: what is the contract address for this token on this chain?

Hardcoding token addresses is fragile. Token lists go stale. New tokens get listed. Wrapped versions differ across chains. And when you're working across Solana (where tokens are identified by mint addresses like So11111111111111111111111111111111111111112) and EVM chains (where they're checksummed hex addresses), your address management code gets messy fast.

WAIaaS exposes a resolve-asset MCP tool and token resolution via the REST API that handles this lookup layer for you. But more importantly, it normalizes the entire execution path — from asset resolution through policy check through on-chain execution — so your bot doesn't have to think about chain-specific quirks at each step.

What WAIaaS Gives a Trading Bot

WAIaaS runs locally (default: 127.0.0.1:3100) and exposes a REST API with 39 route modules. For a trading bot, the relevant surface area is:

Wallet management — create isolated wallets per strategy, per chain
Session tokens — scoped credentials for bot processes
Transaction execution — 7 transaction types including Batch for atomic multi-step trades
15 DeFi protocol integrations — Jupiter, Drift, Hyperliquid, Aave v3, LI.FI, Across, and more
Gas conditional execution — transactions only fire when gas price meets your threshold
Policy engine — 21 policy types with 4 security tiers to bound your bot's risk
Dry-run simulation — test a trade path before committing gas

Let's walk through how a real trading bot interacts with each layer.

Step 1: Create an Isolated Wallet Per Strategy

Good bot architecture isolates capital per strategy. A Solana arb bot shouldn't share a wallet with your Drift perpetuals position manager. Create a wallet for each:

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

Then create a session token scoped to that wallet — this is what your bot process uses at runtime:

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

The session token (wai_sess_...) is all your bot needs for transaction execution. The master password stays out of the hot path entirely.

Step 2: Check Balances Before You Trade

Before your bot enters a position, it needs to know what it's working with. The balance check is a single authenticated call:

curl http://127.0.0.1:3100/v1/wallet/balance \
  -H "Authorization: Bearer wai_sess_eyJhbGciOiJIUzI1NiJ9..."

In the TypeScript SDK, the same call looks like:

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(`${balance.balance} ${balance.symbol} (${balance.chain}/${balance.network})`);

Use getAssets() if you need the full picture — all token balances across the wallet, not just the native token. That's your pre-flight check before sizing a position.

Step 3: Execute a Swap via Jupiter

Once your bot resolves that the Jupiter SOL/USDC spread is worth hitting, execution is a single API call:

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

Notice the token addresses here — So111...112 is the native SOL mint, EPjFW...t1v is USDC on Solana. WAIaaS handles the Jupiter routing, quote fetching, and transaction construction. Your bot just specifies the economic intent.

The same pattern works across all 15 integrated DeFi protocols. For Hyperliquid perpetuals, for Drift, for Aave v3 on EVM — the action provider pattern is consistent. Your bot doesn't need protocol-specific SDKs; it needs one authenticated HTTP client.

Step 4: Simulate Before You Execute

Sending a transaction without knowing if it'll succeed is expensive. WAIaaS has a dry-run mode that simulates the full transaction pipeline — including policy checks — without touching the chain:

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

For a trading bot, this is valuable before executing large positions or testing a new strategy path. If a policy would block the trade, you find out before paying gas. If your balance is insufficient, you find out before the swap fails on-chain.

Step 5: Build Risk Controls with the Policy Engine

This is where WAIaaS earns its place in a serious trading setup. Bots go wrong. A bug in your sizing logic can drain a wallet. A policy engine that's always running gives you a hard floor on how badly things can go.

The policy engine has 21 policy types and 4 security tiers. For a trading bot, the relevant ones are:

SPENDING_LIMIT — the primary guardrail. Define how much your bot can move instantly, how much triggers a notification, how much requires a delay, and how much requires your explicit approval:

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

With this policy: trades under $100 execute immediately. Trades $100–$500 execute and notify you. Trades $500–$2000 wait 15 minutes (cancellable). Anything above $2000 requires manual approval. A runaway position-sizing bug can't drain more than $5000 in a day.

ALLOWED_TOKENS — default-deny whitelist. If your bot should only ever touch SOL and USDC, configure exactly that. Any attempt to approve or transfer an unknown token gets blocked at the policy layer, before signing.

CONTRACT_WHITELIST — only allows calls to contracts you've explicitly approved. If your bot is a Jupiter-only strategy, it should only be able to call the Jupiter router contract. Full stop.

PERP_MAX_LEVERAGE and PERP_MAX_POSITION_USD — for bots running on Hyperliquid or Drift, these policies enforce position sizing limits at the infrastructure layer, independent of your strategy code.

The critical detail: WAIaaS uses default-deny enforcement. A transaction is blocked unless it's explicitly permitted. You're not writing code that says "block this" — you're writing code that says "allow this, and deny everything else."

Step 6: Handle Policy Denials Gracefully

When a policy blocks a trade, your bot gets a structured error response:

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

The retryable field matters for bot logic. A POLICY_DENIED with retryable: false means you need human intervention — don't hammer the endpoint in a retry loop. A different error class might be retryable. Build your bot's error handling around these structured codes, not string matching on error messages.

In TypeScript:

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

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

Step 7: Multi-Step Execution with Batch Transactions

Real trading strategies often involve more than one step. Approve a token, then deposit into a lending protocol. Swap on Jupiter, then stake the output. WAIaaS supports a Batch transaction type as one of its 7 transaction types, letting you compose atomic multi-step operations into a single transaction submission.

This matters for MEV protection: if your strategy requires two actions, bundling them prevents another actor from sandwiching the intermediate state.

Connecting to Claude or an LLM Orchestrator via MCP

If your trading bot is LLM-orchestrated — using Claude or another model to interpret market signals and decide on trades — WAIaaS has a 45-tool MCP server that gives the model direct access to wallet operations without you building a custom tool layer.

Setup is a single command:

waiaas mcp setup --all

That auto-registers all your wallets with Claude Desktop. The MCP server exposes tools including get_balance, send_token, get_defi_positions, simulate_transaction, hyperliquid, polymarket, and get_assets — the full trading surface area, all authenticated and policy-gated.

For a multi-strategy setup where different LLM agents manage different wallets, you can run one MCP server per wallet:

{
  "mcpServers": {
    "waiaas-trading": {
      "command": "npx",
      "args": ["-y", "@waiaas/mcp"],
      "env": {
        "WAIAAS_BASE_URL": "http://127.0.0.1:3100",
        "WAIAAS_AGENT_ID": "019c47d6-51ef-7f43-a76b-d50e875d95f4",
        "WAIAAS_AGENT_NAME": "trading-agent",
        "WAIAAS_DATA_DIR": "~/.waiaas"
      }
    },
    "waiaas-solana": {
      "command": "npx",
      "args": ["-y", "@waiaas/mcp"],
      "env": {
        "WAIAAS_BASE_URL": "http://127.0.0.1:3100",
        "WAIAAS_AGENT_ID": "019c4cd2-86e8-758f-a61e-9c560307c788",
        "WAIAAS_AGENT_NAME": "solana-wallet",
        "WAIAAS_DATA_DIR": "~/.waiaas"
      }
    }
  }
}

Each agent gets its own session scope, its own policies, its own position limits. They can't interfere with each other's capital.

Quick Start: Bot Infrastructure in 5 Minutes

# 1. Install the CLI
npm install -g @waiaas/cli

# 2. Initialize and start the daemon
waiaas init
waiaas start

# 3. Create wallets and sessions in one command
waiaas quickset --mode mainnet

# 4. Connect your bot using the session token printed by quickset
# Set WAIAAS_SESSION_TOKEN in your bot's environment

# 5. (Optional) Register with Claude Desktop
waiaas mcp setup --all

For production deployments, Docker is the better path:

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

The daemon runs on 127.0.0.1:3100 by default — local-only by design. Your API keys and session tokens never leave the host.

The OpenAPI Spec Is Your Friend

WAIaaS auto-generates an OpenAPI 3.0 spec and serves an interactive API reference:

# Download the spec for your bot's HTTP client generation
curl http://127.0.0.1:3100/doc -o openapi.json

# Browse the interactive reference
open http://127.0.0.1:3100/reference

If you're generating a typed HTTP client for your bot (which you should be), point your generator at /doc and get a fully typed interface to all 39 API route modules.

What's Next

WAIaaS is open-source and self-hosted — your keys stay on your infrastructure, your trades stay private, and you're not dependent on a third-party service staying online when your bot needs to execute. The full codebase, including the 15 DeFi protocol integrations and policy engine, is on GitHub.

Star the repo and read the full documentation to go deeper on policy configuration, account abstraction with ERC-4337, and the incoming transaction monitoring that lets your bot react to deposits in real time.

GitHub: https://github.com/minhoyoo-iotrust/WAIaaS
Official site: https://waiaas.ai

Nonce Collision Prevention: Managing Transaction Order Across 18 Networks for AI Agents

Wallet Guy — Tue, 23 Jun 2026 10:07:45 +0000

Nonce Collision Prevention: How WAIaaS Manages Transaction Order for AI Agents Across 18 Networks

Nonce collision is one of the most frustrating problems you'll hit when building AI agents that send blockchain transactions — and it gets worse the moment your agent tries to operate across multiple networks simultaneously. If your agent fires two transactions at once (which AI agents absolutely will do), and both grab the same nonce, one of them silently fails. No error thrown. No retry. Just a lost transaction and a confused agent.

This post walks through why nonce management is uniquely hard for AI agents, how WAIaaS handles it through its 7-stage transaction pipeline, and how you can get an agent submitting safe, ordered transactions across 18 networks in about 10 minutes.

Why Nonce Collisions Are an AI Agent Problem, Not Just a Blockchain Problem

Human wallets rarely hit nonce collisions. A person clicks "send," waits for confirmation, then sends again. Sequential by nature.

AI agents don't work that way. LangChain agents, CrewAI crews, AutoGPT loops, Claude via MCP — they're all capable of initiating multiple actions in parallel or in rapid succession. An agent managing a DeFi portfolio might simultaneously:

Swap SOL for USDC on Jupiter
Stake ETH via Lido
Submit a limit order on Hyperliquid
Pay for an API call via x402

If those four actions hit the same wallet, on even two different chains, you need something that tracks nonce state correctly, queues competing transactions, and retries failed submissions — all without the agent needing to know any of this is happening.

That's the infrastructure problem WAIaaS solves. The agent just calls an API. WAIaaS handles the rest.

What Makes Multi-Network Nonce Management Hard

Before getting to the solution, it helps to understand what you're actually dealing with.

Nonces are per-account, per-chain. Your Ethereum wallet has its own nonce sequence. Your Solana wallet uses a different mechanism (recent blockhash slots). A wallet on Arbitrum has its own nonce counter separate from Ethereum mainnet, even if it's the same private key. WAIaaS supports 18 networks across 2 chain types (EVM and Solana), which means nonce state has to be tracked independently for each.

Concurrent submissions create races. If two processes read nonce 42 from the chain at the same moment and both submit with nonce 42, the network accepts one and silently drops the other. No exception. No revert. The second transaction just never exists.

AI agents are naturally concurrent. Even a single Claude conversation can trigger tool calls that fan out into multiple API requests. The MCP server for WAIaaS exposes 45 tools. An agent using send-batch, hyperliquid, and send-token in the same response is not unusual.

Stuck transactions block everything after them. If nonce 42 gets stuck (gas too low, RPC timeout, whatever), nonces 43, 44, 45 are all waiting behind it. The agent appears frozen.

How WAIaaS Handles This: The 7-Stage Pipeline

Every transaction submitted to WAIaaS — whether via REST API, TypeScript SDK, Python SDK, or any of the 45 MCP tools — goes through a 7-stage pipeline:

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

The key stage for nonce safety is stage4-wait. This is where WAIaaS serializes transactions before they touch the network.

Here's what that means in practice:

Transactions for the same wallet+chain are queued and executed in order
Nonce assignment happens immediately before broadcast, not at submission time
If execution fails, the pipeline can retry without creating a gap in the nonce sequence
The agent's API call returns a transaction ID immediately; confirmation is async

The agent doesn't wait for blockchain confirmation before it can do something else. It submits, gets an ID, and can poll or move on. WAIaaS handles the actual sequencing.

The Agent's View: Simple API, Complex Safety

From the agent's perspective, sending a transaction looks like this:

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

The agent doesn't specify a nonce. It doesn't know what network the wallet is on (that's configured at wallet creation time). It just says "send 0.1" and gets back a transaction ID.

Behind that call, WAIaaS is:

Validating the request format
Checking the session token is valid and not expired
Running the transaction through the policy engine (21 policy types, default-deny)
Queuing it in the pipeline behind any in-flight transactions for that wallet
Assigning the correct nonce at execution time
Submitting to the RPC endpoint
Polling for confirmation

If you want to test a transaction without actually submitting it, use the dry-run flag:

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

This runs the transaction through validation, auth, and policy stages but stops before execution. You get back what would have happened, including policy verdicts, without touching the chain. Useful for testing agent logic before letting it loose with real funds.

Multiple Wallets, Multiple Networks: The MCP Approach

If your agent needs to operate on multiple chains simultaneously — say, ETH on mainnet and SOL on Solana mainnet — the cleanest pattern is one MCP server per wallet. Each wallet has its own session token, its own policy set, and its own nonce sequence. There's no shared state that can collide.

The Claude Desktop config for this looks like:

{
  "mcpServers": {
    "waiaas-trading": {
      "command": "npx",
      "args": ["-y", "@waiaas/mcp"],
      "env": {
        "WAIAAS_BASE_URL": "http://127.0.0.1:3100",
        "WAIAAS_AGENT_ID": "019c47d6-51ef-7f43-a76b-d50e875d95f4",
        "WAIAAS_AGENT_NAME": "trading-agent",
        "WAIAAS_DATA_DIR": "~/.waiaas"
      }
    },
    "waiaas-solana": {
      "command": "npx",
      "args": ["-y", "@waiaas/mcp"],
      "env": {
        "WAIAAS_BASE_URL": "http://127.0.0.1:3100",
        "WAIAAS_AGENT_ID": "019c4cd2-86e8-758f-a61e-9c560307c788",
        "WAIAAS_AGENT_NAME": "solana-wallet",
        "WAIAAS_DATA_DIR": "~/.waiaas"
      }
    }
  }
}

Each MCP server instance connects to a different wallet on the same WAIaaS daemon. Claude sees two separate sets of tools — waiaas-trading tools operate on the EVM wallet, waiaas-solana tools operate on the Solana wallet. Transactions submitted through either path are independently queued and sequenced. They cannot interfere with each other's nonce state.

The CLI can auto-generate this entire configuration:

waiaas mcp setup --all

This registers all wallets known to the daemon and prints the JSON you paste into Claude Desktop config.

Policy as a Safety Net for Agent Mistakes

Nonce ordering keeps transactions from colliding at the protocol level. But AI agents can also make logical mistakes — sending to the wrong address, submitting unexpectedly large amounts, or looping on an action that should have stopped.

WAIaaS's policy engine adds a second layer. With 21 policy types and 4 security tiers (INSTANT, NOTIFY, DELAY, APPROVAL), you can set hard limits on what the agent can actually do — regardless of what it asks for.

A sensible starting policy for an agent you're testing:

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

This means:

Under $100: executes immediately (INSTANT)
$100–$500: executes immediately but you get notified (NOTIFY)
$500–$2000: waits 15 minutes before executing, giving you a cancellation window (DELAY)
Over $2000: requires your explicit approval via WalletConnect or Telegram (APPROVAL)

Combined with ALLOWED_TOKENS and CONTRACT_WHITELIST (both default-deny — the agent literally cannot interact with tokens or contracts you haven't whitelisted), you have a system where agent bugs hit policy walls before they hit the blockchain.

When a transaction is blocked by policy, the response looks like this:

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

The agent sees a clear error code it can handle, log, or report back to the user.

Building an Agent with the TypeScript SDK

For agents built in code rather than via MCP, the TypeScript SDK gives you the same pipeline access with a clean async interface:

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'],
});

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

// Submit transaction — nonce handled by WAIaaS
const sendResult = await client.sendToken({
  type: 'TRANSFER',
  to: 'recipient-address',
  amount: '0.001',
});
console.log(`Transaction submitted: ${sendResult.id} (status: ${sendResult.status})`);

// Poll for confirmation
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 the pattern: submit, get an ID, poll. The agent isn't blocking on blockchain confirmation. It can do other work between polls. And if two parts of the agent submit transactions simultaneously, WAIaaS serializes them correctly — the agent just sees two IDs to track.

Error handling is straightforward:

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

Quick Start: Agent with Safe Transaction Ordering in 5 Steps

Step 1 — Install and start WAIaaS

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

Step 2 — Create wallets and sessions

waiaas quickset --mode mainnet

This creates wallets and MCP sessions in one command.

Step 3 — Set up policies before giving the agent access

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

Step 4 — Connect Claude via MCP

waiaas mcp setup --all

Paste the output into your Claude Desktop config.

Step 5 — Test with a dry run

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

Confirm the pipeline responds correctly before sending real funds.

What's Next

The nonce problem is infrastructure. Once it's solved, the interesting work is building agents that actually do something useful — swapping tokens, managing DeFi positions, paying for their own API calls with x402. WAIaaS has 15 DeFi protocol integrations and 45 MCP tools ready to use once your transaction pipeline is stable.

Browse the full API reference at http://127.0.0.1:3100/reference after starting the daemon — it's an interactive Scalar UI generated from the OpenAPI 3.0 spec, covering all 39 REST API route modules. Everything your agent can call is documented there with live examples.

Get started:

GitHub: https://github.com/minhoyoo-iotrust/WAIaaS
Official site: https://waiaas.ai

Production Docker Architecture: WAIaaS Daemon + Push-Relay Services for Enterprise AI Wallets

Wallet Guy — Mon, 22 Jun 2026 17:47:29 +0000

Production Docker Architecture: Running WAIaaS Daemon + Push-Relay for Enterprise AI Wallets

Would you trust a third party with your AI agent's private keys? If you're building autonomous agents that move real money, that question deserves a serious answer — and for many developers, the answer is no. Self-hosting your wallet infrastructure means your keys live on your server, your policies run in your container, and no external service can rate-limit, suspend, or snoop on your agent's transactions.

Why Self-Hosting Your AI Wallet Infrastructure Matters

The case for self-hosted infrastructure in the AI wallet space isn't just philosophical — it's practical. When your agent executes DeFi trades, pays for API calls via x402, or moves funds across chains, every transaction passes through whatever infrastructure sits between the agent and the blockchain. If that infrastructure is a hosted service, you've introduced a custody and availability dependency you can't control.

Running WAIaaS on your own server flips that equation. You control the master password, the signing keys, the policy engine, and the notification channel. There are no API rate limits imposed by a third party, no Terms of Service that could cut off your agent mid-operation, and no vendor with visibility into your wallet activity. It's the crypto equivalent of running your own email server — except the tooling has matured to the point where it's actually practical.

WAIaaS is an open-source, self-hosted Wallet-as-a-Service built for AI agents. Its 15-package monorepo ships everything you need to run production wallet infrastructure: the main daemon, a push-relay service for mobile notifications, a CLI, MCP integration, and a policy engine. Let's walk through what a production Docker deployment looks like.

The Two-Service Architecture

One detail worth understanding before you deploy: WAIaaS ships two Docker images, not one.

waiaas daemon — the core wallet service. This handles the REST API (39 route modules), the 7-stage transaction pipeline, the policy engine, session auth, and DeFi integrations.
push-relay — a companion service that handles mobile push notifications for transaction approvals. When your agent submits a transaction that hits the APPROVAL tier, the push-relay is what sends the alert to your phone.

Both images live in the same repository. The daemon is the required service; push-relay is what you add when you want human-in-the-loop approval via mobile notifications rather than requiring you to be at a terminal.

This separation is deliberate. The push-relay has no access to private keys — it only receives notification events and forwards them. You can run the daemon without it, or run the push-relay on a different host entirely if your security model requires it.

Understanding the Security Model Before You Deploy

WAIaaS implements a 3-layer security architecture:

Session auth → policy evaluation — every agent transaction passes through the policy engine before execution
Time delay + approval — the DELAY and APPROVAL tiers hold transactions until conditions are met
Monitoring + kill switch — incoming transaction monitoring and owner-controlled recovery

Three auth methods govern who can do what:

masterAuth (Argon2id) — system administrator operations: creating wallets, managing sessions, setting policies
sessionAuth (JWT HS256) — what your AI agent uses for day-to-day operations: sending tokens, querying balances, executing DeFi actions
ownerAuth (SIWS/SIWE) — the fund owner: approving held transactions, using the kill switch

The policy engine enforces a default-deny model. Until you explicitly configure ALLOWED_TOKENS or CONTRACT_WHITELIST, transactions are blocked. This is the right default for production — you opt into what your agent can do, not out of what it can't.

Deploying with Docker Compose

The fastest path to a running daemon is docker compose up:

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

That's genuinely it for a first run. The image is ghcr.io/minhoyoo-iotrust/waiaas:latest and the default port binding is 127.0.0.1:3100:3100 — localhost-only by design. Your daemon is not exposed to the internet out of the box.

For a more controlled first start — useful if you want to script the setup or run headless — use the auto-provision flag:

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 the auto-generated master password
docker exec waiaas cat /data/recovery.key

WAIAAS_AUTO_PROVISION=true tells the entrypoint to generate a random master password on first boot and write it to /data/recovery.key. This is useful for automated deployments where you don't want to manually set a password before the first start. You can harden it later with waiaas set-master once the daemon is running.

Here's the full Compose configuration the project ships with:

services:
  daemon:
    image: ghcr.io/minhoyoo-iotrust/waiaas:latest
    container_name: waiaas-daemon
    ports:
      - "127.0.0.1:3100:3100"
    volumes:
      - waiaas-data:/data
    environment:
      - WAIAAS_DATA_DIR=/data
      - WAIAAS_DAEMON_HOSTNAME=0.0.0.0
    env_file:
      - path: .env
        required: false
    restart: unless-stopped
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:3100/health"]
      interval: 30s
      timeout: 5s
      start_period: 10s
      retries: 3

volumes:
  waiaas-data:
    driver: local

A few things worth noting in this config:

Named volume (waiaas-data) — your wallet data persists across container restarts and updates. docker compose down without -v leaves your data intact.
Healthcheck — Docker will restart the container if the health endpoint stops responding. Good for unattended production runs.
restart: unless-stopped — the daemon comes back after host reboots.
127.0.0.1:3100 — only localhost can reach it. If you need external access, put a reverse proxy (nginx, Caddy) in front and handle TLS there. Don't expose port 3100 directly to the internet.

Production Secrets Management

The docker-compose.secrets.yml overlay is how you handle credentials in production without putting them in environment variables or .env files that end up in logs.

# 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

Docker Secrets integration is supported directly in the entrypoint. The secret files are mounted into the container at runtime and read by the entrypoint script — they never appear in docker inspect output or process environment listings.

For self-hosters who care about operational security, this is the right way to run it. Your master password lives in a file with 600 permissions, not in a shell history or a .env file sitting next to your docker-compose.yml.

Key Environment Variables

The daemon is configured primarily through environment variables. The important ones for a production deployment:

WAIAAS_AUTO_PROVISION=true              # Auto-generate master password on first start
WAIAAS_DAEMON_PORT=3100                 # Listening port
WAIAAS_DAEMON_HOSTNAME=0.0.0.0         # Bind address
WAIAAS_DAEMON_LOG_LEVEL=info            # Log level (trace/debug/info/warn/error)
WAIAAS_DATA_DIR=/data                   # Data directory
WAIAAS_RPC_SOLANA_MAINNET=<url>         # Solana mainnet RPC endpoint
WAIAAS_RPC_EVM_ETHEREUM_MAINNET=<url>   # Ethereum mainnet RPC endpoint

The RPC endpoint variables matter for production. The daemon needs RPC access for 2 chain types across 18 networks. If you're running a self-hosted Solana or Ethereum node, this is where you point the daemon at it — keeping your infrastructure fully sovereign, not just your keys.

Setting Up Wallets and Policies

Once the daemon is running, the CLI handles the initial setup. Install it globally:

npm install -g @waiaas/cli

The CLI ships 20 commands. For initial setup, the relevant flow is:

waiaas init                        # Create data directory + config.toml
waiaas start                       # Start daemon
waiaas quickset --mode mainnet     # Create wallets + MCP sessions in one step

quickset is the fast path. It creates wallets across the chains you configure and generates MCP sessions — the tokens your AI agent will use.

For manual control, create a wallet directly via the API:

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

Then create a session token for your agent:

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

That session token is what your agent uses. It has no access to wallet creation or policy management — only to the operations you've allowed through policies.

Configuring the Policy Engine for Production

The default-deny model means you need to configure policies before your agent can do anything useful. Here's a sensible starting point for a trading wallet — a spending limit with four tiers:

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

This gives you the full 4-tier security model in action:

≤$100: executes immediately, no noise
$100–$500: executes immediately, sends a notification
$500–$2,000: queued for 15 minutes, then executes (you can cancel during the window)
>$2,000: held until you explicitly approve via WalletConnect, Telegram, or push notification

The 21 policy types cover everything from token whitelists and contract whitelists to DeFi-specific rules like PERP_MAX_LEVERAGE for perpetual futures positions and LENDING_LTV_LIMIT for lending protocols. For production, you'll want at minimum ALLOWED_TOKENS and CONTRACT_WHITELIST configured — without them, the default-deny model blocks token transfers and contract calls entirely.

Connecting Your Agent via MCP

Once the daemon is running and wallets are configured, connecting Claude or another MCP-compatible AI is a one-command operation:

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

Or configure it manually in claude_desktop_config.json:

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

The MCP server exposes 45 tools covering wallet operations, transactions, DeFi actions across 15 integrated protocols, NFT operations, and x402 HTTP payment. Your agent gets a session-scoped, policy-enforced interface to your self-hosted wallet — no third-party relay, no external API calls beyond the blockchain RPCs you've configured.

Useful Docker Operations

docker compose up -d          # Start daemon
docker compose logs -f        # Follow logs
docker compose down           # Stop (data preserved in named volume)
docker compose down -v        # Stop + delete data volume

The named volume approach means updates are safe. Pull a new image, bring the stack down without -v, and bring it back up — your wallet data is untouched. The daemon's healthcheck will tell Docker when it's ready.

For debugging, the OpenAPI spec and interactive docs are available while the daemon is running:

# Download OpenAPI 3.0 spec
curl http://127.0.0.1:3100/doc -o openapi.json

# View interactive API reference in browser
open http://127.0.0.1:3100/reference

The interactive reference at /reference (built with Scalar) makes it straightforward to explore the 39 API routes without reading raw JSON.

Quick Start Summary

If you want to go from zero to a running, policy-protected AI wallet in the shortest path:

Clone and start: git clone https://github.com/minhoyoo-iotrust/WAIaaS.git && cd WAIaaS && docker compose up -d
Install the CLI: npm install -g @waiaas/cli
Create wallets and sessions: waiaas quickset --mode mainnet
Connect to Claude: waiaas mcp setup --all
Set spending policies via the REST API or Admin UI at /admin before letting your agent operate on mainnet

The entire stack runs on your hardware. The push-relay handles mobile approvals. The policy engine enforces your rules. The keys never leave your server.

What's Next

The WAIaaS repository has detailed documentation on advanced policy configurations, the 15 integrated DeFi protocols, and the full SDK for building agents programmatically. If you're building something beyond a single-agent setup — multiple agents, multiple wallets, different policy profiles per agent — the multi-wallet MCP configuration and the TypeScript/Python SDKs are the natural next step.

The code is open source, the deployment is yours, and the keys stay where they belong.

→ GitHub: https://github.com/minhoyoo-iotrust/WAIaaS
→ Official site: https://waiaas.ai

When Machines Become Economic Actors: The x402 Payment Revolution

Wallet Guy — Mon, 22 Jun 2026 12:29:41 +0000

When Machines Become Economic Actors: The x402 Payment Revolution

AI agents are already browsing the web, writing code, and making decisions — but they still can't pay for what they use. That's not a philosophical problem; it's a missing infrastructure layer, and it's blocking a category of applications that should exist right now. The x402 HTTP payment protocol changes that equation, and pairing it with autonomous wallet infrastructure makes AI agents full economic participants for the first time.

The Problem Is Concrete, Not Hypothetical

Think about what a capable AI agent actually needs to do its job. It needs data feeds. It needs compute. It calls APIs — weather services, market data providers, translation APIs, image generation endpoints. Every one of those services costs money. Right now, that cost is invisible to the agent. A human developer pre-pays for API keys, embeds credentials in environment variables, and hopes the agent doesn't hit rate limits or run up a bill the developer didn't anticipate.

That model breaks at scale. If you're running ten agents, it's annoying. If you're running a thousand, it's unmanageable. And if you're building a system where agents spawn sub-agents dynamically, the entire model collapses — you can't pre-provision API keys for agents that don't exist yet.

The deeper issue is that this dependency makes agents fundamentally non-autonomous. An agent that can't pay for its own resources is like a contractor who can't buy their own materials — every job requires a trip back to headquarters to ask for money. Real autonomy means the agent can acquire what it needs, when it needs it, within the limits you've set.

The x402 Moment

The HTTP 402 status code has existed since 1991. It was defined as "Payment Required" and marked "reserved for future use." That future is arriving now.

The x402 protocol gives this status code teeth. When an AI agent makes an HTTP request to a paid API, the server can respond with a 402 status and payment metadata — which blockchain, which token, how much. The agent settles the payment on-chain and retries the request with a payment receipt header. The API server verifies the payment and serves the content.

From the agent's perspective, this is completely transparent. It makes a fetch call. If the resource requires payment, payment happens automatically. If the resource is free, nothing changes. No API key management. No pre-loaded credits. No human in the loop.

This is what WAIaaS's x402Fetch method actually does today:

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

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

// This automatically handles 402 responses and pays with the agent's wallet
const response = await client.x402Fetch('https://api.some-paid-service.com/data');

The agent calls x402Fetch exactly like it would call fetch. If the server returns a 402, WAIaaS handles negotiation, settlement, and retry — all within the same call. The agent gets its data. The API provider gets paid. No human saw any of it.

You can also interact with x402-capable endpoints directly through the REST API:

curl -X POST http://127.0.0.1:3100/v1/actions/x402-fetch \
  -H "Authorization: Bearer wai_sess_<token>" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://api.some-paid-service.com/data"}'

Why Wallets Have to Be Different for Agents

At this point you might be thinking: can't you just give an agent a standard crypto wallet? Load it with funds, hand it a private key, let it sign transactions?

You can. And you probably shouldn't, at least not without guardrails. The difference between an autonomous agent and an autonomous agent with a spending limit is the difference between a capable employee and one who can commit the company to unlimited financial obligations.

WAIaaS was built around the assumption that autonomous agents need wallets that are designed for delegation — not just wallets that technically work. That means a few things:

Session-scoped access. An agent doesn't hold the private key to the wallet. It holds a session token that grants time-limited, scope-limited access. The session can be revoked instantly. When the agent is done, the session expires. The wallet remains under the owner's control.

Policy enforcement at the infrastructure layer. Before any transaction executes, it runs through a 7-stage pipeline that includes policy evaluation. There are 21 policy types covering everything from spending limits to allowed token lists to DeFi-specific constraints like maximum leverage for perpetual futures. Policies aren't applied by the agent — they're enforced on the agent by the wallet infrastructure.

Default-deny for token transfers. If you haven't explicitly configured an ALLOWED_TOKENS policy, token transfer transactions are blocked. An agent can't drain your wallet of a token you didn't know it could access. This is the right default.

For x402 payments specifically, there's an X402_ALLOWED_DOMAINS policy that whitelists which domains an agent is permitted to pay:

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": "X402_ALLOWED_DOMAINS",
    "rules": {
      "domains": ["api.example.com", "*.openai.com"]
    }
  }'

This means even if a malicious page returns a 402, the agent's wallet infrastructure will refuse to pay it. The allowed domain list is your firewall for agent payments.

The Four Security Tiers

One of the design choices in WAIaaS that matters for agent autonomy is the four-tier security model: INSTANT, NOTIFY, DELAY, and APPROVAL.

Not every transaction is equal. Paying $0.003 for an API call should happen instantly and silently — interrupting a human to approve a fraction of a cent is counterproductive. Sending $5,000 somewhere should probably require a human to confirm.

The SPENDING_LIMIT policy encodes this logic:

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

Under this configuration: x402 micro-payments under $10 execute instantly. Payments up to $100 execute but send a notification. Payments up to $1,000 are queued for five minutes — giving you time to cancel if something looks wrong. Anything above $1,000 requires your explicit approval via WalletConnect or Telegram.

This is what calibrated autonomy looks like. The agent operates freely within the bounds you've defined. It doesn't need to ask permission for small, routine transactions. But the infrastructure catches anything that falls outside the envelope you've established.

Getting a Working Agent on x402 in Under Ten Minutes

This is a real setup, not a demo with mocked responses. Here's the minimal path from zero to an agent that can make x402 payments:

Step 1: Start WAIaaS

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

On first start, you'll set a master password. This is the masterAuth credential — it controls wallet creation, session management, and policy configuration. Keep it offline.

Step 2: Create a wallet and session

# 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": "agent-wallet", "chain": "solana", "environment": "mainnet"}'

# Create a session for the agent (save the token from the response)
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>"}'

Or use the quickset command to do both in one step: waiaas quickset --mode mainnet

Step 3: Configure x402 payment 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": "X402_ALLOWED_DOMAINS",
    "rules": {
      "domains": ["api.example.com"]
    }
  }'

Step 4: Fund the wallet and connect your agent

Send a small amount of SOL (or ETH, depending on your chain) to the wallet address. Then give your agent the session token. With the TypeScript SDK:

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}`);

// Now the agent can pay for APIs automatically
const data = await client.x402Fetch('https://api.example.com/market-data');

Step 5: Connect to Claude via MCP (optional)

If you're using Claude as your agent runtime, WAIaaS provides 45 MCP tools that Claude can call directly — including x402-fetch:

waiaas mcp setup --all

This auto-generates the Claude Desktop configuration and registers your wallet. Claude can then check balances, send tokens, make x402 payments, and interact with DeFi protocols through natural language.

What the Agent Economy Actually Looks Like

The x402 pattern enables something that's easy to underestimate: agents that are cost-aware. Right now most agents operate as if API calls are free. With x402, an agent can see exactly what it's spending, decide whether a data source is worth the price, compare costs across providers, and optimize its behavior accordingly.

This isn't science fiction. The infrastructure exists today. WAIaaS ships with a Python SDK as well as TypeScript, so agents built in either ecosystem can participate:

from waiaas import WAIaaSClient

async with WAIaaSClient("http://localhost:3100", "wai_sess_xxx") as client:
    balance = await client.get_balance()
    print(f"Agent budget: {balance.balance} {balance.symbol}")

The remaining gap is on the supply side: more APIs need to implement x402 response handling. That adoption curve is a separate conversation. But the agent infrastructure is ready — and having agents that are capable of paying is what will push API providers to implement the protocol.

The Monitoring Layer

One concern that comes up immediately when you give agents autonomous spending authority: how do you know what they're doing?

WAIaaS includes incoming transaction monitoring with real-time notifications for deposits. The transaction pipeline logs every stage — validation, policy evaluation, execution, confirmation. Every transaction the agent attempts is recorded, whether it succeeded, was delayed, required approval, or was blocked by policy.

There's also a dry-run mode that lets agents (or developers testing agents) simulate a transaction before executing it:

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

And if something goes wrong — if an agent behaves unexpectedly, if a session token is compromised — the owner can revoke access immediately using WalletConnect-based approval flows. The DELAY tier is particularly useful here: large transactions sit in a queue for a configurable period before executing, giving you a window to cancel without the agent having any ability to rush the transaction through.

What Comes Next

The x402 pattern is a starting point, not a ceiling. Agents that can pay for API calls can also participate in more complex economic arrangements — lending protocols, prediction markets, perpetual futures, cross-chain asset movements. WAIaaS integrates 15 DeFi protocol providers for exactly this reason. The same wallet infrastructure that handles a $0.003 API payment can also manage a position on Hyperliquid or provide liquidity on Aave.

The shift happening right now isn't just technical. It's that agents are moving from tools that humans use to participants in systems that include humans. An agent that has its own wallet, earns from its work, and spends on what it needs is a different kind of entity than a chatbot. The infrastructure to support that transition exists today.

Explore the project on GitHub at https://github.com/minhoyoo-iotrust/WAIaaS or learn more about what's available at https://waiaas.ai. The API reference is live at /reference once you have a daemon running — 39 route modules, interactive docs, and no account required to start experimenting.

Hyperliquid Sub-Accounts: Advanced Position Management for AI Trading Bots

Wallet Guy — Sun, 21 Jun 2026 15:16:41 +0000

Hyperliquid Sub-Accounts: Advanced Position Management for AI Trading Bots

Hyperliquid sub-accounts give your trading bot the isolation it needs to run parallel strategies without cross-contaminating risk — but wiring up the signing logic, policy guards, and cross-protocol hedging yourself is where most teams sink weeks. If you're building an automated trading system that touches Hyperliquid perpetuals, you need wallet infrastructure that keeps up with your execution logic without becoming the bottleneck.

Why Infrastructure Is the Hidden Bottleneck

Algo traders spend most of their time on signal generation and execution logic. Wallet plumbing — key management, transaction signing, approval flows, risk limits — gets bolted on at the end, and that's exactly when it breaks. A missed position because the signing layer threw an unexpected error, a blown leverage limit because nothing was enforcing it programmatically, or a rogue session token that outlived its usefulness: these are infrastructure failures, not strategy failures.

The same problem gets worse at scale. If you're running multiple sub-accounts on Hyperliquid — one for momentum, one for delta-neutral, one for arb — each account needs its own session, its own policy envelope, and its own audit trail. Managing that manually with raw private keys is a liability waiting to materialize.

WAIaaS is an open-source, self-hosted Wallet-as-a-Service built specifically for AI agents and automated bots. It gives you a REST API, 45 MCP tools, and a 7-stage transaction pipeline with policy enforcement baked in — so your bot focuses on alpha, not key hygiene.

What WAIaaS Brings to Hyperliquid Trading

WAIaaS integrates Hyperliquid directly as one of its 15 DeFi protocol providers. That means perpetual futures, spot trading, and sub-accounts are all accessible through the same session-authenticated REST API your bot already uses for everything else.

The full protocol list spans aave-v3, across, dcent-swap, drift, erc8004, hyperliquid, jito-staking, jupiter-swap, kamino, lido-staking, lifi, pendle, polymarket, xrpl-dex, and zerox-swap. For a trading bot, that means you can express a complete strategy — long perp on Hyperliquid, hedge spot on Jupiter, bridge collateral via LI.FI — through one API surface with one authentication model.

No juggling five different SDKs with five different key formats.

The Policy Engine: Your Risk Manager in Code

Before we get to execution, let's talk about the piece that matters most for automated systems: enforcing limits programmatically.

WAIaaS ships a policy engine with 21 policy types and 4 security tiers (INSTANT, NOTIFY, DELAY, APPROVAL). For Hyperliquid specifically, the relevant policies are:

PERP_MAX_LEVERAGE — hard cap on leverage your bot can set
PERP_MAX_POSITION_USD — maximum notional per position
PERP_ALLOWED_MARKETS — whitelist of tradeable markets
SPENDING_LIMIT — amount-based 4-tier routing for all outgoing value
VENUE_WHITELIST — allowed trading venues

The system is default-deny: if ALLOWED_TOKENS or CONTRACT_WHITELIST isn't configured, transactions are blocked. That's the right default for an autonomous bot. You define exactly what it can touch, and everything else is denied.

Here's how to set a spending limit with tiered security for a trading wallet:

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

With this configuration: transactions under $100 execute immediately (INSTANT), $100–$500 execute and notify you (NOTIFY), $500–$2000 queue for 15 minutes before executing (DELAY), and anything above $2000 requires explicit human approval (APPROVAL). Your bot can operate autonomously within its lane, and anything anomalous gets caught before it hits the chain.

Setting Up a Trading Bot: Step by Step

1. Deploy the Daemon

Start with Docker — the image is ghcr.io/minhoyoo-iotrust/waiaas:latest and binds to 127.0.0.1:3100 by default.

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

For automated deployments, use auto-provision mode to generate the master password without manual input:

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

docker exec waiaas cat /data/recovery.key

2. Create a Trading Wallet and Session

# Create a wallet for Hyperliquid trading
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": "hyperliquid-perp", "chain": "evm", "environment": "mainnet"}'

# Create a session token for the bot
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>"}'

The session token (wai_sess_...) is what your bot uses for all subsequent calls. It's JWT HS256, scoped to a wallet, and has configurable TTL, maxRenewals, and absoluteLifetime. You can run separate sessions for separate sub-account strategies — each session gets its own policy envelope.

3. Apply Perp-Specific Policies

Before your bot touches Hyperliquid, lock down what it can do:

# Cap leverage at 10x
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": "PERP_MAX_LEVERAGE",
    "rules": {"max_leverage": 10}
  }'

# Cap max position size
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": "PERP_MAX_POSITION_USD",
    "rules": {"max_position_usd": 50000}
  }'

4. Execute a DeFi Action Through the Bot's Session

Once policies are in place, your bot calls the Hyperliquid provider through its session token:

curl -X POST http://127.0.0.1:3100/v1/actions/hyperliquid/<action-name> \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer wai_sess_<token>" \
  -d '{...}'

The 7-stage transaction pipeline handles validation, auth check, policy evaluation, optional wait (for DELAY-tier), execution, and confirmation — in that order. Your bot doesn't need to implement any of that logic itself.

5. Simulate Before Committing

For strategies where getting the trade wrong is expensive, use dry-run mode to simulate before submitting:

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 simulation runs through the full pipeline — policy checks included — without touching the chain. You get the exact outcome your bot would see on a live submission.

Gas Conditional Execution

One detail that matters for algorithmic systems: WAIaaS supports gas conditional execution, meaning transactions only execute when the gas price meets a configured threshold. For bots doing high-frequency or cost-sensitive operations, this is the difference between a profitable trade and a margin-eroded one.

You define the threshold; the pipeline checks it before execution. If gas is above the limit, the transaction waits. No polling loop in your bot code, no manual gas price checks — the pipeline handles it.

Multi-Strategy Architecture with Separate Sessions

Here's a pattern that works well for Hyperliquid sub-account strategies: one WAIaaS daemon, multiple wallets, multiple sessions, each with its own policy set.

WAIaaS Daemon
├── Wallet A (hyperliquid-momentum)
│   ├── Session: bot-momentum-001
│   ├── Policy: PERP_MAX_LEVERAGE = 5x
│   └── Policy: PERP_ALLOWED_MARKETS = BTC-USD, ETH-USD
│
├── Wallet B (hyperliquid-arb)
│   ├── Session: bot-arb-001
│   ├── Policy: PERP_MAX_LEVERAGE = 2x
│   └── Policy: SPENDING_LIMIT = $500 instant / $2000 delay
│
└── Wallet C (hyperliquid-delta-neutral)
    ├── Session: bot-dn-001
    └── Policy: PERP_MAX_POSITION_USD = $25000

Each bot process holds its own session token. Policies are enforced independently. If one strategy goes rogue — unexpected order size, wrong market, leverage spike — the policy engine blocks it without affecting the others.

TypeScript SDK for Bot Integration

If you'd rather use a typed SDK than raw curl, the TypeScript SDK (@waiaas/sdk) gives you the same capabilities with async/await and typed errors:

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'],
});

// Check balance before opening position
const balance = await client.getBalance();
console.log(`Balance: ${balance.balance} ${balance.symbol} (${balance.chain}/${balance.network})`);

// Submit transaction with error handling
try {
  const tx = await client.sendToken({
    type: 'TRANSFER',
    to: 'recipient-address',
    amount: '0.001',
  });

  // Poll for confirmation
  const POLL_TIMEOUT_MS = 60_000;
  const startTime = Date.now();
  while (Date.now() - startTime < POLL_TIMEOUT_MS) {
    const result = await client.getTransaction(tx.id);
    if (result.status === 'COMPLETED') {
      console.log(`Confirmed: ${result.txHash}`);
      break;
    }
    if (result.status === 'FAILED') {
      console.error(`Failed: ${result.error}`);
      break;
    }
    await new Promise(resolve => setTimeout(resolve, 1000));
  }
} catch (error) {
  if (error instanceof WAIaaSError) {
    // Structured errors: INSUFFICIENT_BALANCE, POLICY_DENIED, TOKEN_EXPIRED
    console.error(`[${error.code}] ${error.message}`);
  }
}

The Python SDK (waiaas) follows the same pattern with async/await if your bot stack is Python.

Human-in-the-Loop for High-Stakes Trades

For positions that exceed your APPROVAL tier threshold, WAIaaS integrates WalletConnect so the fund owner gets a signing request on their mobile wallet. The bot submits the transaction, it queues for approval, and execution only proceeds when the owner signs.

Three signing channels are available: push-relay, Telegram, and wallet-notification. You configure whichever fits your ops setup. For a trading team running a large book, Telegram notifications for anything above $10k with mobile approval is a sensible pattern — the bot handles everything below that autonomously.

# Approve a queued transaction (owner signs off-chain, submits via API)
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>"

MCP Integration for AI-Driven Trading

If your trading system uses an LLM layer — Claude, GPT, or any MCP-compatible agent framework — WAIaaS exposes 45 MCP tools covering wallet, transaction, DeFi, NFT, and x402 operations. The hyperliquid and polymarket tools are available directly, so an AI agent can reason about positions, execute trades, and query state without custom tool code.

Setup is one command:

waiaas mcp setup --all

That auto-registers all wallets with Claude Desktop. For multi-strategy setups, configure separate MCP servers per wallet so each AI agent operates within its own session scope.

What's Next

The full API surface — 39 REST route modules with an OpenAPI 3.0 spec and interactive Scalar reference UI at /reference — is the place to go deep on Hyperliquid-specific action parameters and the complete policy schema. The 683+ test files in the codebase are also worth reading if you want to understand exactly how the pipeline handles edge cases.

If you're building something where execution reliability and risk containment matter more than convenience, self-hosting WAIaaS gives you full control over the signing layer, the policy engine, and the audit trail — nothing passes through third-party infrastructure.

Explore the codebase and deploy your own instance:

GitHub: https://github.com/minhoyoo-iotrust/WAIaaS
Official site: https://waiaas.ai

ALLOWED_TOKENS + CONTRACT_WHITELIST: The Foundation of AI Agent Security

Wallet Guy — Sun, 21 Jun 2026 10:08:40 +0000

ALLOWED_TOKENS + CONTRACT_WHITELIST: The Foundation of AI Agent Security

Giving an AI agent a wallet without guardrails is like giving a toddler a credit card — the agent might be perfectly capable of executing trades, but one misconfigured prompt or unexpected edge case can drain your funds before you can blink. If you're building anything that lets an AI agent sign transactions on your behalf, the question isn't whether you need security controls — it's which controls actually prevent the scenarios that matter.

Why This Is a Hard Problem

Most wallet security is designed around human users who behave predictably. You log in, you review a transaction, you click confirm. AI agents don't work that way. They receive instructions in natural language, interpret them, and fire off API calls — sometimes in rapid succession, sometimes for amounts and contracts they've never touched before. A prompt injection in a data source, an overly broad system prompt, or a simple misunderstanding can translate directly into an on-chain transaction.

The security model has to shift. You can't rely on the agent to know what it shouldn't do. You need a layer that enforces those limits at the infrastructure level, before any transaction reaches the network — regardless of what the agent believes it was asked to do.

WAIaaS approaches this with three layers between your agent and your funds: session authentication, a policy engine with default-deny enforcement, and human approval channels for high-stakes operations. This post focuses on the two policies that form the foundation of that middle layer: ALLOWED_TOKENS and CONTRACT_WHITELIST.

The Default-Deny Principle

Before getting into specifics, it's worth understanding the default posture. In WAIaaS, the policy engine operates on default-deny: if ALLOWED_TOKENS or CONTRACT_WHITELIST is not configured for a wallet, those transaction types are blocked. The agent doesn't get to try and fail — the request never reaches the network.

This is the opposite of how most systems work. Most systems are default-allow with optional restrictions layered on top. Default-allow is convenient for development and catastrophic for production. Default-deny means you make an explicit decision about every token and every contract your agent is permitted to interact with. Anything outside that explicit list returns a POLICY_DENIED error immediately.

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

The error is not retryable. There is no fallback. The transaction is dead on arrival.

ALLOWED_TOKENS: Controlling What the Agent Can Send

ALLOWED_TOKENS is a whitelist of token contracts your agent is permitted to transfer. If a token address isn't on the list, the transaction is blocked — full stop.

Here's what that policy configuration looks like:

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

This policy is set via masterAuth — the system administrator credential authenticated with Argon2id. The AI agent itself, which only holds a sessionAuth JWT, cannot create or modify policies. That separation is intentional and critical. The agent operates within whatever envelope the operator defines; it has no mechanism to expand that envelope.

The practical implication: if your agent is a USDC-only treasury bot, you configure exactly one token in ALLOWED_TOKENS. Any attempt to transfer SOL, any other SPL token, any ERC-20 — denied. Even if the agent is convinced by a user or a data source that it should be doing something else.

CONTRACT_WHITELIST: Controlling What the Agent Can Call

Token transfers are only half the picture. DeFi interactions — swaps, lending, staking — go through smart contracts. CONTRACT_WHITELIST gives you the same default-deny control over contract interactions.

curl -X POST http://localhost:3100/v1/policies \
  -H 'Content-Type: application/json' \
  -H 'X-Master-Password: <password>' \
  -d '{
    "walletId": "<wallet-uuid>",
    "type": "CONTRACT_WHITELIST",
    "rules": {
      "contracts": [
        {
          "address": "JUP6LkbZbjS1jKKwapdHNy74zcZ3tLUZoi5QNyVTaV4",
          "name": "Jupiter",
          "chain": "solana"
        }
      ]
    }
  }'

If your agent is authorized to swap via Jupiter, that's the one contract address in the list. An attempt to call any other program — a new DEX, a yield protocol your agent found in some documentation, a contract it was hallucinated into believing exists — hits the whitelist and stops.

This matters particularly for prompt injection scenarios. A malicious document or API response that tells your agent to "approve spending to 0x[attacker-contract]" can't actually succeed if that address isn't in CONTRACT_WHITELIST. The policy layer doesn't read natural language; it reads transaction parameters.

Layering Policies: Defense in Depth

ALLOWED_TOKENS and CONTRACT_WHITELIST are the access control layer — they define what the agent can interact with. But WAIaaS gives you additional policies to layer on top of that foundation.

The policy engine supports 21 policy types in total. For a security-focused deployment, you'd typically combine several:

SPENDING_LIMIT adds amount-based tier escalation on top of the token whitelist. Even if USDC is an allowed token, you can require human approval for transfers above a certain threshold:

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 four security tiers work like this:

INSTANT — execute immediately, no notification
NOTIFY — execute immediately, send you a notification
DELAY — queue the transaction for delay_seconds, then execute (you can cancel it during that window)
APPROVAL — full stop, requires your explicit approval via WalletConnect, Telegram, or push notification

APPROVED_SPENDERS closes a common attack vector: token approvals. An AI agent managing DeFi positions will sometimes need to call approve() to allow a protocol to spend tokens on its behalf. APPROVED_SPENDERS applies default-deny to that operation — only whitelisted addresses can be approved, and you can cap the maximum approval amount:

{
  "spenders": [
    {
      "address": "0xDEF1...",
      "name": "Uniswap Router",
      "maxAmount": "1000000000"
    }
  ]
}

APPROVE_AMOUNT_LIMIT and APPROVE_TIER_OVERRIDE give you further control over approval transactions specifically — blocking unlimited approvals and forcing them through the APPROVAL tier regardless of dollar amount.

The Three-Layer Architecture

Zooming out, the full security model has three layers:

Session authentication — AI agents authenticate with JWT session tokens (sessionAuth). Sessions have configurable TTL, maximum renewals, and absolute lifetime. The agent can't extend its own session or escalate its own permissions. Session creation is masterAuth only.
Policy engine — The 7-stage transaction pipeline runs every transaction through validation, authentication, and policy enforcement before execution. Policies are evaluated in the stage3-policy stage. A POLICY_DENIED result terminates the pipeline immediately.
Human approval channels — Transactions that reach the APPROVAL tier don't execute until you sign off. WAIaaS supports WalletConnect integration for owner approval, with the owner authenticating via ownerAuth (SIWE for EVM, SIWS for Solana). There are 3 signing channels available: push-relay, Telegram, and wallet notification.

These layers are independent. Compromising the session token doesn't let an attacker bypass policy. Bypassing policy would require masterAuth credentials, which aren't exposed to the agent at all.

Simulating Before You Deploy

Before putting any of this in production, you should verify that your policies behave the way you expect them to. WAIaaS has a dry-run API for exactly this purpose:

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

With dryRun: true, the transaction runs through the full pipeline — validation, policy evaluation, simulation — but never broadcasts to the network. You get back the same response structure you'd get from a real transaction, including any policy denials. This lets you confirm that your ALLOWED_TOKENS and CONTRACT_WHITELIST configurations are actually blocking what you think they're blocking before real funds are involved.

Quick Start: Securing Your First Agent Wallet

Here's the minimal path to a policy-hardened agent wallet:

Step 1: Start WAIaaS

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: Apply ALLOWED_TOKENS — whitelist only the tokens your agent needs

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

Step 4: Apply CONTRACT_WHITELIST — whitelist only the contracts your agent needs to call

Step 5: Test with dry-run — confirm policy denials work before going live, using the dryRun: true flag shown above.

The session token goes to your agent. The master password stays with you. Your agent now operates in an explicitly defined envelope, and anything outside that envelope fails fast with a clear error code.

What This Looks Like at Runtime

Once your agent is running with the TypeScript SDK, the security layer is invisible when everything is authorized — and loud when it isn't:

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'],
});

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 with retryable: false means the policy engine caught it. The transaction never left your machine. You have a complete audit trail in the daemon logs, and your funds are untouched.

The Honest Assessment

No security system is perfect. WAIaaS's policy engine operates at the transaction level — it enforces rules about what gets signed and sent, not about why your agent decided to send it. If your agent is given legitimate authorization to transfer USDC to a whitelisted address, and it does so because it was manipulated, that transaction will execute.

The value of ALLOWED_TOKENS and CONTRACT_WHITELIST is that they constrain the blast radius. A compromised agent with a narrow token whitelist and a small spending limit can do far less damage than one with no policy controls at all. The DELAY tier gives you a cancellation window. The APPROVAL tier requires you to be in the loop entirely.

Layer these with sensible system prompts, conservative spending limits, and regular review of your agent's transaction history. The policy engine is one part of a broader security practice, not a substitute for it.

What's Next

The full OpenAPI 3.0 spec for WAIaaS is available at http://127.0.0.1:3100/doc, with an interactive reference UI at /reference — useful for exploring the complete policy configuration surface. The codebase is open source, so you can review exactly how the 7-stage transaction pipeline evaluates policies before trusting it with real funds.

If you're ready to go further, the GitHub repository is at https://github.com/minhoyoo-iotrust/WAIaaS and the official site is at https://waiaas.ai. Both have the current documentation and deployment guides for getting a hardened instance running in production.

Zero-Config Docker Deployment: Auto-Provisioning Your Self-Hosted Crypto Wallet

Wallet Guy — Sat, 20 Jun 2026 15:09:35 +0000

Zero-Config Docker Deployment: Auto-Provisioning Your Self-Hosted Crypto Wallet

Docker makes running your own self-hosted crypto wallet infrastructure surprisingly approachable — no third-party custody, no rate limits, no one else holding your AI agent's private keys. If you've ever asked yourself whether you'd trust a hosted service with keys that control real funds on behalf of an autonomous agent, you already know the answer. This post walks through how WAIaaS handles the hardest part of self-hosting: that first-run setup that usually trips people up.

Would You Hand a Stranger Your Keys?

Here's the uncomfortable truth about most "Wallet-as-a-Service" offerings: when you use a hosted provider, someone else generates, stores, and ultimately controls the cryptographic keys that sign your transactions. For personal wallets, that's a familiar trade-off. For AI agents that transact autonomously — potentially 24/7, across DeFi protocols, with real funds — it's a much bigger bet.

The self-hosted alternative has traditionally meant accepting a painful setup process: generating keys manually, configuring secure storage, wiring up RPC endpoints, building your own policy layer. Most developers give up and go back to the hosted option. WAIaaS is designed to eliminate that gap. You get the sovereignty of self-hosting with a setup experience that doesn't require a weekend.

The Self-Hosting Philosophy

Running your own infrastructure is the crypto equivalent of hosting your own email server — except in 2026, Docker has made this actually practical rather than aspirational. When you self-host WAIaaS:

Your private keys never leave your machine
No third party can rate-limit, suspend, or inspect your agent's transactions
You control the upgrade cycle — nothing changes unless you choose to update
Your data (transaction history, policy configs, session tokens) stays on your hardware

This matters especially for AI agents. An autonomous trading agent or a workflow bot that handles payments needs a wallet backend it can rely on without external dependencies introducing latency, outages, or policy changes outside your control.

WAIaaS is open-source and built as a 15-package monorepo. The Docker image — ghcr.io/minhoyoo-iotrust/waiaas:latest — packages the daemon that handles everything: key management, policy enforcement, DeFi protocol integrations, MCP tools for AI frameworks, and the REST API your agents call.

The Auto-Provision Feature: Zero First-Run Friction

The single biggest barrier to self-hosting any secrets-management service is the bootstrap problem: you need a master password before you can do anything, but generating and storing that password securely is exactly the kind of thing people get wrong.

WAIaaS solves this with WAIAAS_AUTO_PROVISION. When this environment variable is set to true, the daemon generates a cryptographically random master password on first start, writes it to /data/recovery.key, and continues without waiting for human input. You retrieve the password after startup and store it somewhere safe.

Here's the single-container version:

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

Notice the port binding: 127.0.0.1:3100:3100. This is intentional — the daemon listens only on localhost by default, so it's not exposed to the network until you explicitly decide otherwise. That's the right default for a service that controls signing keys.

Docker Compose: The Practical Setup

For anything beyond a quick test, Docker Compose is the right approach. WAIaaS ships a docker-compose.yml you can use directly:

services:
  daemon:
    image: ghcr.io/minhoyoo-iotrust/waiaas:latest
    container_name: waiaas-daemon
    ports:
      - "127.0.0.1:3100:3100"
    volumes:
      - waiaas-data:/data
    environment:
      - WAIAAS_DATA_DIR=/data
      - WAIAAS_DAEMON_HOSTNAME=0.0.0.0
    env_file:
      - path: .env
        required: false
    restart: unless-stopped
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:3100/health"]
      interval: 30s
      timeout: 5s
      start_period: 10s
      retries: 3

volumes:
  waiaas-data:
    driver: local

A few things worth noting here:

Named volume for data persistence. waiaas-data is a Docker-managed named volume. This means docker compose down preserves your wallets and transaction history. You'd need docker compose down -v to actually delete data — a deliberate extra step that prevents accidental key loss.

Built-in healthcheck. The compose file includes a healthcheck that polls /health every 30 seconds. This integrates naturally with Docker's restart policies and with monitoring tools in a homelab setup.

The daemon runs as UID 1001 (non-root). This is a security default baked into the Docker image — the process doesn't have root privileges inside the container.

Getting started with Compose is three commands:

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

Production Secrets: Docker Secrets Overlay

For a homelab or production deployment where you want proper secrets management, WAIaaS supports Docker Secrets via a docker-compose.secrets.yml overlay. This keeps your master password out of environment variables entirely:

# 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 pattern means your actual credentials never appear in docker inspect output, shell history, or .env files that might accidentally get committed to version control. For anyone running a homelab where the threat model includes shared machines or accidentally public repositories, this is worth the extra step.

Key Environment Variables

The daemon is configured entirely through environment variables — no config files to manually edit before first boot. The most important ones:

WAIAAS_AUTO_PROVISION=true              # Auto-generate master password on first start
WAIAAS_DAEMON_PORT=3100                 # Listening port
WAIAAS_DAEMON_HOSTNAME=0.0.0.0         # Bind address
WAIAAS_DAEMON_LOG_LEVEL=info            # Log level (trace/debug/info/warn/error)
WAIAAS_DATA_DIR=/data                   # Data directory
WAIAAS_RPC_SOLANA_MAINNET=<url>         # Solana mainnet RPC endpoint
WAIAAS_RPC_EVM_ETHEREUM_MAINNET=<url>   # Ethereum mainnet RPC endpoint

The RPC endpoint variables are where you plug in your own node URLs — Alchemy, QuickNode, your own Geth instance, whatever fits your setup. This is another sovereignty point: you're not locked into any particular RPC provider.

From Container to Working Wallet: The Quick Path

Once the container is running, you need to create a wallet and give your AI agent a session token. This is where the three-layer auth model comes in. There's a master password (for admin operations like creating wallets and setting policies), owner auth (for approving high-stakes transactions via WalletConnect or similar), and session tokens (what your AI agent actually uses for day-to-day operations).

Create a wallet with the master password:

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

Create a session token for your agent:

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

Now your agent can check its balance using just the session token — the master password never touches agent code:

curl http://127.0.0.1:3100/v1/wallet/balance \
  -H "Authorization: Bearer wai_sess_eyJhbGciOiJIUzI1NiJ9..."

This separation matters. The session token is scoped to one wallet, subject to whatever policies you've set, and can be revoked without touching the underlying key material.

Policies: The Safety Layer You Set Once

Self-hosting means you're also responsible for setting the guardrails. WAIaaS has a policy engine with 21 policy types and a default-deny stance: if ALLOWED_TOKENS or CONTRACT_WHITELIST aren't configured, transactions are blocked by default.

A basic spending limit policy looks like this:

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

This creates four tiers of behavior: under $100 executes immediately, $100-$500 executes and notifies you, $500-$2000 waits 15 minutes before executing (giving you a cancellation window), and anything over $2000 requires your explicit approval. You set this once and the daemon enforces it on every transaction your agent submits — no matter what the agent asks for.

The 4 security tiers — INSTANT, NOTIFY, DELAY, and APPROVAL — map to real threat scenarios. An agent that accidentally goes rogue, a bug that causes runaway transactions, or a prompt injection attack that tries to drain a wallet all get caught at different tiers depending on the amount involved.

CLI Alternative: Even Faster Setup

If you prefer the CLI over raw curl commands, the @waiaas/cli package wraps all of this into a few commands:

npm install -g @waiaas/cli
waiaas init --auto-provision     # Generates random master password → recovery.key
waiaas start                     # No password prompt
waiaas quickset                  # Creates wallets + sessions automatically
waiaas set-master                # (Later) Harden password, then delete recovery.key

The CLI has 20 commands covering everything from backup and restore to MCP setup and notification configuration. For anyone who finds curl-based setup tedious, this is the faster path.

Common Operations

docker compose up -d          # Start daemon
docker compose logs -f        # Follow logs
docker compose down           # Stop (data preserved in named volume)
docker compose down -v        # Stop + delete data volume

The interactive API reference is available at http://127.0.0.1:3100/reference once the daemon is running — useful for exploring the 39 REST API route modules without leaving the browser.

Why Self-Hosting Is Actually Practical Now

Three things have changed that make self-hosting crypto wallet infrastructure reasonable in 2026:

Docker has solved the environment problem. The same image runs the same way on a Raspberry Pi 5, a homelab server, or a cloud VPS. You're not debugging library versions or system dependencies.

Auto-provisioning has solved the bootstrap problem. The hardest part of setting up any secrets management service used to be the first run. WAIAAS_AUTO_PROVISION=true eliminates that entirely.

The policy layer handles the "what if the agent goes wrong" problem. The default-deny stance and the 4-tier spending limit system mean you can hand an agent a session token without losing sleep about what it might do with it.

The result is a setup that genuinely takes one afternoon, produces a running system you fully control, and doesn't require ongoing maintenance beyond occasional updates (which Docker handles automatically if you configure Watchtower).

Quick Start Summary

Clone the repo and run docker compose up -d
Add WAIAAS_AUTO_PROVISION=true to your environment or .env file
Retrieve the generated master password from /data/recovery.key
Create a wallet and session token via the REST API or CLI
Set a spending limit policy before handing the session token to your agent

That's the full path from zero to a running, policy-enforced, self-hosted wallet backend.

What's Next

The REST API documentation is auto-generated and available at /reference on your running instance — it's the fastest way to explore what's available across all 39 route modules. If you're planning to connect an AI agent via Claude Desktop or another MCP-compatible framework, the 45 MCP tools in @waiaas/mcp are the next thing to look at. And if you want to go deeper on keeping your agent's spending within safe boundaries, the full policy engine — all 21 policy types — is worth reading through before you go to production.

The project is on GitHub at https://github.com/minhoyoo-iotrust/WAIaaS and the official site is at https://waiaas.ai. Both are good starting points depending on whether you want to read code or documentation first.

The Payment Layer for Autonomous AI: Building Economic Infrastructure for Agent Commerce

Wallet Guy — Sat, 20 Jun 2026 09:46:23 +0000

The Payment Layer for Autonomous AI: Building Economic Infrastructure for Agent Commerce

AI agents will need to pay for compute, data, and API calls — and the infrastructure to let them do that autonomously exists today. Not as a concept paper, not as a whitepaper with a 2027 roadmap, but as working, self-hosted software you can run in a Docker container this afternoon. The question isn't whether AI agents will participate in economic activity. The question is what the payment layer looks like when they do.

The Problem Nobody Is Talking About Yet

There's a gap in how we build AI agent systems that becomes obvious the moment an agent needs to do something that costs money.

Today, when an AI agent needs to call a paid API, swap tokens, pay for compute, or move funds on behalf of a user, one of a few things happens: a human manually approves every transaction, the agent uses a shared custodied account that nobody really controls, or the whole capability gets punted — "we'll add payments later."

None of these are good answers. The first doesn't scale. The second is a security nightmare. The third means your agent is fundamentally limited to free operations.

The deeper issue is structural. We've built incredible reasoning and planning capabilities into AI agents, but we haven't built the economic infrastructure that would let them act on those plans when acting costs money. An agent that can identify the best DeFi yield opportunity but can't execute a swap isn't an autonomous agent — it's an expensive suggestion engine.

What Autonomous Wallet Infrastructure Actually Requires

Let's be specific about what "a wallet for an AI agent" actually needs to do, because it's more than just holding keys.

The agent needs to act independently within defined limits. This is the core tension. You want the agent to be able to execute transactions without asking for human permission every time — that's the whole point. But you also need hard guarantees about what it can and can't do. These aren't contradictory requirements; they need a policy engine that enforces rules at the infrastructure layer, not at the application layer.

The human owner needs real oversight without becoming a bottleneck. There's a spectrum between "approve every transaction" and "trust the agent completely." Good infrastructure needs to support the whole spectrum — instant execution for small trusted operations, notifications for medium operations, time delays for large operations, and mandatory human approval for anything above a threshold.

The infrastructure needs to speak the protocols that autonomous payments require. Agents paying for API calls need HTTP-level payment protocols. Agents operating across chains need cross-chain bridging. Agents using DeFi need protocol integrations that understand lending, staking, and swaps.

Everything needs to be auditable. When an agent takes an economic action, there needs to be a complete record. Not for regulatory compliance (though that matters too) — for debugging, for trust-building, and for the basic engineering requirement of knowing what your system did and why.

WAIaaS is built around exactly these requirements. It's an open-source, self-hosted Wallet-as-a-Service designed specifically for the case where AI agents are the primary actors.

The Three-Layer Security Model

The security architecture in WAIaaS reflects a specific philosophy: agents should be able to act autonomously, but within hard limits that humans set and can always override.

There are three authentication tiers, each representing a different principal:

# 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>"

The master password is for the system operator — creating wallets, managing sessions, configuring policies. Think of it as the infrastructure admin role.

The session token is what the AI agent holds. It can execute transactions, query balances, call DeFi protocols — but only within whatever policies the master has configured. This is the credential your agent code uses.

The owner signature is cryptographic proof from the human who owns the funds — using SIWS (Solana) or SIWE (Ethereum). This can't be faked by software. It's the human's key, and it's what's required to approve transactions that exceed the agent's autonomous limits or to trigger recovery.

This maps cleanly onto the actual principals in an AI agent system. The operator who deploys the agent isn't the same person as the end user who owns the funds, and the agent itself is a third party that neither fully trusts.

The Policy Engine: Programmable Limits

The policy system is where the interesting infrastructure work lives. WAIaaS supports 21 policy types with 4 security tiers — and it operates with default-deny semantics.

Default-deny means if you haven't explicitly allowed something, it's blocked. An agent without an ALLOWED_TOKENS policy configured can't transfer tokens. An agent without a CONTRACT_WHITELIST can't call contracts. This is the right default for autonomous systems where mistakes are expensive and irreversible.

The four security tiers map to the spectrum from "execute immediately" to "require human approval":

INSTANT   — Execute immediately, no notification
NOTIFY    — Execute immediately, send notification
DELAY     — Queue for delay_seconds, then execute (cancellable)
APPROVAL  — Require human approval via WalletConnect/Telegram/Push

A SPENDING_LIMIT policy assigns tiers based on transaction amount:

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

With this configuration, a $50 transaction executes immediately. A $300 transaction executes with a notification. A $1,500 transaction queues for 15 minutes before executing — giving the owner time to cancel if something looks wrong. Anything over $2,000 requires explicit human approval.

This isn't just spending limits. The full policy set covers DeFi-specific risks:

LENDING_LTV_LIMIT — caps the loan-to-value ratio an agent can take on in lending protocols
PERP_MAX_LEVERAGE — prevents an agent from opening overleveraged perpetual futures positions
PERP_MAX_POSITION_USD — hard cap on position size
APPROVED_SPENDERS — controls which contracts can be approved to spend tokens (critical for preventing drainer approvals)
REPUTATION_THRESHOLD — ERC-8004 onchain reputation gating

These aren't generic finance policies bolted onto a crypto wallet. They reflect the specific risk surface of autonomous agents operating in DeFi.

x402: The HTTP Payment Protocol

One of the most interesting capabilities in WAIaaS is x402 support — an HTTP payment protocol where AI agents automatically pay for API calls.

The x402 protocol works at the HTTP level. When an agent requests a resource that requires payment, the server returns a 402 Payment Required response. The agent's wallet infrastructure handles the payment automatically and retries the request with proof of payment.

From the agent's perspective, this is a transparent operation. The agent calls an API; the wallet layer handles the economics. This is exactly the right abstraction for autonomous systems — the agent shouldn't need to know about payment mechanics any more than it needs to know about TCP/IP.

For a developer building an agent that consumes paid APIs, the MCP tool x402-fetch exposes this capability directly, and the TypeScript SDK includes x402Fetch() for programmatic use. The policy type X402_ALLOWED_DOMAINS lets you define a whitelist of domains where automatic payment is permitted — so the agent can't be tricked into paying for arbitrary endpoints.

This is the infrastructure primitive that makes "agents that pay for what they use" real. Not a concept. Working today.

DeFi as a Native Capability

WAIaaS integrates 15 DeFi protocol providers. For an autonomous agent, this means DeFi operations aren't special cases that require custom integration work — they're just actions the agent can take through the standard session token interface.

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 integrated protocols cover the major categories of DeFi activity: swaps (Jupiter, ZeroX, D'CENT, LI.FI), cross-chain bridging (LI.FI, Across), lending (Aave v3, Kamino), liquid staking (Lido for EVM, Jito for Solana), perpetual futures (Hyperliquid, Drift), yield (Pendle), and prediction markets (Polymarket). All of this is available through the same session token your agent already holds.

The 7-stage transaction pipeline handles the full lifecycle: validation → authentication → policy check → wait (for delay-tier transactions) → execute → confirm. The gas conditional execution feature means transactions can be queued to execute only when gas prices meet a threshold — useful for agents that are cost-sensitive about when they execute.

Connecting Agents to Wallets: Three Integration Paths

WAIaaS supports three ways for an agent to interact with its wallet, depending on how you're building.

MCP (Model Context Protocol) is the integration path for conversational AI like Claude. WAIaaS provides 45 MCP tools covering wallet operations, transactions, DeFi, NFTs, and x402 payments. Setup is a single command:

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

After that, Claude can check balances, send tokens, and execute DeFi actions directly from conversation. The MCP tools enforce the same policy engine — Claude can't do anything the agent's session token isn't authorized to do.

The TypeScript and Python SDKs are the path for agents built in code. The TypeScript SDK (@waiaas/sdk) has 40+ methods. The Python SDK (waiaas) is async/await native. Both are zero-external-dependency libraries:

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();
const tx = await client.sendToken({
  to: 'recipient-address...',
  amount: '0.1',
});

The REST API is the path for any agent framework or language. The 39 API route modules cover everything from wallet management to DeFi positions to NFT operations. There's an OpenAPI 3.0 spec auto-generated at /doc and an interactive Scalar API reference at /reference — so any agent framework with HTTP capability can integrate without a dedicated SDK.

Running It: Self-Hosted in Minutes

Self-hosted is a deliberate choice in WAIaaS's design. For agents handling real economic activity, the infrastructure should be under the operator's control. Keys, transaction history, and policy configuration don't belong in someone else's cloud.

The deployment path is straightforward:

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

The Docker image is ghcr.io/minhoyoo-iotrust/waiaas:latest, binding to 127.0.0.1:3100 by default — localhost only, not exposed to the internet. The entrypoint supports auto-provisioning for unattended deployments:

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

docker exec waiaas cat /data/recovery.key

For production, Docker Secrets overlay via docker-compose.secrets.yml keeps credentials out of environment variables. The image runs as a non-root user (UID 1001) with a built-in healthcheck.

The CLI adds an operational layer on top:

npm install -g @waiaas/cli
waiaas init                        # Create data directory + config.toml
waiaas start                       # Start daemon
waiaas quickset --mode mainnet     # Create wallets + MCP sessions in one step

The 20 CLI commands cover the full operational lifecycle: wallet creation, session management, backup and restore, status monitoring, MCP setup, and notification configuration.

The Infrastructure That Doesn't Exist Without This

Here's what becomes possible when agents have autonomous wallet infrastructure with proper policy enforcement:

An agent that manages a treasury can rebalance positions based on market conditions, staying within per-protocol limits and daily spend caps, notifying the owner for anything unusual, and requiring explicit approval for anything large. No human needs to approve each rebalance — but no agent can go rogue either.

An agent that consumes paid APIs can handle the economics transparently through x402, paying only domains on the approved list, within spending limits the owner set. The agent focuses on its actual task; the wallet layer handles payments.

An agent operating across chains can bridge assets, stake for yield, and execute swaps — all through the same credential, with the same policy enforcement, across the 18 networks WAIaaS supports.

None of this requires trusting the agent with unconstrained access. The policy engine enforces limits at the infrastructure layer. The three-tier auth model keeps humans in control of the limits while letting agents execute autonomously within them.

Quick Start: Agent Wallet in Five Steps

Deploy the daemon — docker compose up -d after cloning the repo
Create a wallet — curl -X POST http://127.0.0.1:3100/v1/wallets -H "X-Master-Password: ..." -d '{"name": "agent-wallet", "chain": "solana", "environment": "mainnet"}'
Set policies — Configure SPENDING_LIMIT and ALLOWED_TOKENS before creating sessions
Create a session — curl -X POST http://127.0.0.1:3100/v1/sessions -H "X-Master-Password: ..." — this gives you the session token your agent holds
Connect your agent — Use the MCP integration, SDK, or REST API with the session token

The agent can now execute transactions within the policy limits you set. The owner can monitor and approve. The infrastructure enforces the rules.

What's Next

The economic infrastructure for autonomous AI agents isn't a future problem — it's a present one, and the building blocks are available now. WAIaaS is open-source, self-hosted, and production-capable: explore the full codebase and contribute at GitHub, and see documentation and deployment guides at waiaas.ai. If you're building agents that need to participate in economic activity, this is the layer worth understanding today — because the agents that can pay for what they use will do things the ones that can't simply cannot.

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

Wallet Guy — Fri, 19 Jun 2026 16:13:20 +0000

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

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

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

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

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

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

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

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

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

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

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

39 REST API Routes: How We Built Comprehensive Wallet Control for Trading Bots

Wallet Guy — Fri, 19 Jun 2026 11:00:03 +0000

39 REST API Routes: How We Built Comprehensive Wallet Control for Trading Bots

Your trading bot spotted the arbitrage opportunity — the price gap is there, the math checks out, but can it actually execute before the block closes? Reliable wallet infrastructure is the unglamorous part of trading bot development that determines whether your strategy lives or dies in production. WAIaaS is an open-source, self-hosted Wallet-as-a-Service that gives trading bots a complete REST API with built-in risk controls, multi-protocol DeFi access, and the execution primitives you actually need.

Why Wallet Infrastructure Is the Hard Part

Most trading bot tutorials stop at strategy. They show you how to detect a price discrepancy on Jupiter versus another DEX, and then wave their hands at "signing and sending a transaction." In production, that hand-wave collapses into a pile of problems: gas spikes eating your margins, unsigned approvals blocking execution, no way to simulate before committing, and a single compromised key wiping out everything your bot has earned.

The infrastructure layer needs to handle gas optimization, policy enforcement, transaction simulation, and multi-protocol execution — and it needs to do all of that without becoming the bottleneck in your execution path. That's the problem WAIaaS was built to solve.

39 API Routes Covering Every Trading Primitive

WAIaaS exposes 39 REST API route modules. For a trading bot, that full surface area matters because different trading scenarios need different primitives. Let's walk through the ones that matter most.

Authentication: Three Layers for Three Roles

WAIaaS separates concerns cleanly with three authentication methods:

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

# sessionAuth — AI agent or trading bot (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>"

Your trading bot runs exclusively on sessionAuth. It never touches the master password. This means a compromised bot session has bounded blast radius — it can only operate within the policies you've configured for that session, and you can revoke it instantly without affecting the underlying wallet or other sessions.

Step 1: Create the Trading Wallet

Before your bot executes a single trade, you set up the wallet once using masterAuth:

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

Then create a session token that your bot will use for every subsequent request:

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

From this point, your bot operates entirely with the returned session token. The wallet creation and session management are one-time setup steps — your hot path only uses sessionAuth.

Gas Conditional Execution: Only Trade When Gas Is Cheap

One of the most practical features for any bot running on EVM chains is gas conditional execution. WAIaaS has a dedicated pipeline stage (stage-gas-condition) that holds a transaction in queue until the gas price meets your configured threshold. Your bot submits the transaction, and the daemon handles the gas monitoring — you're not writing a polling loop.

For MEV bots and arbitrage strategies with thin margins, this is the difference between a profitable trade and a loss. You define the acceptable gas ceiling in your policy, and the execution engine enforces it automatically.

15 DeFi Protocols, One Wallet

This is where WAIaaS gets interesting for multi-leg strategies. WAIaaS integrates 15 DeFi protocol providers: aave-v3, across, dcent-swap, drift, erc8004, hyperliquid, jito-staking, jupiter-swap, kamino, lido-staking, lifi, pendle, polymarket, xrpl-dex, and zerox-swap.

For a Solana-based bot, you can swap on Jupiter in the same session you use to open a Drift perpetual:

# Leg 1: Swap SOL → USDC on Jupiter
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 Hyperliquid integration covers perpetual futures, spot trading, and sub-accounts. The cross-chain story is handled by LI.FI and Across, both integrated as first-class DeFi providers. Swap on Solana, hedge the exposure on an EVM chain, bridge the collateral — all through the same session token, same API surface, same policy enforcement layer.

Simulate Before You Execute

Trading bots that don't simulate are trading bots that occasionally blow up. WAIaaS has a dry-run API baked into the transaction route:

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 dryRun: true flag runs the transaction through the full 7-stage pipeline — validation, auth, policy check, gas conditions — without committing to the chain. Your bot can verify that a planned execution would actually pass all policy gates before spending gas on a transaction that was going to get blocked anyway.

The 7-stage pipeline is: validate → auth → policy → wait → execute → confirm. Every transaction goes through all of these stages. Simulation gives you deterministic pipeline output without the on-chain side effect.

Policy Engine: Risk Controls That Run Before Every Trade

The policy engine has 21 policy types with 4 security tiers (INSTANT, NOTIFY, DELAY, APPROVAL) and enforces default-deny on token transfers and contract calls. For a trading bot, the most relevant policies are:

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

The tier assignment is deterministic: transaction value ≤ instant_max_usd executes immediately, ≤ notify_max_usd executes with a notification, ≤ delay_max_usd queues for delay_seconds before executing (and can be cancelled in that window), and anything above that requires explicit owner approval.

For a bot you want running autonomously, you set instant_max_usd to the maximum trade size you're comfortable with the bot executing without any human in the loop. Large unexpected transactions hit the DELAY or APPROVAL tier automatically.

Beyond SPENDING_LIMIT, the policy types most relevant to trading bots are:

CONTRACT_WHITELIST — default-deny contract calls. Your bot can only interact with protocols you've explicitly whitelisted. A compromised session can't drain funds into an arbitrary contract.
ALLOWED_TOKENS — default-deny token transfers. Only the tokens you've listed can be moved.
PERP_MAX_LEVERAGE — hard cap on perpetual futures leverage, enforced at the API layer before the order reaches the protocol.
PERP_MAX_POSITION_USD — maximum position size in USD across perp markets.
PERP_ALLOWED_MARKETS — restrict which perpetual markets the bot can trade.
RATE_LIMIT — maximum transactions per period, useful for preventing runaway execution loops.
VENUE_WHITELIST — restrict which trading venues the bot can route through.

The default-deny enforcement means ALLOWED_TOKENS and CONTRACT_WHITELIST block all transfers and contract calls unless explicitly configured. This is the correct default for a bot wallet — not permissive until locked down, but locked down until explicitly opened.

Batch Transactions for Multi-Leg Strategies

The transaction schema supports 7 types in a discriminated union: Transfer, TokenTransfer, ContractCall, Approve, Batch, NftTransfer, and ContractDeploy. The Batch type lets you bundle multiple operations into a single atomic submission — useful for strategies that need to approve a spender and execute a swap in the same block, or open a position and set a stop-loss simultaneously.

Checking Balance Before Every Trade

Your bot's execution loop almost certainly starts with a balance check:

curl http://127.0.0.1:3100/v1/wallet/balance \
  -H "Authorization: Bearer wai_sess_eyJhbGciOiJIUzI1NiJ9..."

The TypeScript SDK wraps all of these calls with type safety and async/await ergonomics:

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'],
});

// Check balance before attempting execution
const balance = await client.getBalance();
console.log(`Balance: ${balance.balance} ${balance.symbol} (${balance.chain}/${balance.network})`);

// Send tokens
const sendResult = await client.sendToken({
  type: 'TRANSFER',
  to: 'recipient-address',
  amount: '0.001',
});
console.log(`Transaction submitted: ${sendResult.id} (status: ${sendResult.status})`);

// Poll for confirmation
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(`Confirmed! Hash: ${tx.txHash}`);
    break;
  }
  if (tx.status === 'FAILED') {
    console.error(`Failed: ${tx.error}`);
    break;
  }
  await new Promise(resolve => setTimeout(resolve, 1000));
}

Error codes from the API are structured and machine-readable:

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

POLICY_DENIED with retryable: false means your bot should not retry — the transaction was blocked by a policy rule. INSUFFICIENT_BALANCE and TOKEN_EXPIRED are also first-class error codes your execution loop can handle explicitly.

ERC-4337 Account Abstraction for Gasless Execution

For EVM bots, WAIaaS supports ERC-4337 Account Abstraction with a dedicated UserOp build/sign API. This means gasless transactions and smart account execution — your bot can execute strategies without holding the native gas token, relying instead on a paymaster. The build-userop and sign-userop tools are available both via REST and through the 45 MCP tools.

x402: Paying for API Calls Automatically

The x402 HTTP payment protocol support deserves a mention for bots that consume paid data APIs. When your bot hits an API endpoint that returns an HTTP 402 Payment Required, WAIaaS can handle the micropayment automatically using the x402-fetch route. Combined with X402_ALLOWED_DOMAINS policy, you whitelist which API domains the bot is allowed to pay, and the payment flow is fully automated.

Quick Start for Trading Bot Developers

Getting WAIaaS running for a trading bot takes five steps:

1. Start the daemon with Docker:

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

docker exec waiaas cat /data/recovery.key

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: <from-recovery.key>" \
  -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: <from-recovery.key>" \
  -d '{"walletId": "<wallet-uuid>"}'

3. Set policies before funding the wallet:

Configure SPENDING_LIMIT, ALLOWED_TOKENS, and CONTRACT_WHITELIST policies as shown above. Default-deny enforcement means you must set ALLOWED_TOKENS and CONTRACT_WHITELIST before the bot can transact.

4. Install the SDK and point it at your daemon:

npm install @waiaas/sdk

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

5. Explore the interactive API reference:

open http://127.0.0.1:3100/reference

The OpenAPI 3.0 spec is auto-generated at /doc and the interactive Scalar API reference is at /reference — useful for exploring the full 39 route surface without reading source code.

What's Next

The full API surface — all 39 route modules with request/response schemas — is available interactively at /reference once you have the daemon running. The GitHub repository has the complete source for the policy engine, pipeline stages, and all 15 DeFi protocol integrations if you want to understand exactly what happens between your bot's API call and the on-chain transaction.

If you're building a trading bot that needs wallet infrastructure that doesn't get in the way of your strategy, start here:

GitHub: https://github.com/minhoyoo-iotrust/WAIaaS
Official site: https://waiaas.ai