Auto-Generated OpenAPI 3.0 Spec: Interactive API Reference for AI Agent Wallets

2026-04-08

Building AI agents that can actually handle money is trickier than you think. Your Claude agent can browse the web, write code, and manage files — but when it comes to blockchain transactions, token swaps, or DeFi operations, you're stuck building custom wallet integrations from scratch. WAIaaS changes that by providing auto-generated OpenAPI 3.0 specifications and interactive API documentation, making it dead simple to give your AI agents proper wallet capabilities.

Why Traditional Wallet APIs Don't Work for AI Agents

Most blockchain APIs are built for human developers, not autonomous agents. You end up juggling multiple SDKs, managing private keys, handling gas estimation, and writing custom retry logic for failed transactions. Even worse, there's no standardized way to add spending limits, approval workflows, or audit trails — all critical when an AI agent controls real funds.

The result? Developers either skip blockchain features entirely or spend months building wallet infrastructure instead of focusing on their agent's core intelligence.

Auto-Generated OpenAPI Spec: Your AI Agent's Wallet Blueprint

WAIaaS solves this with a comprehensive REST API that includes auto-generated OpenAPI 3.0 specifications. The daemon automatically generates complete API documentation at /doc and serves an interactive reference UI at /reference, giving you everything needed to integrate wallet functionality into any AI agent framework.

Here's what the OpenAPI spec covers:

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

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

The spec includes 39 REST API route modules covering everything from basic balance queries to complex DeFi operations across 15 integrated protocols. Each endpoint includes request/response schemas, authentication requirements, and error codes — perfect for AI agent frameworks that can consume OpenAPI specifications directly.

Interactive API Reference: Test Before You Build

The interactive Scalar API reference UI at /reference lets you test every endpoint directly in your browser. This is invaluable when building AI agents because you can verify the exact request/response format before writing integration code.

For example, here's how simple it is to check a wallet balance:

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

The response format is documented in the OpenAPI spec, making it trivial for AI agents to parse:

{
  "balance": "1.5",
  "symbol": "SOL",
  "chain": "solana",
  "network": "mainnet",
  "usd_value": 225.50
}

Three-Layer Authentication for AI Agent Security

WAIaaS implements a three-layer authentication system designed specifically for AI agents:

masterAuth — System administration (wallet creation, policy management)
sessionAuth — AI agent operations (transactions, balance queries)
ownerAuth — Human oversight (approvals, kill switches)

# Create a session for your AI agent (masterAuth)
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 returned can be used by your AI agent for all transactions, while the human owner retains ultimate control through approval workflows.

Policy Engine: 21 Rule Types for Safe AI Agent Operations

The OpenAPI spec documents WAIaaS's policy engine with 21 policy types and 4 security tiers: INSTANT, NOTIFY, DELAY, and APPROVAL. This lets you configure exactly what your AI agent can do autonomously versus what requires human approval.

# Create spending limits for your AI agent
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 policy system ensures your AI agent can handle routine transactions instantly while routing larger operations through appropriate human oversight.

DeFi Integration: 15 Protocols Ready to Use

The OpenAPI spec includes endpoints for 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.

Your AI agent can execute complex DeFi operations with simple REST calls:

# Execute a Jupiter swap on Solana
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"
  }'

Error Handling: Structured Responses for AI Agents

The OpenAPI spec documents a consistent error format that AI agents can easily parse and respond to:

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

This structured approach lets your AI agent handle different error scenarios appropriately — retrying network failures but escalating policy violations to human operators.

Multi-Chain Support: EVM and Solana

The OpenAPI spec covers 2 chain types (solana, evm) with 18 networks, letting your AI agent operate across multiple blockchains with the same API interface. No need to learn different SDKs for each chain — WAIaaS handles the complexity.

Quick Start: OpenAPI Integration in 4 Steps

Here's how to integrate WAIaaS's OpenAPI spec into your AI agent:

Start WAIaaS daemon:

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

Download the OpenAPI spec:

curl http://127.0.0.1:3100/doc -o waiaas-openapi.json

Generate client code (optional, for typed languages):

# Generate TypeScript client
openapi-generator-cli generate -i waiaas-openapi.json -g typescript-axios -o ./waiaas-client

Test the interactive reference:

open http://127.0.0.1:3100/reference

Your AI agent framework can now consume the OpenAPI spec directly, giving it instant access to wallet functionality across multiple blockchains.

Beyond Basic Transactions: Advanced Capabilities

The OpenAPI spec includes advanced features like:

x402 HTTP payment protocol — AI agents can pay for API calls automatically
ERC-4337 Account Abstraction — Gasless transactions and batch operations
NFT operations — ERC-721/ERC-1155 and Solana Metaplex support
Cross-chain bridging — Move funds between networks automatically
Transaction simulation — Test operations before execution

These capabilities are all documented in the OpenAPI spec, making them accessible to any AI agent framework.

Real-World Integration Examples

The interactive API reference shows exactly how AI agents can:

Monitor incoming deposits with real-time notifications
Execute complex multi-step DeFi strategies
Handle failed transactions with appropriate retry logic
Maintain audit trails for compliance
Implement spending controls and approval workflows

Each endpoint in the spec includes practical examples your AI agent can adapt.

What's Next

The auto-generated OpenAPI 3.0 spec makes WAIaaS the fastest way to add blockchain capabilities to any AI agent. Download the spec, explore the interactive reference, and start building agents that can actually handle money.

Ready to give your AI agent a wallet? Check out the WAIaaS GitHub repository for installation instructions, or visit waiaas.ai to learn more about the platform's capabilities.